內容匯入 | EmDash CMS Everything

EmDash 透過位於 /_emdash/admin/import/wordpress 的 Import from WordPress 頁面匯入 WordPress 內容。匯入器可以分析 WordPress eXtended RSS（WXR）檔案，也可以連線到執行 EmDash Exporter 外掛程式的站台。

匯入來源

來源登錄表中包含三個 WordPress 來源：

來源 ID	輸入	匯入內容	存取範圍
`wxr`	WordPress 匯出的 `.xml` 檔案	是	匯出檔中包含的資料
`wordpress-plugin`	站台 URL 加 EmDash Exporter 憑證	是	匯出器端點，包括需要驗證的內容
`wordpress-rest`	公開的站台 URL	否	僅探測和公開數量統計

不存在 wordpress-com OAuth 匯入來源。WordPress.com 站台必須使用 WXR 匯出，或相容的 EmDash Exporter 連線。

匯入 WXR 檔案

當 WordPress 可以匯出你所需的內容、且無法安裝 EmDash Exporter 時，請使用 WXR。

在 WordPress 中開啟 Tools → Export，選擇所需內容，並下載 XML 檔案。
在 EmDash 中，選擇管理後台側邊欄中的 Import 並上傳該檔案。
在建立結構描述或內容之前，檢查偵測到的文章類型、欄位、作者、分類法、可重複使用區塊和附件 URL。

XML 包含附件中繼資料和來源 URL，不包含媒體的位元組內容。在選用的媒體複製完成之前，請保持 WordPress 可存取。

連線 EmDash Exporter

當你掌控該 WordPress 站台、並且需要草稿或受支援設定等需要驗證的資料時，請使用匯出器。留言、選單、標誌、網站圖示，以及用於產生遷移金鑰的 Tools → EmDash Migration 頁面，都需要匯出器 1.2.0 或更新版本。任何版本的匯出器都可以使用 WordPress 使用者名稱和應用程式密碼進行連線。匯出器透過其 emdash/v1 API 端點傳送資料；它不會授予 EmDash 對資料庫的直接存取權限。

管理後台匯入流程

管理後台依序執行以下階段：

連線。 上傳 WXR 檔案、貼上 EmDash Exporter 遷移金鑰，或輸入站台 URL。
分析。 讀取文章類型、必填欄位、作者、附件和結構描述相容性。
檢閱。 選擇文章類型、集合對映、作者和受支援的附加項。
準備。 建立缺少的集合和欄位。型別不相容的現有欄位會阻擋該對映。
匯入。 轉換並建立內容。匯出器路徑對內容、留言和收尾階段使用有大小限制的請求。
複製媒體。 將所選 WXR 附件下載到 EmDash 儲存空間中，並改寫相符的 URL。

WXR 路徑可以匯入文章、頁面、自訂文章類型、分類法、可重複使用區塊、作者或訪客 byline，以及匯出檔中列出的媒體。匯出器路徑還可以從線上的 WordPress API 取得所選站台設定和受支援的 SEO 值；使用匯出器 1.2.0 或更新版本時，還可以取得留言、選單、標誌和網站圖示。

理解分析結果

對於偵測到的每個文章類型，檢閱介面會顯示建議的集合以及四種結構描述狀態之一：

狀態	含義
Ready	集合和必填欄位已經具有相容的型別
New collection	準備步驟將建立該集合及其必填欄位
Add fields	集合已存在，準備步驟將新增缺少的欄位
Incompatible	現有欄位的型別不同；請在匯入該文章類型之前修正對映或結構描述

準備步驟只做增量新增。它不會為了讓匯入適配而變更現有欄位的型別。

狀態對映

內容路由會儲存 WordPress 匯入中的兩種狀態：

WordPress 狀態	EmDash 狀態
`publish`	`published`
`draft`	`draft`
`pending`	`draft`
`private`	`draft`
`future`、`trash` 或其他值	`draft`

匯入器不會保留 WordPress 中待審、私密、排程發佈或資源回收筒的語意。在 EmDash 中發佈這些條目之前，請先檢查它們。

內容與識別碼

WXR 來源和匯出器來源會將 Gutenberg 標記轉換為 Portable Text。它們將 post 對映到 posts，將 page 對映到 pages，並將已知的自訂文章類型對映到集合 slug。WordPress 的內部文章類型會被排除。可重複使用區塊（wp_block）會作為 EmDash 的 sections 處理，而不是一般條目。

對於一個匯入的條目：

如果可用，WordPress 文章的 slug 會成為 EmDash 的 slug。
EmDash 會產生自己的資料庫 ID。
作者對映會關聯一個 EmDash 使用者。未對映的 WordPress 作者可以變成可重複使用的訪客 byline。
WordPress ID 僅被暫時用於解析選單、留言、精選圖片和翻譯等關聯。它們不是用於偵測現有 WXR 條目的持久識別。

使用 skipExisting 重新執行 WXR 時，會依集合、slug 和地區設定比對現有條目。因此，slug 發生變化可能會建立另一個條目。匯出器路徑使用相同的 slug 與地區設定檢查，並根據其略過的條目重建 WordPress ID 關聯對映。

媒體複製與去重

媒體階段會下載每個附件 URL，計算已下載位元組內容的 SHA-1 雜湊，並尋找具有該內容雜湊的現有媒體資料列。即使 WordPress URL 不同，位元組完全相同的內容也會重複使用現有的媒體記錄。

