用 Codex 修改项目时，有一种问题很常见：

代码本来还能正常运行，Codex加了一个依赖、升级了一个包之后，项目突然开始报错。

常见表现包括：

• 原本可以启动，修改依赖后直接构建失败；

• 新功能能跑，旧功能却出现异常；

• 本地安装成功，其他同事拉代码后却报错；

• package.json 看起来没问题，锁文件却发生了大量变化；

• 一个包升级以后，另外几个依赖同时冲突；

• Codex为了修一个小问题，顺手把一批依赖都升级了。

这类问题往往不是业务代码本身写错。

真正需要排查的是：

依赖版本、锁文件、兼容范围以及项目原有环境有没有被改变。

---

一、先看Codex到底改了哪些依赖

遇到问题以后，不要第一时间继续执行：

npm install

或者让 Codex继续升级。

先查看：

git diff package.json

再检查：

git diff package-lock.json

如果使用 pnpm 或 yarn，则重点看：

pnpm-lock.yaml
yarn.lock

先回答三个问题：

1. 新增了哪些依赖？

2. 升级了哪些原有依赖？

3. 有没有删除依赖？

很多时候你以为Codex只是：

安装一个新库。

实际Diff里却可能同时出现：

react 18 → 19
typescript 5.4 → 5.8
某个UI库升级
多个间接依赖变化

真正引发问题的，可能根本不是最初新增的那个包。

---

二、不要只看“依赖存在”，还要看版本是否兼容

例如新代码需要：

library-x@5

但项目里的另一个插件只支持：

library-x@3

这时候两个包虽然都能安装，运行时却可能出现：

API不存在
类型不匹配
插件加载失败

所以遇到依赖错误时，不要只问：

这个包装了吗？

还要问：

当前版本和项目已有依赖是否兼容？

可以让 Codex先分析：

不要修改依赖，先检查新增依赖与现有主要包之间的版本兼容关系。

先定位冲突，再决定升级哪一边。

---

三、最危险的是“为了一个小功能升级整个依赖链”

比如任务只是：

增加一个Markdown解析功能。

理论上可能只需要新增一个库。

但如果Codex发现当前某些版本比较旧，顺手执行了一次大规模升级，就可能导致：

10个直接依赖变化
几十个间接依赖变化

这样一来，真正的风险已经远远超过原任务。

真实项目里应该尽量遵循：

最小依赖变更。

也就是：

能不升级就不升级；

只升级真正必要的包；

不要顺手做无关依赖整理。

任务描述里可以直接加一句：

如果现有依赖可以完成任务，不要升级无关包；如果必须升级，请先说明原因。

---

四、锁文件变化太大要重点检查

很多人只看：

package.json

觉得只增加了一行：

"xxx": "^2.0.0"

就认为影响很小。

但锁文件可能已经变化几百行。

因为新增一个包，往往还会带来一整套间接依赖。

所以可以执行：

git diff --stat

看看：

package-lock.json

到底变化了多少。

如果只是新增一个很小的依赖，却导致锁文件出现异常的大规模重写，就需要确认：

• 包管理器版本是不是变了；

• 锁文件格式是不是被升级；

• 是否重新解析了整个依赖树；

• 是否混用了 npm、pnpm、yarn。

---

五、不要混用不同包管理器

一个项目原本使用：

pnpm

如果Codex突然执行：

npm install

就可能多出：

package-lock.json

而项目本来已经有：

pnpm-lock.yaml

这时候仓库里同时存在两套锁文件。

不同环境安装出来的依赖树可能完全不一样。

所以进入项目以后，第一件事应该确认：

这个项目到底使用npm、pnpm还是yarn？

然后统一使用。

长期项目里最好在规则中明确：

项目只使用pnpm，不要执行npm install或yarn。

这样可以减少Agent自己选择包管理器导致的混乱。

---

六、注意语义化版本中的“^”和“~”

例如：

"axios": "^1.6.0"

这里并不一定意味着永远安装：

1.6.0

在符合版本规则的情况下，重新安装时可能拿到更新的小版本或次版本。

而：

"axios": "1.6.0"

则更加固定。

因此如果：

昨天项目能跑；

今天重新安装却出现异常；

也要检查是不是依赖版本范围允许安装了一个更新版本。

锁文件存在的一个重要意义，就是尽量保证团队和CI安装出一致版本。

---

七、Peer Dependency冲突不要直接强制跳过

安装依赖时经常会看到：

peer dependency conflict

很多人第一反应是使用：

