如果你打算把 WordPress 博客迁移到 Hugo、11ty 或 Obsidian，在后台点「工具」再点「导出」，得到的却不是 Markdown，而是一个 XML 文件。很多人就停在了这一步。迁移的路径不止一条，文章数量和手上的环境不同，最快的路也不同。这篇文章比较三条路径，并整理各自的操作步骤和容易遗漏的后处理。
选哪条路径迁移
先看结论判断表。
- 想一次性迁移几十到几百篇，本地能运行 Node.js — 路径 A（wordpress-export-to-markdown）
- 想在服务器侧完成，有管理员权限安装插件 — 路径 B（导出插件）
- 目标只有几篇，既不能用 Node.js 也不能装插件，或者处理不能外传的文章 — 路径 C（浏览器内转换，免费、无需注册、不上传）
路径 C 与其说是「迁移」，不如说是「转换」这种灵活的手段。但如果只想先移一篇草稿，或从离职者留下的公司 WordPress 里救回文章，它是最快的。
导出的 XML 为什么不是 Markdown
在 WordPress 后台执行「工具」里的「导出」，会下载 WordPress eXtended RSS（WXR）格式的 XML 文件在新标签页中打开。这个格式把文章、固定页面、分类、标签、评论等打包在一起，正文以 HTML 形式嵌在 XML 里。也就是说，导出后的状态是「XML 壳子里的 HTML」，到 Markdown 需要两次转换。
另外，用区块编辑器（Gutenberg）写的文章，区块分隔会以 HTML 注释的形式序列化保存。按照 WordPress 官方区块编辑器设计文档在新标签页中打开，一个段落是这样保存的：
<!-- wp:paragraph -->
<p>欢迎来到区块的世界。</p>
<!-- /wp:paragraph -->
像 [gallery] 这样的短代码也会原样留在正文里。这三层（XML 壳子、区块注释、短代码）如何处理，是选择路径的关键。
迁移前确认 — 什么保留、什么消失
无论哪条路径，正文（标题、段落、列表、链接、表格、代码块）都会变成 Markdown。差别在元数据。
- 发布日期、slug、分类、标签都在 WXR 里。路径 A 会写成 frontmatter，路径 C 只处理复制的正文 HTML，所以 frontmatter 要自己加
- 读者评论在任何路径下都不会变成 Markdown 文件。迁移后还想显示的话，需要另外切换到静态站点的评论服务
- 自定义字段的处理依赖工具。如果迁移后需要某些值，提前整理一下用了哪些字段
路径 A — 用 wordpress-export-to-markdown 批量转换
事实上的标准工具是 wordpress-export-to-markdown在新标签页中打开。它接收 WXR 文件作为输入，为每篇文章生成带 frontmatter 的 Markdown 文件，同时下载正文中引用的图片并改写引用（功能列表见仓库 README）。
- 在后台「工具」里打开「导出」，选择「所有内容」下载 XML。
- 在安装了 Node.js 的环境运行命令。
npx wordpress-export-to-markdown
交互式向导会运行，可以选择输入文件位置、输出位置、文件夹结构（--post-folders / --date-folders）、文件名加日期（--prefix-date）、图片保存方式（--save-images）、frontmatter 包含的字段（--frontmatter-fields）等。文章越多，这个批量处理的效果越大。
路径 B — 用插件导出
想在服务器侧完成的话，有 Static Site Exporter（原 Jekyll Exporter）在新标签页中打开 这类导出插件。它把文章和固定页面转成带 YAML frontmatter 的 Markdown，打包成 ZIP，便于直接导入 Jekyll 或 Hugo。
注意两点。添加插件需要管理员权限；而且正如插件页面所写，规模较大的站点在网页运行容易超时，推荐使用命令行运行。部分托管会碰到 PHP 内存上限。
路径 C — 只用浏览器转换
如果只有几篇，不需要环境搭建的浏览器内转换最快。获取输入有两种方法。
- 在区块编辑器打开文章，从右上角选项切到「代码编辑器」，复制正文 HTML。这个 HTML 里有
<!-- wp:paragraph -->这样的区块注释 - 在浏览器打开已发布页面，用开发者工具等复制文章部分的 HTML。因为是渲染后的 HTML，没有区块注释，但会带着主题的包装元素
复制后，粘贴到 HTML 转 Markdown 运行即可。工具的一般用法见HTML 转 Markdown 指南。
例如从代码编辑器复制下面的 HTML 粘贴后，
<!-- wp:heading -->
<h2 class="wp-block-heading">迁移归档</h2>
<!-- /wp:heading -->
<!-- wp:image -->
<figure class="wp-block-image size-large"><img src="https://example.com/wp-content/uploads/2024/03/diagram.png" alt="架构示意图" class="wp-image-42"/><figcaption class="wp-element-caption">图 1：旧架构</figcaption></figure>
<!-- /wp:image -->
输出是这样。
## 迁移归档
图 1：旧架构
区块注释、wp-block-* 的 class、内联 style 会消失，标题、图片会变成 Markdown 语法。HTML 粘贴时去除内联样式的通用模式见HTML 粘贴 Markdown 化。figcaption 的说明文字以纯文本形式留在图片下方。<pre class="wp-block-code"> 代码块变成围栏代码，表格变成管道表。短代码不是 HTML，所以不会转换，会像 \[gallery ids="12,13,14"\] 这样方括号被转义的纯文本留下（后处理章节会讲）。
转换完全在浏览器内的 JavaScript 完成，粘贴的内容不会发送到任何地方。处理公司 WordPress 的文章或未公开草稿时，这一点和上传型转换服务不同。
迁移后处理检查清单
无论走哪条路径，下面 4 点最后都要动手。
- 短代码清理。
[gallery]、[caption]或插件特有的短代码不会变成 Markdown 而留下。形状不固定（有没有属性、包裹形式等），安全做法是在编辑器里搜索[逐个判断，而不是一键替换 - 图片迁移。路径 C 里图片 URL 仍指向
wp-content/uploads。把目标里的图片下载并改写 URL。srcset或loading="lazy"属性在转换时会消失，需要的话在目标侧重新加 - 内部链接改写。把指向旧域名或固定链接结构（
?p=123格式等）的链接改成目标 URL 规则 - frontmatter 添加。把标题、日期、标签用 YAML 加在开头。静态站点生成器（SSG）格式各不相同，查目标 SSG 的文档。frontmatter 格式的细节见Markdown frontmatter 的 YAML 与 JSON
比较 — 三条路径的区别
| 路径 | 适合规模 | 需要环境 | 元数据 | 图片 |
|---|---|---|---|---|
| A: wordpress-export-to-markdown在新标签页中打开 | 几十到几百篇批量迁移 | Node.js + WXR 导出 | 自动写进 frontmatter | 下载并改写引用 |
| B: 导出插件 | 想在服务器侧完成 | 管理员权限（装插件） | 自动写进 frontmatter | 取决于插件 |
| C: HTML 转 Markdown | 只迁移几篇 | 只需浏览器（免费、无需注册） | 手动添加 | URL 保留，手动迁移 |
常见问题
不用 Node.js 能把 WordPress 文章转成 Markdown 吗？
可以。能装插件就用路径 B，不能就用路径 C。把文章切到代码编辑器视图复制 HTML，粘贴到 HTML 转 Markdown，不搭建环境也能得到 Markdown。
Gutenberg 的区块注释转换后还留吗？
FormatArc 转换中，<!-- wp:paragraph --> 这样的 HTML 注释不会留在输出里。注意，这种注释只存在于代码编辑器复制的 HTML 中，从已发布页面复制的 HTML 本来就没有。
图片也能一起迁移吗？
路径 A 有下载正文图片并改写引用的功能（README在新标签页中打开 有说明）。路径 C 只转换，图片 URL 仍指向原站点。只有几篇的话，手动保存图片并改写 URL 更实际。
把未公开草稿或公司 WordPress 文章粘贴到外部工具安全吗？
向服务器发送的工具，粘贴的瞬间内容就脱离了控制。FormatArc 只在浏览器内处理，不会发生发送。判断标准在在线工具安全检测中整理。
用经典编辑器写的旧文章也能用同样步骤迁移吗？
可以。经典编辑器正文是没有区块注释的纯 HTML，转换反而简单。路径 A、B、C 都能处理经典编辑器的文章。
总结
WordPress 到 Markdown 的迁移由规模和环境决定。几百篇批量迁移用 wordpress-export-to-markdown，服务器侧完成用导出插件，只有几篇、不搭环境、还涉及机密内容时，HTML 转 Markdown 的浏览器内转换最快。无论选哪条路径，把短代码清理、图片迁移、内部链接改写、frontmatter 添加都纳入迁移范围来计划。如果从 Notion 等平台迁移时使用同样的做法，Notion 导出 Markdown 也可参考。