记录个人博客从 VitePress 迁移到 Next.js App Router 的原因、过程、测试和收尾状态。

这一次改动基本上是一次脱胎换骨，直接把 VitePress 主题迁到了 Nextra，全面脱离Vue，拥抱React。

一、概要

这次迁移的目标是彻底换掉底层框架，同时让读者看到的网站尽量保持原样。

迁移前后的变化如下：

迁移时的约定：

• 文章格式兼容：文章内容、frontmatter、outline 和链接结构保持兼容。
• 前端样式不变：Splash、Fireworks、Spine、BGM 这些装饰组件全部保留。
• 就链接重定向：旧 .html 链接继续兼容，由 Cloudflare Pages 的 _redirects 做 301。
• 脱离Vitepress与Vue：迁移完成并验证后删除 .vitepress/，不再把旧主题源码留在仓库里当依赖。

二、原始方案问题

1. 使用全局样式

旧主题的样式由 Less、全局 CSS 变量和组件 scoped 样式一起组成。小项目这么写没有太大问题，但这个博客后来加了首页、文章页、标签页、文集页、搜索、侧边栏、Splash、Spine、评论区和打印样式，样式影响范围就开始变得难判断。

这次迁移后，组件样式全部使用到 *.module.css。并做了完整的的变量语义化，调色盘放在全局，主题变量按组件分类放进 SCSS mixin。

2. Vue 维护成本

我平时写 React / Next.js 更多，不是特别喜欢Vue的语法。原来的 Vue 把模板、脚本和样式都放在一个文件里，感觉非常混乱。

博客是长期项目，写文章之外还会不断加小功能。继续在一个不熟悉的Vue主题体系里堆功能，后面每次修改都会变成心理负担。

3. 主题功能越来越重

这个博客早就超出了普通静态 Markdown 站点的范围。迁移前主题里已经有：

• Splash / Fireworks / Spine / BGM
• 首页文章列表、标签筛选、文集页
• 搜索弹窗、关键字索引、文章摘要
• KaTeX、Shiki 代码块、图片灯箱、PDF 打印
• SEO、sitemap、旧链接跳转、评论区主题

最麻烦的一段是把这些东西“再长回去”。Next.js 框架，真正耗时间的是让每个旧组件在新框架里表现得像原来一样。

三、迁移方案

1. 分支与骨架

迁移没有直接在 main 上改。main 继续承载原有 VitePress 生产版本，react-migration 用来开发 Next.js 版本，并接入 Cloudflare preview。

阶段记录如下：

2. 组件迁移

组件迁移按 .vitepress/theme/components 一项一项对照，不容易漏掉小细节。

这部分修了很多肉眼才能发现的问题，例如 Navbar 首次加载时横向漂移、移动端 SideList 从屏幕外滑入、titleDot 高度不对、PostList 切换时卡住、Splash 遮罩没有停留闪烁、Spine 模型位置和主题切换不一致。

3. Markdown 兼容层

旧文章是 VitePress Markdown，不是严格 MDX。直接按 MDX 编译会遇到 Vue 组件写法、旧图片导入、裸 HTML 标签、相对 .md 链接和公式边界问题。

兼容层集中放在 lib/mdx.ts 和图片检查脚本里：

文章里使用图片的写法也迁移到了 React 的 TSX 语法：

<Image {...previewCommitImage} />

4. 评论、SEO 与部署

评论系统从 Gitalk 改成 giscus。原来的 Gitalk 需要在前端放 GitHub OAuth 配置，giscus 只依赖 GitHub Discussions 和仓库配置，维护上更干净。代价是历史 Gitalk Issue 评论不会自动迁移，这一点迁移前已经接受。

SEO 也从 VitePress 的 head 字段迁到 Next.js metadata。旧文章里的 head 仍然保留，Next 端会读取并转换。sitemap.xml、 robots.txt、Open Graph、Twitter card 和 JSON-LD 都在 Next 端重建。

值得一提的是，迁移期间所有部署都是成功的：

四、测试记录

1. 构建与输出检查

迁移后构建前置检查更多了。现在 pnpm build 会先执行 pnpm typecheck，其中包含 TypeScript 检查和文章图片引用检查。

本地检查记录：

2. 浏览器测试

浏览器测试是纯人工进行的。迁移期以 Cloudflare Pages 的 react-migration preview 为被测对象，main 上的 VitePress 版本作为视觉和行为对照；测试环境覆盖了桌面端与iPad端的所有主流浏览器。

2.1 macOS 端

2.2 Windows 端

2.3 iPad 端

2.4 iOS 移动端

2.5 Android 移动端

测试时的问题主要集中在这些地方：

3. Lighthouse报告

迁移后，也同样补充了完整的 Lighthouse 测试，结果如下。

五、收尾

验证通过后，react-migration 合并回 main。.vitepress/ 已删除，旧的 VitePress / Vue / Less / markdown-it 相关依赖和脚本也从新链路里清掉。animejs 还保留，因为 React 端的 Splash 和 Fireworks 仍在使用。

收尾后的状态：

六、相关提交

这几张截图对应迁移过程里的几个节点：第一次上线 preview、迁移基本完成并结束测试、删除 .vitepress/、合并回 main 。从部署结果看，迁移期间 main 的 production 和 react-migration 的 preview 都没有失败。