从 WordPress 到 Astro 迁移记录

一、为什么选择 Astro

WordPress 虽然功能丰富，但本质上是动态架构，需要服务器和数据库的支持。而 Astro 作为新兴的静态站点生成器（SSG），能够将内容预渲染为纯 HTML，性能表现极其优异。

1. 托管平台的灵活性

由于 Astro 生成的是纯静态文件，我们可以将其免费部署在多个全球分发平台上。以下是主流选择的对比：

托管平台	主要优势	核心限制（2026 年）	适用场景
GitHub Pages	与源码管理无缝集成，完全免费，配置极其简单。	总包大小 1 GB 以内；月流量 100 GB；单文件需小于 100 MB。	适合仓库较小的个人项目或纯文字类型的简单技术博客。
Cloudflare Pages	流量不限量；全球 CDN 性能极佳；提供强大的 Bulk Redirects 重定向规则。	免费版文件数量限制在 20,000 个以内；单个资产文件不能超过 25 MB。	强烈推荐。尤其是文章配图较多、追求国内访问稳定性以及需要处理旧链接重定向的站长。
Vercel	部署流程极其顺滑，对 Astro 等现代前端框架支持度最高，预览功能强大。	免费版（Hobby）月流量 100 GB；每日构建部署上限为 100 次。	适合追求极致开发体验、需要频繁预览分支版本或使用 Serverless 函数的高级用户。

2. 轻量化与主题选择

Astro 最大的好处是“零 JS 模式”，只有在需要交互时才会引入 JavaScript，这让页面加载几乎是瞬间完成。在 Astro Themes 官方市场挑选后，我最终选择了 astro-koharu，它的设计简洁且符合我的审美。

二、导出 WordPress 数据

迁移的核心在于如何将原有的数据库文章转换为 Markdown 文件。

1. 获取原始数据

首先在 WordPress 后台使用自带的导出工具，导出所有文章（建议按分类分别导出，方便后面统一处理）和页面的 XML 文件。

2. 自动化转换

为了高效转换，我使用了 wordpress-export-to-markdown 工具。在终端执行：

npx wordpress-export-to-markdown

经验建议： 在转换过程中，建议选择为每篇文章生成独立文件夹。这样可以将文章对应的图片存放在各自文件夹下的 images 目录中，引用方式如 ![](images/imgtitle.webp)，非常便于后期维护。

三、处理 MD 文件

导出后的 Markdown 文件往往需要二次清洗，以符合 Astro 主题的 YAML 规范和 MD 特定的格式排版要求。

1. 使用 Python 脚本进行批量处理

为了处理成百上千的文章，建议利用 AI 编写 Python 脚本。以下是我提供给 AI 的设计需求，你可以直接参考这个逻辑：

# 设计一个py脚本，需要处理当前目录和子文件夹下的所有md文件，pubDate改为date，删除category: 音浪歌姬包厢，增加categories字段
categories:
  - 音浪歌姬包厢
增加字段tocNumbering: false，slugId改为link，确保删除之后不留提行；正文不要做任何修改。在代码块内输出最终的md。
## 需要修改的文件示例
示例
## 修改后的文件示例
示例

2. 格式微调与转义

除了表头，正文部分有两个特殊的处理点：

转义英文冒号：为了避免 Markdown 渲染器将正文中的冒号误判为 YAML 语法，需要将非代码块中的英文冒号 : 前加上转义符 \。
强制换行处理：在连续未提行的段落中，需要在每个段落末尾添加反斜杠 \。

示例：

常见的有偏机构和他们的价值导向：\
①资本媒体：资本导向，为了卖更多的货，赚更多的钱，形成资本增值；\
②政治媒体：政治导向，为了政权的稳定，和更大的政权影响范围和影响力；\
③个人媒体：个人价值观和兴趣导向，偏好不一。

注意，段落的最后一行不需要加反斜杠。

四、安装 Astro 并预览调试

环境配置阶段非常简单，只要有 Node.js 即可。

1. 依赖安装

进入你的 Astro 项目根目录，推荐使用 pnpm 以获得更快的速度：

pnpm install

2. 本地开发预览

执行以下命令开启开发服务器：

pnpm dev

此时访问 http://localhost:4321 即可实时预览迁移后的效果。在这里你可以反复调试样式，确保转换后的 MD 文件渲染正常。

五、上传到 Cloudflare Pages

部署到 Cloudflare Pages 是目前性价比最高的方案。

1. 部署细节

注意： 这里的 UI 比较隐蔽，点击进去后，下方会有一个较小的链接按钮切换到 Pages 选项卡。如果直接点大按钮，可能会创建成 Workers。

2. 绑定域名

关联 GitHub 仓库后，Cloudflare 会自动完成构建。部署成功后，你可以在设置中绑定自己的顶级域名，Cloudflare 会自动签发 SSL 证书。

六、域名重定向

这是最关键的一步。WordPress 的文章路径通常包含日期（如 /2025/03/slug），而 Astro 主题通常使用 /post/slug。

为了不让旧的搜索索引失效，需要在 Cloudflare 的 Bulk Redirects 中配置规则，将旧路径重定向到新路径：

匹配规则： https://yourdomain.com/20*/*/*
重定向至： https://yourdomain.com/post/$

这里的 ${3} 对应原路径中的 slug 部分。通过这一步，原本链接的 SEO 会无缝转移到新站上。

一、 为什么选择 Astro