雜湊以 sha1: 前綴儲存。它是去重鍵，而不是安全簽章。兩個 URL 不會僅僅因為檔名相同而被視為重複。

複製媒體之後，匯入器會改寫 Portable Text、文字、字串、圖片和檔案欄位中相符的 URL。在驗證下載和改寫後的頁面之前，請保持 WordPress 來源在線。

重試行為

管理後台不會為 WXR 匯入儲存持久的還原權杖。如果某個請求失敗：

在啟用 skip existing 的情況下重新執行分析和匯入。
現有條目會依集合、slug 和地區設定被略過。
對於已經儲存的檔案，重新執行媒體步驟是安全的，因為位元組完全相同的下載會重複使用內容雜湊。
重試之前，請檢查部分完成的結構描述變更以及 slug 發生變化的條目。

匯出器流程被分塊處理，以適應 Worker 的限制。瀏覽器在請求之間攜帶游標以及 WordPress 到 EmDash 的關聯對映。如果瀏覽器遺失了該狀態，請重新開始匯入；被略過的條目會在處理內容頁面時重建關聯對映。

獨立的 emdash import wordpress CLI 會將轉換後的 JSON 檔案寫入輸出目錄。它的 --resume 選項會讀取 .wp-migration-progress.json，並略過其中已記錄的 WordPress 文章和附件 ID。這個檔案轉換工作流程不是管理後台的資料庫匯入，也不會讓管理後台的請求變得可還原。

管理後台 API 契約

這些端點為需要驗證的管理後台頁面提供支援。它們需要具有 import:execute 權限的管理員工作階段，以及 X-EmDash-Request: 1 請求標頭。成功回應通常使用 { "success": true, "data": ... } 信封；錯誤使用 { "success": false, "error": { "code", "message" } }。

探測 URL

POST /_emdash/api/import/probe 接受 JSON { "url": "https://example.com" }。

它的 data 值是 { success: true, result }。result 包含 url、isWordPress、bestMatch 和 allMatches。僅符合一般的 WordPress REST 時，會建議上傳 WXR；它不會啟用直接的 REST 匯入。

分析 WXR 檔案

POST /_emdash/api/import/wordpress/analyze 接受帶有 file 部分的 multipart/form-data。它的 data 值包含站台、文章類型分析、附件摘要、作者摘要、分類法數量以及自訂欄位建議。

準備結構描述

POST /_emdash/api/import/wordpress/prepare 接受如下 JSON 結構：

{
  "postTypes": [
    {
      "name": "post",
      "collection": "posts",
      "fields": [
        {
          "slug": "title",
          "label": "Title",
          "type": "string",
          "required": true,
          "searchable": true
        }
      ]
    }
  ]
}

它的 data 值包含 success、collectionsCreated、fieldsCreated 以及每個集合的 errors。

執行 WXR 匯入

POST /_emdash/api/import/wordpress/execute 接受包含以下部分的 multipart/form-data：

file：WXR 檔案。
config：一個 JSON 字串，包含 postTypeMappings、skipExisting、選用的 authorMappings、選用的 importSections，以及選用的整個匯入範圍的 locale。

它的 data 值包含 success、imported、skipped、errors、byCollection，以及選用的 sections 和分類法摘要。

複製媒體

POST /_emdash/api/import/wordpress/media 接受 JSON { "attachments": [...], "stream": true }。預設啟用串流。串流回應是以換行分隔的 JSON，先是 progress 記錄，最後是一筆 result 記錄；它不使用一般的 API 信封。將 stream 設定為 false，即可收到包裹著 { imported, failed, urlMap } 的一般信封。

改寫媒體 URL

POST /_emdash/api/import/wordpress/rewrite-urls 接受 JSON { "urlMap": { "old": "new" }, "collections": ["posts"] }。選用的集合清單用於限制改寫範圍。它的 data 值包含已更新的條目數量和已改寫的 URL 數量，以及錯誤資訊。

使用匯出器 API

POST /_emdash/api/import/wordpress-plugin/analyze 接受 JSON { "url", "token" }，其中 token 是 WordPress 使用者和應用程式密碼的 Base64 基本驗證值。它的 data 值是 { success: true, analysis }。

POST /_emdash/api/import/wordpress-plugin/execute 接受包含 url、token 和 config 的 JSON。管理後台還會提供 phase（content、comments 或 finalize）。每個回應包含 done、選用的下一個 cursor、部分 result，以及一個 chunk 物件，其中帶有任何更新後的 idMap、translationGroups 或 commentRoots。管理後台會合併 chunk 中的值，並在下一個請求中傳送累積的對映。

疑難排解

偵測到站台但無法直接匯入

wordpress-rest 結果只是一次探測。請上傳 WXR 檔案，或安裝 EmDash Exporter 後再次探測該站台。

文章類型不相容

在檢閱介面中展開該文章類型，找到衝突的欄位。變更目標集合，或在 Content Types 中調和該欄位。匯入器不會取代現有欄位的型別。

部分媒體失敗

最終的媒體結果會列出失敗的來源 URL。請確認每個 URL 是公開的、仍然存在，並且不會重新導向到私有網路位址。修正存取問題後重試媒體步驟；已完成的、位元組完全相同的檔案會被重複使用。

下一步

操作流程請參見從 WordPress 遷移。
內容匯入完成後，請參見移植 WordPress 主題。
當站台依賴自訂行為時，請參見移植 WordPress 外掛程式。