从 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 插件功能
处理内容 — 查询和渲染导入的内容