用 Codex 安全升级 Node.js 项目依赖

依赖升级不是把所有版本号改成 latest。安全升级需要先确认运行时要求、框架兼容关系和可回滚状态。

教程目标

完成后，你能让 Codex 完成一次有依据、可验证、可回滚的 Node.js 项目依赖升级。

开始前准备

• Git 工作区干净，或已经保存用户原有改动。
• 当前 package.json、锁文件和构建命令可用。
• 记录当前 Node.js 与 npm 版本。

第 1 步：只读审计

请只读审计当前 Node.js 项目的依赖，不要修改文件。

请输出：
1. 当前 Node.js、npm、框架和主要依赖版本。
2. package.json 与锁文件是否一致。
3. 直接依赖、间接依赖和安全漏洞分别有哪些。
4. 哪些可以补丁升级，哪些属于破坏性主版本升级。
5. 每次升级需要的 Node.js 最低版本和迁移文档。
6. 建议的分批顺序、验证命令和回滚方法。

第 2 步：先升级运行环境约束

如果新框架要求更高 Node.js 版本，先更新开发环境和 engines.node，再安装依赖。CI 与部署环境必须同步，不能只在一台电脑上升级成功。

第 3 步：分批升级

推荐顺序：

1. 补丁和次版本安全修复。
2. 构建工具与框架主版本。
3. 与框架绑定的插件。
4. 样式、测试和内容工具。
5. 移除已确认无用的依赖。

每批只解决一组兼容关系，保留独立 diff 和验证结果。

第 4 步：重新生成锁文件

使用项目选定的包管理器重新安装。不要混用 npm、pnpm 和 yarn，也不要在没有解释的情况下使用 --force 或 --legacy-peer-deps 隐藏冲突。

第 5 步：完整验证

至少检查：

• 内容或类型检查。
• lint、test、build。
• 安全审计。
• 关键页面和移动端视觉回归。
• 生成文件、锁文件和依赖树是否符合预期。

常见失败分支

• Peer dependency 冲突：先查插件支持范围，不要强装。
• Node engine 不满足：升级运行环境，不要长期忽略警告。
• 构建成功但页面变化：检查框架迁移说明和自定义组件覆盖点。
• 审计只能靠主版本修复：单独开升级任务并评估迁移成本。

验收结果

1. Node.js、框架、插件和锁文件版本彼此兼容。
2. 构建、测试、安全审计和关键页面回归都有结果记录。
3. diff 中没有无关依赖，且旧版本和回滚方法可追溯。

下一篇看：怎样看懂 Codex 的 diff 和修改总结。