很多人第一次用 AI 编程工具升级项目依赖，会直接说一句：“帮我把所有包更新到最新版。”这句话听起来省事，但风险很高。依赖升级不是改几个版本号，它会影响构建、类型、运行时行为、样式、部署脚本，甚至数据库连接和鉴权逻辑。
更稳的做法，是把 Codex、Claude Code、Cursor 当成执行助手，而不是让它自由更新。你需要先让 AI 盘点依赖、分级风险、提出更新顺序，再逐步验证。本文可以和 AI编程工具专题、老达AI实践专题 一起看。
先判断：这次升级到底为什么做
依赖升级不要只因为“很久没更新”。真正值得启动升级的原因通常有四类：
- 安全原因：某个包有已知漏洞，必须尽快升级或替换。
- 兼容原因：Node、Python、框架或部署平台升级后，旧依赖不再适配。
- 功能原因：新版本提供了项目需要的能力，例如更好的类型、API 或性能。
- 维护原因：旧版本已经停止维护，继续使用会让后续改动越来越难。
如果目的说不清，AI 很容易把一次小修变成大范围改造。站内的 AI编程需求变更控制 讲过类似问题：范围边界不清，AI 的“积极性”会放大风险。
第一步：让 AI 先做依赖盘点，不要直接修改
一个好用的开场指令不是“升级依赖”，而是：
请先阅读 package.json、lock 文件、构建配置、测试脚本和部署说明。
不要修改文件。
输出当前依赖清单、可能过期的核心依赖、风险最高的依赖、建议升级顺序，以及需要运行的验证命令。
这一步的目的，是让 AI 先建立项目地图。对 JavaScript 项目，重点看 package.json、package-lock.json、pnpm-lock.yaml、vite.config、next.config、测试配置和 CI 配置。对 Python 项目，重点看 pyproject.toml、requirements.txt、poetry.lock、uv.lock 和部署脚本。
如果项目本身没有清晰入口，可以先补一份简短说明。之前的 AI编程环境配置清单 和 AI编程上下文管理，都适合在升级前先补课。
第二步：按风险分层，而不是一次全升
依赖升级最怕“一锅端”。建议让 AI 把依赖分成三层：
- 低风险：开发工具、格式化工具、类型声明、文档相关依赖。
- 中风险：构建工具、测试框架、UI 组件、状态管理、HTTP 客户端。
- 高风险：运行时框架、认证库、数据库 ORM、支付、文件上传、权限中间件。
低风险依赖可以成组升级。中风险依赖要分批升级并运行对应测试。高风险依赖最好一个一个处理，每次升级后都留下结果记录。让 AI 先写升级计划，再让它执行第一批，是比较稳的节奏。
第三步：先更新锁文件，再看真实 diff
依赖升级的核心证据不是 AI 的解释，而是 diff。升级前先创建独立分支，升级后让 AI 汇总这些变化：
- 哪些依赖版本发生变化；
- 锁文件变化是否异常大；
- 是否引入新的大包、废弃包或同类重复包；
- 构建脚本、运行脚本、配置文件是否被改动；
- 业务代码是否为了兼容新版本被批量修改。
如果一次升级导致大量业务代码变化，就要暂停。依赖升级本身应该尽量可解释，如果 diff 已经看不懂，就不适合直接合并。
第四步：用测试和页面验收守住底线
AI 可以帮你跑命令，但验收标准要提前写清楚。最少要覆盖四类检查：
- 安装检查：依赖是否能干净安装，lock 文件是否稳定。
- 静态检查：lint、typecheck、格式化是否通过。
- 自动测试：单元测试、集成测试、关键脚本是否通过。
- 人工页面检查：登录、表单、支付、内容发布、后台管理等核心路径是否正常。
这一步可以直接复用 AI编程测试自动化 和 AI编程上线检查清单 的思路：不要只问 AI “有没有问题”，要让它运行命令、贴出失败点、解释影响范围。
第五步：高风险依赖要准备回滚方案
升级认证、数据库、支付、上传、缓存这类依赖时，必须提前准备回滚。回滚方案至少包括：
- 回到哪个提交或分支；
- 是否需要恢复 lock 文件；
- 是否改过环境变量或部署配置；
- 是否涉及数据迁移，能不能反向执行；
- 线上发布后观察哪些日志和指标。
如果 AI 建议顺手重构大量代码，要先拒绝。依赖升级和重构最好分开做。前者目标是“保持行为不变地完成版本更新”，后者目标才是改善结构。两个目标混在一起，出了问题很难定位。
一段更适合复制的 AI 指令
你是这个项目的依赖升级助手。
目标：只升级本轮指定依赖，尽量保持业务行为不变。
请按以下顺序工作：
1. 先阅读依赖文件、测试脚本、构建脚本和部署说明，不要修改。
2. 输出风险分级、升级顺序和需要验证的命令。
3. 等我确认后，只执行第一批低风险升级。
4. 每次升级后运行安装、lint、typecheck、test、build。
5. 如果失败，先解释原因和最小修复方案，不要扩大重构范围。
6. 最后输出变更摘要、验证结果、遗留风险和回滚方法。
这段指令的重点是把 AI 的动作限制在“先读、再计划、再分批执行”。对 Codex、Claude Code、Cursor 都适用，只是具体命令和权限提示会略有差异。
依赖升级后的交接记录怎么写
升级完成后，不要只留一句“已更新依赖”。建议让 AI 生成一份交接记录，包含：
- 升级范围：哪些包、从什么版本到什么版本；
- 修改文件：依赖文件、配置文件、业务文件分别有哪些；
- 验证命令：哪些通过，哪些未运行，原因是什么；
- 兼容调整：是否改过 API 调用、配置项或类型声明；
- 发布建议：是否适合立即上线，是否需要灰度观察；
- 回滚方法：出问题时怎么恢复。
如果团队里有其他人接手，这份记录比聊天记录更有价值。它能让后续维护者知道“为什么升级、怎么升级、有没有风险”。
老达点评
AI 编程让依赖升级变快了，但也更容易让人低估风险。真正靠谱的升级流程，不是让 AI 一次性把所有版本拉满，而是让它帮你看清依赖关系、拆小步骤、跑检查、保留回滚路径。
对个人站长、小团队和独立开发者来说，最实用的原则只有一句：凡是会影响运行时行为的依赖，都不要让 AI 悄悄升级。让它先解释，再分批执行，再用测试和页面验收说话。
