從 WordPress 遷移

EmDash 提供從 WordPress 的完整遷移路徑。無需 CLI，在管理後台即可匯入文章、頁面、媒體與分類法。

開始之前

匯入方式

EmDash 支援三種匯入 WordPress 內容的方式：

多數遷移建議使用 WXR 檔上傳，可涵蓋草稿、自訂欄位與私密文章等全部內容。

WXR 檔案匯入

內容轉換

Gutenberg 到 Portable Text

EmDash 將 Gutenberg 區塊轉為 Portable Text 結構化格式。

未知區塊以 htmlBlock 儲存，附原始 HTML 與區塊中繼資料。可手動處理或撰寫自訂 Portable Text 元件渲染。

傳統編輯器內容

傳統編輯器的 HTML 會轉成 Portable Text 區塊。行內樣式（<strong>、<em>、<a>）變成 span 上的標記。

狀態對應

分類法匯入

分類與標籤以分類法匯入，階層保留：

WordPress:                    EmDash:
├── Categories (hierarchical) ├── taxonomies table
│   ├── News                  │   ├── category/news
│   │   ├── Local             │   ├── category/local (parent: news)
│   │   └── World             │   ├── category/world (parent: news)
│   └── Sports                │   └── category/sports
└── Tags (flat)               └── content_taxonomies junction
    ├── featured                  ├── tag/featured
    └── breaking                  └── tag/breaking

自訂欄位與 ACF

文章詮釋資料與 ACF 欄位會在匯入時分析：

URL 重新導向

匯入後 EmDash 會產生重新導向對照：

{
	"redirects": [
		{ "from": "/?p=123", "to": "/posts/hello-world" },
		{ "from": "/2024/01/hello-world/", "to": "/posts/hello-world" },
		{ "from": "/category/news/", "to": "/categories/news" }
	],
	"feeds": [
		{ "from": "/feed/", "to": "/rss.xml" },
		{ "from": "/feed/atom/", "to": "/atom.xml" }
	]
}

可套用至：

• Cloudflare 重新導向規則
• 主機平台的重新導向設定
• astro.config.mjs 中 Astro 的 redirects 選項

概念對照表

將 WordPress 慣例對應到 EmDash 時可參考：

API 匯入（進階）

WordPress 匯入可透過管理後台與 REST API 使用。為取得欄位對應、衝突處理與進度追蹤，建議使用匯入精靈。

程式化存取使用 /_emdash/api/import/wordpress/ 下的端點。

疑難排解

「XML parsing error」

匯出檔可能損毀或不完整，請從 WordPress 重新匯出。

媒體下載失敗

部分圖片可能需登入或 URL 已變更。匯入會繼續，失敗的 URL 會記錄。

欄位型別衝突

若既有集合中有不相容型別的欄位，精靈會提示衝突。您可以：

• 重新命名 EmDash 中的欄位
• 調整 WordPress 欄位對應
• 刪除並重建該集合

超大匯出

超過約 100MB 時建議：

1. 在 WordPress 依文章類型分別匯出
2. 依序逐檔匯入
3. 使用含 --resume 的 CLI 以提高可靠度

下一步

• Content Import — 其他匯入來源與方式
• Plugin Porting — 遷移 WordPress 外掛能力
• Working with Content — 查詢與渲染已匯入內容