从 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 — 查询与渲染已导入内容