從 WordPress 遷移

使用 EmDash 管理後台分析 WordPress 站台、準備相容的集合、匯入內容、複製媒體並改寫 URL。在匯入後的站台通過驗證之前，請保持 WordPress 站台可用。

開始之前

請準備以下項目：

• WordPress 資料庫和 wp-content/uploads 的備份。
• 如果打算複製媒體，需要一個已設定儲存空間的 EmDash 站台。
• 一個 EmDash 管理員帳號。WordPress 匯入需要 import:execute 權限。
• 完整的 WordPress eXtended RSS（WXR）匯出檔，或在 WordPress 站台上安裝的 EmDash Exporter 外掛程式。

記錄目前的永久連結結構、正規來源、重新導向、選單、啟用的文章類型、分類法，以及新站台必須保留的外掛程式自有欄位。

選擇匯入方式

在沒有匯出器的情況下輸入站台 URL，只會探測公開的 WordPress REST API。該探測可以偵測到 WordPress，並統計公開的文章、頁面和媒體數量，但無法執行直接的 REST 匯入。

匯出 WXR 檔案

在 WordPress 中開啟 Tools → Export，選擇 All content，然後下載 XML 匯出檔。WXR 檔案指向 WordPress 來源上的媒體；它不包含附件的位元組內容。

連線 EmDash Exporter

請在 WordPress 的 Plugins 頁面查看匯出器的版本。留言、選單、標誌和網站圖示需要匯出器 1.2.0 或更新版本。使用更早的版本時，匯入會在沒有這些內容的情況下完成，也不會把它們回報為缺失。

使用匯出器 1.2.0 或更新版本時，請在 WordPress 中開啟 Tools → EmDash Migration 並產生遷移金鑰。把金鑰貼到 EmDash 匯入頁面中。

無論匯出器是哪個版本，你都可以輸入 WordPress 站台 URL。偵測到匯出器後，透過 WordPress 的應用程式密碼頁面授權 EmDash。在本機 HTTP 開發站台上，由於授權回呼需要 HTTPS，請手動輸入 WordPress 使用者名稱和應用程式密碼。

透過管理後台匯入

轉換行為

狀態

匯入器按如下方式對映 WordPress 狀態：

排程發佈的日期和 WordPress 的可見性規則不會根據這些狀態重建。發佈之前，請檢查每一篇匯入的草稿。

富文字和可重複使用區塊

Gutenberg 標記會被轉換為 Portable Text。傳統 HTML 由同一個轉換器處理。請在算繪後的 EmDash 站台中檢查複雜區塊、嵌入內容、短代碼、頁面建構器標記和外掛程式定義的區塊。

WordPress 在伺服器端渲染的區塊（例如 Latest Posts 或來自外掛程式的區塊）沒有儲存的標記。它們會被匯入為 HTML 區塊，其中包含原始的區塊註解，例如 <!-- wp:latest-posts {"postsToShow":3} /-->。這些區塊在站台上不顯示任何內容。請在編輯器中開啟該區塊的 HTML 分頁，查看它原本是什麼，然後重新建置或刪除它。

WXR 中的 wp_block 條目會作為 sections 匯入。它們不會被匯入到一般的內容集合中。

集合和欄位

預設的文章類型對映包括 post 到 posts，以及 page 到 pages。自訂文章類型使用經過清理的集合 slug。準備步驟會新增分析所需的標準標題、Portable Text 內容、摘要和精選圖片欄位。

型別相容的現有欄位會被重複使用。型別不符會阻擋該集合的對映；匯入器不會把現有欄位強制轉換為其他型別。

自訂欄位和 SEO 資料

WXR 分析會回報非內部的文章中繼資料鍵，並建議欄位名稱和型別，但 WXR 資料庫匯入寫入的是標準的匯入欄位，而不是複製每一個任意的中繼資料鍵。請把分析結果當作可能需要另行轉換的欄位清單。

當目標集合具有相符的欄位時，EmDash Exporter 路徑可以複製自訂中繼資料和 Advanced Custom Fields（ACF）的值。對於帶有 “Post Type is equal to” 位置規則的 ACF 欄位群組，分析會為該群組中的每個 ACF 欄位建議一個欄位：文字、數字和真/假欄位會獲得相符的型別，而選擇、核取方塊、重複器、群組、關聯，以及其他可以儲存清單或物件的欄位則會變成 JSON 欄位。透過其他位置規則指派的欄位群組，其欄位僅根據匯出器回報的中繼資料鍵來建議。如果某個集合的欄位是先前的匯入根據中繼資料鍵建立的，它會保留這些欄位，因此其重複器會以每一列和每個子欄位各產生一個欄位的方式匯入。JSON 值保持其 WordPress 形態：關聯、文章物件、使用者和分類法欄位依 WordPress ID 指向 WordPress 的文章、使用者和詞彙，而不是 EmDash 條目；圖片、檔案和圖庫欄位指向 WordPress 媒體檔案，而不是已匯入的 EmDash 媒體。儲存在多篇文章上的 ACF 群組子欄位，也可能作為單獨的欄位出現在該群組的 JSON 欄位旁邊；請保留你的範本所使用的那一份。在範本中使用這些值之前，請先檢查它們。

