從 WordPress 遷移

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

開始之前

請準備以下項目：

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

請記錄目前的固定連結結構、正規來源（canonical origin）、重新導向、選單、啟用的文章類型、分類法，以及新站台必須保留的所有由外掛程式擁有的欄位。

選擇匯入方式

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

匯出 WXR 檔案

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

連線 EmDash Exporter

在 WordPress 中開啟 Tools → EmDash Migration 並產生遷移金鑰。把金鑰貼到 EmDash 匯入頁面中。

你也可以輸入 WordPress 站台 URL。偵測到 exporter 後，透過 WordPress 應用程式密碼畫面授權 EmDash。在本機 HTTP 開發站台上，由於授權回呼需要 HTTPS，請手動輸入 WordPress 使用者名稱和應用程式密碼。

透過管理後台匯入

轉換行為

狀態

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

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

富文字和可重複使用區塊

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

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

集合和欄位

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

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

自訂欄位和 SEO 資料

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

當目標集合有相符的欄位時，EmDash Exporter 路徑可以複製自訂 meta 和 Advanced Custom Fields（ACF）的值。啟用相應的匯入開關後，它還可以建立並填入受支援的精選圖片欄位以及 Yoast 或 Rank Math 的 SEO 欄位。請檢查序列化的 PHP 值、重複器、彈性內容和外掛程式特有的結構，而不要假定它們在 WordPress 中的表示與 EmDash 欄位型別相符。

作者和 byline

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

分類法

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

媒體

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

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

重試部分完成的匯入

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

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

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

切換上線前的驗證

對照來源站台檢查匯入後的站台：

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

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

疑難排解

無法解析 XML 檔案

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

集合被標記為不相容

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

媒體 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 主題。端點契約和確切的重試邊界請閱讀內容匯入。