--force

或者：

--legacy-peer-deps

确实可能让安装继续。

但安装成功不代表项目真正兼容。

Peer Dependency冲突通常是在提醒：

两个库对某个核心依赖的版本要求不同。

比如：

插件要求 React 18；

项目已经升级到 React 19。

强制安装以后，真正运行时仍然可能报错。

所以更稳的方式是先弄清楚：

谁要求什么版本。

再决定：

升级插件；

降低核心依赖；

还是更换其他库。

不要把“能装上”当成“兼容”。

---

八、依赖升级后，要检查API有没有变化

大版本升级经常带来Breaking Changes。

例如：

v2 → v3

可能意味着：

函数名改了；

参数格式变化；

默认行为改变；

某些API被删除。

这时候旧代码继续使用原写法，就会出现：

function not found

或者：

unexpected argument

所以如果Codex升级了依赖，最好同步检查：

当前代码使用的API是否仍然适用于新版本？

不要只看安装是否成功。

---

九、类型错误突然暴增，也可能是依赖版本造成的

TypeScript项目里特别明显。

例如升级一个类型库以后，突然出现：

20个类型错误

并不一定是20个业务逻辑同时坏了。

更可能是：

某个公共类型定义变化了。

例如：

原来允许：

string | undefined

新版变成：

string

于是所有调用方一起报错。

这时候应该先寻找共同根因。

不要让Codex逐个修改20个文件。

可以问：

这些类型错误是否由同一个依赖版本变化引起？先找共同原因，不要逐个修。

---

十、依赖升级以后，一定要运行原有测试

只验证新功能还不够。

假设Codex为了实现新功能升级了一个核心包。

新功能测试通过。

但旧模块可能已经受影响。

所以依赖变化以后，更建议执行：

Lint
↓
类型检查
↓
Build
↓
相关测试
↓
完整测试

依赖越底层，影响面通常越大。

比如修改：

React
Node
数据库驱动
HTTP客户端
测试框架

都应该更加谨慎。

---

十一、什么时候应该优先回退，而不是继续修？

如果只是增加一个小功能，却出现：

• 大量依赖冲突；

• 数十个类型错误；

• 多个旧功能测试失败；

• 锁文件大规模变化；

• 大量无关包被升级；

这时候继续修可能不是最优方案。

可以先问：

这个新功能是否真的需要升级这些核心依赖？

如果答案是否定的，更合理的方案可能是：

回退依赖变化，再找兼容当前版本的实现方式。

尤其是成熟项目，稳定性往往比“使用最新版依赖”更重要。

---

十二、一个稳定的依赖修改排查流程

以后Codex修改依赖后项目出问题，可以按照这个顺序：

第一步：查看依赖Diff

确认到底新增、升级、删除了什么。

第二步：检查锁文件

看变化规模是否符合预期。

第三步：确认包管理器

不要混用npm、pnpm、yarn。

第四步：检查版本兼容

特别是核心依赖和Peer Dependency。

第五步：检查API变化

确认新版本有没有Breaking Changes。

第六步：重新干净安装

排除本地旧环境影响。

第七步：运行完整验证

包括构建、类型检查和测试。

第八步：必要时回退

不要为了一个小功能强行修复几十个新问题。

---

十三、给Codex加一个“依赖保护规则”

以后涉及真实项目，可以提前写：

依赖修改要求：

1. 不升级与当前任务无关的依赖；
2. 新增依赖前先说明用途；
3. 不混用包管理器；
4. 修改package.json后检查锁文件；
5. 如果涉及Major版本升级，先说明Breaking Changes；
6. 完成后运行完整测试。

这会比任务结束以后才发现：

整个依赖树已经变了

更安全。

---

最后

Codex修改依赖后项目突然报错，真正的问题很多时候不是：

新代码本身写错了。

而是一次依赖变化可能同时影响：

版本、锁文件、API、类型、构建和测试。

尤其是成熟项目，不要把：

“能安装最新版”

理解成：

“就应该升级到最新版”。

更稳定的做法是：

最小变更、固定版本、检查锁文件、确认兼容，再运行完整测试。

如果只是一个小功能，却需要大规模升级整个依赖链，最好先停下来问一句：

这次升级真的有必要吗？

很多依赖问题，往往在这个问题上就能提前避免。

---

持续更新 Codex、大模型开发与 AI 编程实战内容，也会整理 AI 会员订阅与使用相关经验。更多技术内容欢迎搜索关注「仙逆GPT」。