devgo.cn如果你的团队也维护着一个跑了四年的技术博客，内容积累到几百篇，但每次想换框架都因为“没时间”“怕出问题”一拖再拖，那这篇文章就是为你准备的。我们（Evil Martians 前端团队）用了三年来拖延这件事，却在 2026 年 8 月真正动手时，只花了两周就把 evilmartians.com 从 Gatsby 整体迁移到了 Astro——而且主力干活的不是一个专职工程师，是一个 Claude 驱动的自动化流程，外加我们人工检查。今天想跟你分享的不是“AI 多厉害”的鸡汤，而是这次迁移里真正的技术决策、失败模式，和那几个差点漏掉的 bug。
先交代背景：evilmartians.com 是 Evil Martians 这家咨询公司的门面，也是我们给几十万开发者发技术文章的主要渠道。整个站点有 367 篇文章，全部基于 Gatsby 构建，已经跑了四年。Gatsby 是 React 生态里非常成熟的静态站点生成器（SSG，把 React 组件在构建时直接编译成静态 HTML，用户访问时不需要跑 JavaScript），但它的问题是生态和构建链路越来越重，为了一个博客要维护一整套 GraphQL 数据层、插件系统，以及不断升级的依赖版本。相比之下，Astro 是更轻量、默认输出零 JS 的框架，它提倡“岛屿架构”——页面大部分是纯静态 HTML，只有需要交互的局部才挂载少量脚本，这样首屏性能更好，维护心智也更简单。
为什么拖了三年？因为我们是咨询公司，工程师的时间基本都绑在客户项目上，内部站点迁移永远是“重要但不紧急”的任务。每次评估都要拉人出来做规划、测兼容性、处理 Gatsby 特有的各种 API，估算下来起码要一个月，而且容易影响正在进行的客户交付。直到 2026 年我们决定换个思路：让 LLM（大语言模型，这里用的是 Claude）来承担绝大部分机械性的迁移工作，我们只负责定义规则、审查产出和修复它无法处理的部分。结果是，整个迁移只用了 9¾ 天（对，就是标题里的那个哈利·波特梗），两周内完成，其中大部分时间其实花在人工抽查和修正上，真正的“AI 写码”阶段反而很快。
具体做法是：先把 Gatsby 的页面模板、数据获取逻辑、路由和组件结构梳理成一份清单，然后给 Claude 提供明确的迁移规范和示例——比如 Astro 的 frontmatter（文件顶部用 YAML 或 JSON 写元数据的区块）怎么写、组件引用方式怎么变、GraphQL 查询如何替换成直接的数据导入。Claude 一次处理一个目录或一个页面组，生成 Astro 版本的 `.astro` 文件。我们没有让它一次性全部生成，而是分批喂入，每批回来由工程师抽查、跑本地构建看报错、检查渲染结果。这个过程本质上是“人机结对编程”：模型负责把模板语法翻译过去，人负责判断语义是否正确。
但最值得写下来的是过程中发现的四个“如果让 Agent 跑飞就会上线”的 bug。第一个是图片路径问题：Gatsby 里图片资源是通过 graphql 查询拿到 URL，然后交给 `gatsby-image` 组件做响应式压缩，而 Astro 需要直接引用 `public` 目录或经 `astro:assets` 处理。Claude 在转换时把很多 `gatsby-image` 的参数直接翻译成了 `<img>` 标签，却丢失了尺寸、占位图、懒加载配置，导致首页首屏的 LCP（最大内容绘制，可理解为用户看到主要内容的时间）性能数据可能恶化——我们后来重新用 Astro 的 `Image` 组件补上了。第二个是动态路由的 `slug` 处理：Gatsby 的文件名和 Astro 的动态路由参数（`[...slug].astro`）在多级路径下有细微差异，Claude 有几次生成了错误的文件路径映射，如果没检查，文章 URL 会全部 404，对 SEO 是毁灭性打击。第三个是 RSS 订阅和 sitemap 等 `getStaticPaths` 之外的辅助输出，Claude 默认忽略了这些非页面代码，差点导致订阅源失效。第四个是自定义 React 组件的交互逻辑：Astro 里要挂载 React 组件需要明确标注 `client:load` 或 `client:only`，Claude 把一些需要交互的折叠面板、代码复制按钮直接转成了静态 HTML，结果页面看起来没坏，但点击没反应，这种“静默失败”最危险，因为自动化测试不一定能覆盖到。
从这次经验里，我最大的感受是：不要怕把老项目交给 LLM，但前提是你得给它划定边界、提供充分的验收标准和人工复查步骤。我们把这套流程固化成了两个技巧：一是让 Claude 先“解释再动手”，每个文件转换前先输出它对原文件的理解，我们再确认理解无误才允许生成代码；二是用“先坏后好”的方式跑本地服务器，故意保留一个旧版页面做对照，每次新生成的页面都在浏览器里对比差异，能捕捉到视觉和交互上的回归。另外，迁移前把依赖和工具链升级到 Astro 当前稳定版，可以减少 AI 生成代码时猜测 API 的错误（Claude 的知识截止日期可能早于你用的版本）。
如果你也在考虑迁移一个老静态站点，这个思路可以复制：任何“模板转换 + 数据搬运 + 配置调整”组成的迁移任务，都很适合让 LLM 先做一遍粗活，然后由人做“差分审查”。但要注意三种坑：一是模型对历史 API 的误判，要强制它使用你提供的最新文档；二是生成代码的风格不统一，最好先让模型学习 2-3 个你自己手工写的 Astro 页面作为风格基准；三是处理非页面文件（RSS、sitemap、搜索索引、构建脚本）时，必须单独列出清单单独检查。说白了，AI 帮你省掉了从头阅读旧代码的成本，但“决定什么不能丢”这件事，还得你自己来。
整篇文章没有配任何截图或架构图，唯一能参照的图占位符位于正文语义中——在这篇讲迁移过程的文章里，最合适的位置就是描述从 Gatsby 到 Astro 的转换流程时，但原文并没有提供具体图片内容，因此我按规范保留占位符并插入到人机协作流程说明之后的段落附近，表明迁移流程的大致形态：旧 Gatsby 代码 → Claude 批量转换 → 人工审查 → Astro 输出。
最后补充一点团队视角：这趟迁移让我们意识到，之前对“技术债”的恐惧有相当一部分来自对大规模改动的未知，而 LLM 恰好把这种未知变成了“可批量尝试，可快速失败”的状态。如果你手头也有一个几百页的老站，或者一份积累了多年的代码库，别急着投一个整月去做重写，先挑一个代表性页面让 AI 做一遍迁移，看看它碰到的问题是否可控。能控制，你就有了提速的杠杆；不能控制，那至少你没有损失一个月的开发时间。这个经验适用于任何类似的长尾重活——只要任务的可重复性足够高，AI 就能帮你把拖延了多年的“重要但不紧急”变成“重要且已做完”。
内容与图片版权归原作者所有 · 原文: https://evilmartians.com/chronicles/golden-switch-or-migrating-from-gatsby-to-astro-in-under-9-days