依赖升级总是挂在同样这四个地方：类型检查看不见的废弃 API、函数签名没动但行为变了、peer-dep 冲突静默解析成错误版本、单测抓不到的运行时回归。AI 编码 Agent 这四种都能搞定——前提是你给它该有的结构：官方 CHANGELOG、一份对应到你真实文件的破坏性变更清单，以及一个”绝不漂移到重构”的修复循环。
一句话总结
- 从绿色的
main拉分支，每个 PR 只升一个包。永远别盲跑npm audit fix --force。 - 把 Agent 锚在已发布的 CHANGELOG 上，而不是它的训练数据。让它返回一张把每条破坏性变更映射到本仓库
file:line的表格。 - 先把每个测试失败都归档，再逐一对应到某条 CHANGELOG 条目。对不上的失败说明你漏了一条破坏性变更。
- 用最小化 diff 修复、采用新 API；Agent 顺手塞进来的风格重构一律 revert。
- 类型检查过不等于”完成”。上线前先把 App 跑起来手工冒烟。没授权的传递依赖 major 用 pin 或
overrides锁住。
这篇主要解决什么问题
你接手一个项目，关键依赖已经落后 12 个 major；或者周五下午 5 点掉了安全公告，而 patched 版本藏在两个破坏性版本之后。CI 是绿的，但你不信这个版本锁。这套流程让一个开发者加一个 AI Agent，在一次专注会话里安全完成升级,并 ship 一份 CHANGELOG 映射好的 diff——reviewer 能逐行核对。
它对 npm/pnpm/yarn、pip、cargo、gem 都同样适用:CHANGELOG 锚定这一步与语言无关,只是安装命令和测试运行器不同。
什么时候用、什么时候别用
该用的时候:某个依赖落后好几个 major;CI 通过但你不信版本锁;被安全公告逼着升;接手一个废弃内部工具、其 lockfile 比公司当前 ESLint 配置还老。在动这个仓库的其他任何东西之前,先跑这套。
别用在完整框架迁移上——Vue 2→3、Angular major 到 major、Rails 大版本跳跃。那些需要专门的迁移计划,含 codemod、分阶段上线、常常还要 feature freeze,而不是一次升级跑。(那种场景看 AI 迁移 Prompt 工作流。)也别用在小型 prototype 仓库——按当前版本重新搭脚手架比升级还快。
开始前准备
- 确认
main上 CI 是绿的。main红就先修红,否则升级失败和既有失败混在一起,你分不清谁是谁。 - 写好冒烟测试方案: 那 3-4 条覆盖该依赖的手工路径。类型检查会过,冒烟测试才抓到真正的运行时回归。
- 定好升级边界。 就这一个包加它必须的 peer-dep,还是带上相邻包?默认一次一个包。
- 留好回滚方案。 老 lockfile 留在分支上,清楚自己的分支保护。把
package-lock.json做个git stash就够了,一条命令撤回一次失败的解析。
具体步骤
- 从绿色的
main拉分支。 跑npm ci(从 lockfile 干净安装,不是npm install),再跑完整测试套件。确认绿色基线。基线绿不了就停下,先修基线。 - 和 Agent 一起读 CHANGELOG。 让它:“我要把
[包]从[x]升到[y]。读该范围的官方 CHANGELOG 和迁移指南。列出每条可能影响这个 TypeScript 代码库的破坏性变更,我们用到的 API 有:[列出你用的]。“存下清单。 - 把破坏性变更映射到你的代码。 每条都问:“本仓库哪些文件用了受影响的 API?给
file:line。“点开逐一核对。一个列出一堆没真匹配文件的 Agent 就是在幻觉——要质疑它。 - 升级这一个包。
npm install package@y --save-exact(或你的运行器等价命令)。重新解析 lockfile。这次 commit 里别动任何其他依赖。 - 跑测试。归档失败。先别修。 列出每个失败:哪个测试文件、哪条 assertion、源码哪一行。
- 逐个失败和破坏性变更清单交叉对照。 每个失败都该对上清单里某一条。对不上,说明你漏了一条破坏性变更——回到第 2 步,把失败输出当证据重新 prompt。
- 逐条修复。 每个修复都该是采用新 API 的最小化 diff,而不是顺手重构周边代码。问它:“这是最小化改动,还是你在引入一个不匹配本代码库其他风格的新模式?”
- 跑完整套件 + 手工冒烟。 启动 App、走冒烟路径、盯着 network 面板和 console 看有没有新警告。类型检查过远远不够。
- 按 CHANGELOG 映射写 commit。 每个 commit 写明它处理的是哪条破坏性变更,这样 reviewer 能直接拿你的改动去对 CHANGELOG 章节。
破坏性变更映射 prompt
开着仓库,把这段贴进 Claude Code 或 Cursor。这是你每次都复用的那一个模板,只有前三行要改。
Package: [name]
Upgrade: [from-version] -> [to-version]
Codebase: TypeScript 5, Node 22, [framework]
读该范围的官方 CHANGELOG 和迁移指南。
返回一张 markdown 表格:
| 破坏性变更 | 受影响 API | 本仓库 file:line | 建议修法 |
只列影响本代码库的;我们没用的特性变更跳过。每行给出
CHANGELOG 章节引用,我要能核对。实战示例:React Router v6 升到 v7
这是 2026 年大多数 React 团队都会碰到的升级,也恰好说明为什么 future-flag 路径很关键。只要你先把 v6 的全部六个 future flag 打开,React Router v7 升级是零破坏性变更(见官方升级指南)。陷阱在于把它当成一次性硬切换。
CHANGELOG 映射的跑法是这样:
- 先升到最新的 v6.x minor,这样你拿到全部 future flag 和 console 警告。
- 让 Agent 把每个 flag 映射到它改变的行为——比如
v7_relativeSplatPath、v7_normalizeFormMethod、v7_partialHydration。一个一个打开,App 跑着,把每个 flag 冒出的 console 警告逐个修掉。 - 只有当六个 flag 全为
true且测试保持绿色,你才npm install react-router-dom@7 --save-exact。v7 里这些 flag 是默认值,所以你把它们从配置里删掉。
| 变更 | v6 写法 | v7 写法 | 不开 flag 的风险 |
|---|---|---|---|
| 相对 splat 路径 | 旧解析方式 | v7_relativeSplatPath | 嵌套 * 路由静默解析到错误 URL |
| Form method 大小写 | 混用 | v7_normalizeFormMethod | loader/action 里 formMethod 比较失效 |
| 部分 hydration | 全量 hydrate | v7_partialHydration | SSR 应用 hydrate 行为与测试不一致 |
逐个打开 flag,会把静默的行为差异变成可见的 console 警告,你就能一个一个修。这正是上面”归档 → 映射 → 修复”那套循环,只不过这回是维护者免费把清单递给你。
如果你的 App 部署到 Firebase Hosting,大版本路由升级之后紧接着跑 AI Firebase 部署检查工作流——这类升级经常打坏本地测试根本不会触发的 SPA rewrite 规则。
安全驱动的升级
npm audit 会把每条发现关联到一个 GitHub Security Advisory(GHSA)。2026 年要知道两件事:
- 别跑
npm audit fix --force然后就走开。--force会装上破坏性的大版本跳跃(比如把一个<7的包硬拉到8.x),这个”修复”接着就打坏你的 App。先读公告,再对那一个受影响的包跑这套流程。 - 大多数发现在传递依赖里,你
package.json里根本没有它的条目,没法直接npm install。用overrides(npm 8.3.0+)强制装上 patched 版本:
"overrides": {
"vulnerable-pkg": "1.4.2"
}只想在某一个父依赖下生效时,把它限定到那个父包:"overrides": { "loader-utils": { "ip-address": "9.0.5" } }。每次 override 后都重跑完整套件——强制一个嵌套版本可能引入它自己的不兼容。
(提个醒:npm 的旧 audit 端点在 2026 年 7 月 15 日之后退役;pnpm 和 yarn 用户要确认自己的 audit 工具走的是当前端点。)
AI 工作流 vs. 自动化机器人
用机器人扛量,用这套流程扛风险。两者互补,不是竞争关系。
| Dependabot | Renovate | 这套 AI 工作流 | |
|---|---|---|---|
| 最适合 | patch + minor 升级 | 规模化 patch/minor,分组 | major、高危 minor、安全逼升 |
| PR 数量 | 默认每个依赖每天 1 个 PR | 把上百个升级合进一个 PR | 一个包,一个 PR |
| 配置面 | 小,GitHub 原生 | 400+ 选项 | 一个可复用 prompt |
| CHANGELOG 到失败的追溯 | 无 | 无 | 有——这正是核心 |
Renovate 的分组通常能把 PR 数量比未分组的 Dependabot 减少三到五倍。让机器人清掉安全的 minor/patch 噪音,这套手动循环就专门留给真正会咬人的升级。
开 PR 前的质量检查
- 你失败清单里每一条都对应某条已知 CHANGELOG 条目吗?对不上的失败说明还有没发现的破坏性变更——回到第 2 步。
- 你是在跑起来的 App 上冒烟过吗,不是只过 CI?类型检查抓不到运行时回归,尤其是静默那种(一处日志变化、一个默认参数翻转)。
- Agent 加了无关重构吗?revert——它们属于另一个 PR。
- lockfile 解析干净吗,还是带进了某个你没授权的传递依赖 major?diff 一下
package-lock.json,有就用overridespin 住。
容易踩的坑
- 跳过 CHANGELOG 这一步。 Agent 会从训练数据猜破坏性变更,对你的精确版本范围可能是错的。一定要把它锚在已发布的 CHANGELOG 上。
- 升级途中让 Agent 做风格重构。 每个重构都给一个本该无聊的 PR 增加风险。留给另一波工作。
- 一次升多个包。 测试挂了你没法干净归因。一个包一个 PR。
- 不在跑起来的 App 上冒烟。 类型过了,App 却加载空白,因为一个默认 prop 翻了。手工冒烟不可省。
- 信任传递依赖解析。 lockfile 引入新的传递 major 就 pin 或
override,直到你也读过它的 CHANGELOG。 - CI 绿就算完。 生产环境有 CI 不复现的运行时配置。先上 staging。
FAQ
- 还要用 Dependabot 或 Renovate 吗? 要,用来跑安全的 patch 和 minor 升级。这套 AI 工作流在 major、高危 minor 以及已知有迁移痛点的包上发挥。让机器人清掉噪音。
- 废弃警告怎么办? 当作作业,不是阻塞项。两到四周内单独排一个 PR 清掉。让 deprecation 堆积,正是你最后”落后 12 个 major”的成因。
- 传递依赖怎么处理? 升级后审
package-lock.json。某个传递依赖跳了你没授权的 major,就用overrides(npm 8.3.0+)、resolutions(yarn)或 pnpm 的等价机制 pin 住。 - Agent 坚持某条破坏性变更和你无关、但其实有关怎么办? 把失败测试输出给它:“把这个失败和你说不适用的那条 CHANGELOG 条目对齐。“被直接递上矛盾时,Agent 会自纠。
- 能多 Agent 并行吗? 同一分支一次一个 Agent。同一升级里并行 Agent 会引发合并冲突,并毁掉让这个 PR 可审的 CHANGELOG 到失败追溯。
- npm、pip、cargo、gem 都适用吗? 都适用。只是安装命令和测试框架细节不同;CHANGELOG 锚定循环完全一致。