從 WordPress 遷移 | EmDash CMS Everything

EmDash 可以從 WordPress 遷移內容。透過管理儀表板匯入你的文章、頁面、媒體和分類。

開始之前

匯出你的內容

在 WordPress 中，前往工具 → 匯出並下載完整的匯出檔案（.xml）。

備份你的網站

在驗證遷移成功之前，保持你的 WordPress 網站運行。

匯入方法

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

方法	適用於	包含草稿	需要認證
WXR 檔案上傳	完整遷移	是	否
WordPress.com	WordPress.com 託管網站	是	OAuth
REST API（探測）	匯出前檢查內容	否	選用

大多數遷移推薦使用 WXR 檔案上傳。它可以捕獲所有內容，包括草稿、自訂欄位和私密文章。

WXR 檔案匯入

從 WordPress 匯出

在你的 WordPress 管理後台，前往工具 → 匯出 → 所有內容 → 下載匯出檔案。
開啟匯入精靈

在 EmDash 中，前往管理 → 設定 → 匯入 → WordPress。
上傳你的匯出檔案

拖放你的 .xml 檔案或點擊瀏覽。檔案在瀏覽器中解析。

檢視偵測到的內容

精靈顯示發現的內容：

Found in export:
├── Posts: 127 → posts [New collection]
├── Pages: 12  → pages [Add fields]
└── Media: 89 attachments

設定對映

切換要匯入的文章類型。EmDash 自動：
- 為未對映的文章類型建立新集合
- 向現有集合新增缺失欄位
- 對欄位類型衝突發出警告
執行匯入

點擊匯入內容。處理每個項目時顯示進度。
匯入媒體（選用）

內容匯入後，選擇是否下載媒體檔案。EmDash 會：
- 從你的 WordPress URL 下載
- 按內容雜湊去重
- 自動重寫內容中的 URL

內容轉換

Gutenberg 到 Portable Text

EmDash 將 Gutenberg 區塊轉換為 Portable Text，一種結構化內容格式。

Gutenberg 區塊	Portable Text	注意
`core/paragraph`	`block` style=“normal”	保留內聯標記
`core/heading`	`block` style=“h1-h6”	來自區塊屬性的層級
`core/image`	`image` block	媒體參照已更新
`core/list`	`block` with `listItem` type	有序和無序
`core/quote`	`block` style=“blockquote”	包含引用
`core/code`	`code` block	保留語言屬性
`core/embed`	`embed` block	儲存 URL 和提供商
`core/gallery`	`gallery` block	圖像參照陣列
`core/columns`	`columns` block	保留巢狀內容
未知區塊	`htmlBlock`	保留原始 HTML 以供審查

未知區塊儲存為 htmlBlock，包含原始 HTML 和區塊中繼資料。你可以手動審查和轉換它們，或建立自訂 Portable Text 元件來呈現它們。

傳統編輯器內容

傳統編輯器的 HTML 轉換為 Portable Text 區塊。內聯樣式（<strong>、<em>、<a>）成為跨距上的標記。

狀態對映

WordPress 狀態	EmDash 狀態
`publish`	`published`
`draft`	`draft`
`pending`	`pending`
`private`	`private`
`future`	`scheduled`
`trash`	`archived`

分類匯入

類別和標籤作為分類匯入，保留層次結構：

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

WordPress 文章中繼資料和 ACF 欄位在匯入期間進行分析：

分析階段

精靈偵測自訂欄位並建議 EmDash 欄位類型：

Custom Fields:
├── subtitle (string, 45 posts)
├── _yoast_wpseo_title → seo.title (string, 127 posts)
├── _thumbnail_id → featuredImage (reference, 89 posts)
└── price (number, 23 posts)

欄位對映

內部 WordPress 欄位（以 _edit_、_wp_ 開頭）預設隱藏。SEO 外掛欄位對映到 seo 物件。
類型推斷

EmDash 從值推斷欄位類型：
- 數字字串 → number
- "1"、"0"、"true"、"false" → boolean
- ISO 日期 → date
- 序列化的 PHP/JSON → json
- WordPress ID（例如 _thumbnail_id）→ reference

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 時使用此表：

WordPress	EmDash	注意
`register_post_type()`	管理 UI 中的集合	透過儀表板或 API 建立
`register_taxonomy()`	分類或陣列欄位	取決於複雜性
`register_meta()`	集合結構描述中的欄位	類型化，非鍵值
`WP_Query`	`getCollection(filters)`	執行階段查詢
`get_post()`	`getEntry(collection, id)`	傳回條目或 null
`wp_insert_post()`	`POST /_emdash/api/content/{type}`	REST API
`the_content`	`<PortableText value={...} />`	Portable Text 呈現
`add_shortcode()`	Portable Text 自訂區塊	自訂元件呈現器
`register_block_type()`	Portable Text 自訂區塊	與短代碼相同
`add_menu_page()`	外掛管理頁面	在 `/_emdash/admin/` 下
`add_action/filter()`	外掛掛鉤	`hooks.content:beforeSave`
`wp_options`	`ctx.kv`	鍵值儲存
`wp_postmeta`	集合欄位	結構化，非鍵值
`$wpdb`	`ctx.storage`	直接儲存存取
Categories/Tags	分類	保留層次結構支援

API 匯入（進階）

WordPress 匯入可透過管理儀表板和 REST API 使用。使用管理儀表板匯入精靈獲得最佳體驗——它提供欄位對映、衝突解決和進度追蹤。

匯入 API 端點位於 /_emdash/api/import/wordpress/ 下，用於程式化存取。

故障排除

「XML 解析錯誤」

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

媒體下載失敗

某些圖像可能位於身分驗證後面或已移動。匯入繼續進行，失敗的 URL 將記錄以供手動處理。

欄位類型衝突

如果現有集合具有不相容類型的欄位，匯入精靈會顯示衝突。可以：

重新命名 EmDash 欄位
更改 WordPress 欄位對映
刪除並重新建立集合

大型匯出

對於超過 100MB 的匯出，考慮：

在 WordPress 中單獨匯出文章類型
按順序匯入每個檔案
使用帶有 --resume 的 CLI 以提高可靠性

下一步

內容匯入 — 其他匯入來源和方法
外掛移植 — 遷移 WordPress 外掛功能
處理內容 — 查詢和呈現匯入的內容