內容匯入

EmDash 從 WordPress 和其他平台匯入內容。每個匯入源會偵測平台,分析其內容並將其擷取到您的網站。

匯入源

WXR 檔案上傳

最完整的匯入方法。將 WordPress eXtended RSS (WXR) 匯出檔案直接上傳到管理儀表板。

功能:

• 所有文章類型(包括自訂)
• 所有元欄位
• 草稿和私密文章
• 完整的分類階層
• 媒體附件中繼資料

如何取得 WXR 檔案:

WordPress.com OAuth

對於託管在 WordPress.com 上的網站,透過 OAuth 連線以匯入,無需手動匯出檔案。

包含的內容:

• 已發佈和草稿內容
• 私密文章(需要授權)
• 透過 API 取得的媒體檔案
• 向 REST API 公開的自訂欄位

WordPress REST API 探測

當您輸入 URL 時,EmDash 會探測網站以偵測 WordPress 並顯示可用內容:

偵測到: WordPress 6.4
├── 文章: 127 (已發佈)
├── 頁面: 12 (已發佈)
└── 媒體: 89 個檔案

注意: 草稿和私密內容需要身分驗證
或完整的 WXR 匯出。

REST 探測僅供參考。對於完整匯入,它建議上傳 WXR 檔案或透過 OAuth 連線(對於 WordPress.com)。

匯入流程

所有來源都遵循相同的流程:

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│     連線    │────▶│     分析    │────▶│     準備    │────▶│     執行    │
│  (探測/     │     │  (結構      │     │  (建立      │     │  (匯入      │
│   上傳)     │     │   檢查)     │     │   結構)     │     │   內容)     │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

步驟 1: 連線

輸入 URL 進行探測或直接上傳檔案。

URL 探測並行執行所有已註冊的來源。信心度最高的配對決定建議的下一步操作:

• WordPress.com 網站 → 提供 OAuth 連線
• 自架 WordPress → 顯示匯出說明
• 未知 → 建議檔案上傳

步驟 2: 分析

來源解析內容並檢查結構相容性:

文章類型:
├── post (127) → posts [新集合]
├── page (12)  → pages [現有,相容]
├── product (45) → products [新增 3 個欄位]
└── revision (234) → [跳過 - 內部類型]

所需的結構變更:
├── 建立集合: posts
├── 向 pages 新增欄位: featured_image
└── 建立集合: products

每種文章類型顯示其狀態:

步驟 3: 準備結構

點選建立結構並匯入以:

1. 建立新集合
2. 使用正確的欄類型新增缺少的欄位
3. 設定帶索引的內容表

步驟 4: 執行匯入

內容依序匯入:

• Gutenberg/HTML 轉換為 Portable Text
• WordPress 狀態對應到 EmDash 狀態
• WordPress 作者對應到所有權(authorId)和展示署名
• 建立並連結分類
• 可重複使用區塊(wp_block)作為區段匯入
• 即時顯示進度

作者匯入行為:

• 如果作者對應指向 EmDash 使用者,則將所有權設定為該使用者,並為同一使用者建立/重複使用連結的署名。
• 如果沒有使用者對應,則從 WordPress 作者身分建立/重複使用訪客署名。
• 匯入的項目獲得有序的署名信用,第一個信用設定為 primaryBylineId。

步驟 5: 媒體匯入(選用)

在內容之後,可選擇匯入媒體:

媒體匯入使用內容雜湊(xxHash64)進行去重。在多個文章中使用的相同圖片只儲存一次。

API 端點

匯入系統公開這些端點:

探測 URL

透過探測請求偵測 URL 背後的平台:

POST /_emdash/api/import/probe
Content-Type: application/json

{ "url": "https://example.com" }

回應包含偵測到的平台和建議的操作。

分析 WXR

上傳 WXR 檔案以分析其文章類型和結構相容性:

POST /_emdash/api/import/wordpress/analyze
Content-Type: multipart/form-data

file: [WordPress export .xml]

回應包含帶結構相容性的文章類型分析。

準備結構

為選定的文章類型建立集合和欄位:

POST /_emdash/api/import/wordpress/prepare
Content-Type: application/json

{
  "postTypes": [
    { "name": "post", "collection": "posts", "enabled": true }
  ]
}

執行匯入

將內容匯入對應的集合:

POST /_emdash/api/import/wordpress/execute
Content-Type: multipart/form-data

file: [WordPress export .xml]
config: { "postTypeMappings": { "post": { "collection": "posts" } } }

匯入媒體

下載並儲存匯入參考的媒體附件:

POST /_emdash/api/import/wordpress/media
Content-Type: application/json

{
  "attachments": [{ "id": 123, "url": "https://..." }],
  "stream": true
}

回應在下載和上傳期間串流 NDJSON 進度更新。

重寫 URL

將匯入內容中的舊媒體 URL 取代為其儲存的等效項:

POST /_emdash/api/import/wordpress/rewrite-urls
Content-Type: application/json

{
  "urlMap": { "https://old.com/image.jpg": "/_emdash/media/abc123" }
}

錯誤處理

可恢復的錯誤

• 網路逾時 — 使用退避重試
• 單個項目解析失敗 — 記錄,跳過,匯入繼續
• 媒體下載失敗 — 標記為手動處理

致命錯誤

• 無效的檔案格式 — 匯入停止並顯示錯誤訊息
• 資料庫連線中斷 — 匯入暫停,允許恢復
• 儲存配額超出 — 匯入停止,顯示使用情況

錯誤報告

匯入完成後,EmDash 顯示成功、調整和失敗的摘要:

匯入完成

✓ 已匯入 125 篇文章
✓ 已匯入 12 個頁面
✓ 已記錄 85 個媒體參考

⚠ 2 個項目有警告:
  - 文章 "Special Characters ñ" - 標題編碼已修復
  - 頁面 "About" - 重複的 slug 已重新命名為 "about-1"

✗ 1 個項目失敗:
  - 文章 ID 456 - 內容解析錯誤(已儲存為草稿)

失敗的項目儲存為草稿,原始內容在 _importError 中供審查。

自訂來源

要從內建來源未涵蓋的平台匯入,實作 ImportSource 介面並在整合上註冊:

import { mySource } from "./src/import/custom-source";

export default defineConfig({
	integrations: [
		emdash({
			import: { sources: [mySource] },
		}),
	],
});

介面(probe、analyze、fetchContent)和規範化的輸出形狀記錄在架構(內部)中。

下一步

• WordPress 遷移 — 完整的 WordPress 遷移指南
• 外掛程式移植 — 將 WordPress 外掛程式移植到 EmDash