让 AI 陪你做"不敢动"的升级：依赖与框架迁移的实践

一、为什么"升级"比"写新功能"更让人发怵

写新功能是加法，升级是在一栋住着人的房子里换承重墙。

老依赖、老写法、没人敢碰的模块，三五年攒下来的技术债，谁都知道该还，谁都不愿意先动手。原因很实际：风险不在"改"，而在"不知道会牵动什么"。

升级一个主版本，可能连带几十处 API 变更、配置调整、行为差异。逐条翻 changelog、逐个文件比对，枯燥且容易漏。人做这件事，往往三天热度，第五个文件就烦了。

这恰恰是 AI 能接过去的部分——它不厌倦比对，也不怕清单长。

二、AI 在迁移里真正擅长的三件事

用了一段时间后，我把它在迁移里的价值收在三件事上：

1. 摸清现状：盘点项目里用到了目标版本的哪些 API、哪些是已废弃用法、哪些是 breaking change 的雷区。这一步它翻文档、做统计比人快得多。
2. 起草"映射表"：把"旧 API → 新 API"的对应关系列出来，逐处标出位置和依据。有了这张表，改动就从"凭感觉"变成了"照单执行"。
3. 批量机械替换 + 逐处复核：纯机械的改名、签名调整、参数顺序变更，交给它；判断哪些需要人工确认，标出来留给你。

关键在于第三步的分寸：机械的放手，语义的收回。 它擅长前者，不该越界到后者。

三、我的迁移四步法

1. 先建安全网。这是唯一不可跳过的一步。迁移前必须确保项目能跑测试、能构建、有基本冒烟验证——否则你连"改坏了没有"都不知道。没有测试的地方，先补测试，再迁移。
2. 生成变更清单。让它对照目标版本，列出所有 breaking changes 和受影响的代码位置，形成一份可勾选的 checklist。大任务一旦显式化成清单，焦虑感会大幅下降。
3. 渐进式替换。按模块、按依赖推进，一次只动一处或一类。每步都能单独验证、单独回退——这点和重构是同一个道理，迁移同样怕"一次改太大"。
4. 回归 + 清理。跑完回归，再清理过渡期的兼容层和临时开关，别让"临时方案"变成永久债务。

四、几个关键技巧

• 从"叶子依赖"升起。先升级依赖最少、影响面最小的包，验证流程跑通了，再动核心依赖。别一上来就啃最硬的骨头。
• 让它解释每一处替换的"为什么"。能说清依据的替换才可信；说不清的，往往是它的想当然，必须人工确认。
• 保留兼容层作为过渡。适配器、polyfill、特性开关，可以让新旧共存一段时间，而不是一刀切铲平。代价是记得回头清理。
• 把清单当项目来管。迁移不是"一口气改完"，而是一份持续勾选的进度表——AI 帮你维护它，你负责拍板顺序。

五、几个不得不防的坑

• 版本幻觉。它可能"记得"一个新版 API，但签名、参数是错的。一切以官方 changelog 和实际编译结果为准，别信二手记忆。
• 迁移途中顺手重构。这是最容易翻车的组合——两件事的目标不同，“改完到底是迁移引入的 bug 还是重构引入的”，根本分不清。一次只做一件事。
• 没有安全网就全量迁移。能不能小步走，取决于你有没有可验证的回归手段；没有，就先补，别硬上。
• 低估配置与构建的变化。很多时候坑不在业务代码，而在构建配置、类型定义、环境变量这些"边角"。

六、结语

迁移的核心从来不是"改得多快"，而是每一步都可验证、可回退。

AI 把这里面最枯燥的部分——盘点、比对、机械替换——接了过去，让"想升却不敢升"的项目重新有了推进的可能。但安全网怎么搭、分批怎么切、哪一步该停，仍然得由人来定。

工具能替你消化枯燥，却替不了你对风险的判断——而升级这件事，判断比手速重要得多。