匯出器路徑還可以在啟用相應的匯入開關後，建立並填入受支援的精選圖片欄位，以及 Yoast 或 Rank Math 的 SEO 欄位。

作者和 byline

已對映的 WordPress 作者會成為條目的擁有者。署名顯示使用 byline。如果沒有使用者對映，EmDash 會根據 WordPress 作者的身分建立或重複使用訪客 byline。

分類法

分類和標籤會匯入到相符的 EmDash 分類法定義中。匯出器路徑可以為自訂分類法建立定義。沒有相符 EmDash 定義的 WXR 自訂分類法會被回報為缺少，其指派關係會被略過。

媒體

媒體去重會比較已下載位元組內容的 SHA-1 雜湊。具有相同雜湊的現有媒體資料列會被重複使用。檔名和 WordPress ID 不是去重的依據。

在 EmDash 下載附件期間，來源站台必須保持可存取。來自附件 URL 的重新導向在被跟隨之前會經過驗證。

重試部分完成的匯入

管理後台匯入的設計會略過已存在的條目，但其比對邊界很重要：

• 現有內容依集合、slug 和地區設定比對，而不是依 WordPress ID 比對。
• 如果來源 slug 在兩次嘗試之間發生了變化，請檢查這兩個條目並手動解決重複問題。
• 重新執行媒體步驟時，會依內容雜湊重複使用已經儲存的、位元組完全相同的檔案。
• 匯出器流程傳送的是有大小限制的分塊。重新啟動瀏覽器流程會重新執行內容頁面，並根據被略過的條目重建關聯對映。

管理後台不會保存 WXR 的還原檔。emdash import wordpress 上的 --resume 旗標屬於另一個將轉換後的 JSON 檔案寫入磁碟的 CLI 工作流程；它不會還原管理後台的資料庫匯入。

切換上線前的驗證

將匯入後的站台與來源站台進行比對：

• 依文章類型和狀態統計條目數量。
• 開啟具有代表性的 Gutenberg、傳統編輯器、短代碼和頁面建構器內容。
• 確認精選圖片和內嵌媒體都能從 EmDash URL 解析。
• 檢查作者、byline、分類、標籤、自訂分類法和翻譯。
• 如果是透過匯出器匯入的，測試選單、留言、站台識別和 SEO 欄位。
• 爬取舊的公開 URL，並為每一個發生變化的路由準備重新導向。
• 驗證未登入的訪客仍然無法存取草稿。

在新站台於正式環境中成功運作、並且不再需要回復之前，請保留備份和 WordPress 部署。

疑難排解

無法解析 XML 檔案

請從 Tools → Export 重新匯出檔案，並確認下載已完成。不要用會改變編碼的工具編輯 XML。

集合被標記為不相容

現有欄位的 slug 相同，但型別不同。請在重試之前變更文章類型的對映，或在 Content Types 下調和該欄位。準備步驟會新增缺少的欄位，但不會變更現有欄位的型別。

機器人防護攔截了匯出器

Cloudflare 的機器人防護可能會用挑戰頁面而不是匯出器 API 來回應 EmDash 的請求。EmDash 隨後會回報機器人防護阻止了連線。請在遷移期間放行匯出器的請求：

• 使用 Super Bot Fight Mode 或其他 Cloudflare WAF 功能時，新增一條動作為 Skip 的自訂規則，並把它放在任何會發出挑戰的規則之上。選擇 All Super Bot Fight Mode rules；如果該區域使用 I’m Under Attack 模式，還要選擇 Security Level。下面的運算式可比對啟用和未啟用永久連結美化時的匯出器 API（包括安裝在子目錄中的 WordPress），以及 EmDash 下載的媒體檔案：

  (http.request.uri.path contains "/wp-json/emdash/v1/")
  or (http.request.uri.query contains "rest_route=%2Femdash%2Fv1%2F")
  or (http.request.uri.path contains "/wp-content/uploads/")

• Cloudflare 免費方案上的 Bot Fight Mode 無法透過規則跳過。請在遷移期間將其關閉，並在遷移之後重新開啟。

媒體 URL 下載失敗

請檢查來源附件是否無需 WordPress 工作階段即可存取。需要驗證的媒體、已刪除的檔案，以及重新導向到私有網路位址的媒體都會單獨失敗，並保留在媒體錯誤清單中。

調整主題

封存路由使用 getEmDashCollection()，slug 路由使用 getEmDashEntry()。entry.id 是路由識別碼，通常就是 slug；entry.data.id 是關聯輔助函式使用的已儲存內容 ID。

下面的路由會算繪一篇匯入的文章：

---
import { decodeSlug, getEmDashEntry } from "emdash";
import { PortableText } from "emdash/ui";

const slug = decodeSlug(Astro.params.slug);
if (!slug) return Astro.rewrite("/404");

const { entry: post, error } = await getEmDashEntry("posts", slug);
if (error) return new Response("Could not load the post", { status: 500 });
if (!post) return Astro.rewrite("/404");
---

<article>
  <h1>{post.data.title}</h1>
  <PortableText value={post.data.content} />
</article>

路由和元件的對映請閱讀移植 WordPress 主題。端點契約和確切的重試邊界請閱讀內容匯入。