大迁移——Vue 2 升 Vue 3、React class 转 hooks、JavaScript 转 TypeScript、Next.js Pages Router 转 App Router——过去意味着 3 周机械改动加 1 周抓 bug。让模型用一句”把整个 repo 迁了”去做，只会得到一份看着像、却跑不起来的代码。这套工作流把模型的机械速度和你的 code review 判断绑在一起：手工写 1 个参考文件、做模式扩散、用 codemod 收长尾，最后对照官方 checklist 复查。在一个真实的 React class 转 hooks 迁移里（约 50 个组件），它把 3 周的活压到约 3 天，且每次 commit 测试都保持绿色。
一句话总结
- 永远不要一口气迁整个 repo。把迁移切成有”过/不过”可验证的小块；失败止于一个文件，而不是 200 个。
- 流程：官方指南摘要 → 手工 + AI 写 1 个参考文件 → 用这个参考迁 5-10 个文件 → 用 codemod 处理琐碎长尾 → 对照官方 checklist 复查。
- 有官方 codemod 就先用（
@vue/compat、npx @next/codemod、Airbnb 的ts-migrate）；codemod 拿不准的判断 case 交给 AI。 - 截至 2026 年 6 月，Claude Opus 4.7 与 Gemini 3.1 Pro 都有 1M token 上下文——足以把参考文件和目标文件一次喂进同一个 prompt，一致性正是从这里来的。
- 前提：被改文件的测试覆盖率要高于约 50%。没有测试，每一步都是在赌。
适合谁、什么时候用
适合面对多周迁移、想让 AI 干机械活但又不希望它产出垃圾的开发者，也适合需要把迁移转成靠谱估算的 tech lead。最适合 50-1,000 个文件的代码库：手工迁太慢，纯 codemod 又漏掉判断 case。
什么时候上：迁移有清晰的官方升级路径（Vue、React、Next.js、Angular、Svelte），且多个文件以同样方式改动。判断触发点：随手点出 3 个文件，它们会被改得一模一样。带官方 codemod 但仍需清理的类型语言迁移（JS→TS、Python 2→3）也合适。
什么时候别用：跨范式的迁移——jQuery → React、REST → GraphQL——没有机械翻译可言，AI 只能当学习辅助，架构决策归你。代码没有测试覆盖也别上，因为你连一步都没法验证。
动手前先选对工具
大多数迁移都有官方机械工具。用它处理大头，把模型留给工具标记出来、或工具拿不准的 case。下表反映这些工具在 2026 年 6 月的状态。
| 迁移 | 官方机械工具 | 它不覆盖、需要 AI 的部分 |
|---|---|---|
| Vue 2 → Vue 3 | @vue/compat 迁移构建 + v3-migration.vuejs.org 指南 | Composition API 改写、v-model 重做、render 函数变化 |
| Next.js Pages → App Router | npx @next/codemod（如 next-async-request-api 处理异步 cookies()/headers()/params） | 路由结构重排、拆分 client/server 组件、数据获取改写——没有单一 codemod 能完成整个迁移 |
| JS → TypeScript | Airbnb ts-migrate（Airbnb 称单日处理 5 万+ 行、1,000+ 文件） | 超出 any 的真实类型，以及 class 转 hooks（ts-migrate 不碰 hooks） |
| React class → hooks | 无官方工具 | 整个转换——生命周期转 useEffect、state 转 useState/useReducer |
| 大批量改名（prop、import、废弃 hooks） | jscodeshift / ts-morph / ast-grep | 改名途中任何需要判断的地方 |
关于 codemod 引擎：jscodeshift（Meta）是经典的 JS/TS 转换器；ts-morph 封装了 TypeScript 编译器 API，转换时能真正读懂类型；ast-grep（以及基于它的新作者层 jssg）更快、跨语言，是 2026 年新 codemod 最被推荐的引擎。需要类型信息驱动改动就选 ts-morph；追求速度或处理非 JS 语言就选 ast-grep。
框架细节方面，可参考 AI 依赖升级工作流（把迁移钉在可复现的固定版本上），以及 AI 重构工作流（本文借用了它的文件级 review 纪律）。
开始前准备
- 确认被改文件的测试覆盖率高于约 50%。偏低就先给最常改的文件补 characterization 测试。
- 锁死确切的版本对。“Vue 2.7 → Vue 3.5”和”Vue 2.0 → Vue 3.5”是不同的迁移，模型需要真实起点。（Vue 2 已于 2023 年 12 月 31 日 EOL，“继续留在 2”拿不到新的安全修复。）
- 把官方迁移指南从头到尾读一遍。模型能总结，但你得能识破错误总结。
- 开一条干净分支，不夹带其他重构。把迁移和无关改动混在一起会让 bisect 失效。
分步流程
- 用官方指南锚定模型。 第一次对话：贴上你确切版本对的官方迁移指南 URL，让模型列出 5-10 个最常见的机械改动。钉 URL 能把模型留在官方路径，而不是 2 年前的博客传说——这很关键，因为前沿模型的训练时间往往早于某些指南定稿。
- 手工 + AI 写 1 个参考文件。 挑代码库中部、中等复杂度的文件，不要挑最简单的。prompt：
对这个文件应用迁移改动 1-5。输出：
1. 迁移后的整文件
2. 与原文件的 diff
3. 你做出的所有判断 call
不要重构无关代码。不要改不需要改的变量名。不要"顺手优化"。- 复查并锁定参考。 逐行 review diff。只跑这个文件的测试。自己改或再来一条聚焦 prompt 修问题。这个文件现在就是你的参考实现——单独 commit。
- 扩散模式。 下一次对话：“这是 A 文件的参考迁移（贴）。用同样模式迁 B 文件（贴）。完全匹配 A 文件的迁移风格。“把两个文件一次喂进同一个 prompt，正是 1M token 上下文模型的价值所在——一致性来自模型看见参考，而不是重新推导。
- 重复迁 5-10 个文件。 到第 3 个你已理解模式；到第 7 个你能 5 秒识破错误建议。每个文件单独 commit，bisect 才好用。
- codemod 收长尾。 对 40-200 个琐碎 case，用 AI 协助在 jscodeshift、ts-morph 或 ast-grep 里写 codemod，或直接跑官方的（
npx @next/codemod <transform> <path> --dry --print先预览）。永远先 dry-run、看 diff、再应用。每批之后测试必须通过。 - 对照官方 checklist 复查。 收尾对话：“review 这个分支，看是否漏了官方迁移条目：[贴指南的 checklist]。“漏掉少于 5 项算健康；超过则说明扩散中途有地方静默断掉——回去找差异点。
第一次怎么跑才不会炸
挑路线图里最小的非平凡迁移——一个 feature 文件夹、10-20 个文件。真上线、爆炸半径小。完整跑一遍流程并给每个阶段计时：指南摘要、参考文件、扩散、codemod、复查。把参考文件的 diff 和 codemod 脚本存下来，它们就是下一个同类型迁移的模板。下一批只改一个变量——换模型，或一次扩散更多文件——这样质量变化才能归因。
验收门槛
- 每次 commit 后测试都绿。如果某次 commit 改了 5 个文件并出错，先定位是哪个文件再继续。
- 参考文件的 diff 10 分钟内能 review 完。超时说明模型加太多，把 prompt 加严”禁止无关改动”。
- codemod 的 dry-run diff 30 分钟内能 review 完。超时说明 codemod 太激进——把它的匹配收窄。
- 收尾复查漏掉的条目少于 5 项。超过说明扩散出现了分叉。
MIGRATION-LOG.md（文件、状态、备注、blocker）已 commit，今天停下队友也能接手。
迁移用哪个模型
截至 2026 年 6 月，实用选型如下：
| 模型 | 上下文窗口 | 为什么适合迁移 |
|---|---|---|
| Claude Opus 4.7 | 1M token | 跨多文件保持一致性、跨模块边界追踪类型依赖最强；SWE-bench Verified 87.6% |
| Gemini 3.1 Pro | 1M token | 同样的上下文规模，API 成本更低（每 1M token 输入/输出 $2/$12，对比 Opus 的 $5/$25）；大 repo 的省钱替代 |
| Claude Sonnet 4.6 | 1M token | 按文件扩散时的主力，不需要 Opus 级判断时用它 |
| GPT-5.5 | 视应用而定 | 速度快、执行强；Terminal-Bench 2.0 82.7%，在 agentic 编辑器里好用 |
上下文规模在这里之所以关键：扩散的做法是把参考文件加目标文件一次喂进 prompt。1M token 窗口让你还能塞进相关类型定义或第二个参考，而这正是消除不一致的关键。如果你在 Cursor 这类编辑器里做迁移，它能路由到 Sonnet 4.6、Opus 4.7、GPT-5.5 和 Gemini 3.1 Pro，可以用同一条扩散 prompt 做 A/B。
容易踩的坑
- 一口气迁整个代码库——一面墙的改动，没法测、没法 bisect。
- 跳过参考实现，于是每个文件风格各异，reviewer 拒 PR。
- 不 dry-run 就信 AI codemod；它顺手改无关代码的频率比你想的高。
- 文件之间不跑测试，错误静默累积。
- 迁移和 feature 工作混在一起，坏掉的 commit 没法归因。
- 用训练时间早于框架迁移指南的模型——它给过时建议。钉上指南 URL 来对冲。
越用越省的技巧
- 每个 prompt 都钉上官方指南 URL，把模型留在官方路径。
- 大批量改名（prop 名、废弃生命周期、import 形态）用脚本 codemod 比 AI 准——AI 留给判断 case。
- 参考文件先走团队常规 code review 再扩散。文件 1 抓到的分歧，能省下文件 30 上的 50 条评论。
- codemod 阶段设”不带判断”规则：codemod 不能机械决定的就留
TODO手工 review，而不是瞎猜。 - 建一个内部 codemod 库。跨项目反复出现同样的模式（class 转 hooks、prop 改名、默认导入转命名导入）——写一次反复用。
FAQ
codemod 还是按文件让 AI 做？ 机械大头用 codemod；需要判断的部分按文件交给 AI。两者互补，不是二选一。
真实迁移要多久？ 随体量增长，但 AI 大致把机械的那 70% 减半。需要判断的 30% 两种方式耗时差不多，所以预算要按它算，而不是按大头算。
哪个模型最适合迁移？ 截至 2026 年 6 月：最难的一致性与判断活用 Claude Opus 4.7；想要同样的 1M 上下文又更省钱用 Gemini 3.1 Pro；按文件扩散的主力用 Sonnet 4.6。它们都胜过小上下文模型，因为迁移受益于同时看到参考和目标。
测试要同时迁吗？ 测试与源文件同步迁。让测试和源代码分叉是迁移停摆的常见原因——你会丢掉”这一步成功了”的信号。
官方指南不完整怎么办？ 去框架的 GitHub issues 搜迁移 tag。真实 edge case 住在 issues 里，而不是打磨过的指南里。
怎么 review 50 个 AI 迁的文件？ 按模式分组。共享同一迁移模式的文件作为一批——详读 2 个，其余扫读看是否偏离。