dependency conflict 依赖冲突处理检查清单

依赖冲突排查要像查账，不能像抽奖。每一步都要知道自己看见了什么、判断了什么、改了什么。完整说明可以看 dependency conflict 依赖冲突怎么处理，这篇只保留可复制的检查项。

适合谁

适合安装项目时遇到 ERESOLVE、peer dependency、dependency tree、版本不兼容、构建失败的新手。你可以把这份清单放到文档、表格或项目诊断记录里。

也适合做客户项目初步排查的人。清单可以帮你先交付诊断，而不是在边界不清时直接改依赖树。

不适合谁

不适合正在处理生产项目、多人协作仓库、私有包、客户真实密钥或无法回滚的部署环境的新手独立操作。依赖调整会影响整个项目，不只是安装命令。

也不适合客户要求“别管原因，直接改到能跑”的任务。原因不清时，项目之后很可能在 build、test 或部署阶段再次失败。

风险提醒

不要默认删除锁文件，不要默认使用强制安装，不要默认升级所有包。每个动作都会改变项目依赖树。客户项目里要先确认分支、未提交改动、验证命令和回滚方式。

如果需要登录私有包源、访问客户仓库、配置 token、安装付费包或修改部署环境，先记录为待确认事项。没有确认前，只做本地日志分析和建议。

具体步骤

1. 报错记录

• 完整安装命令：
• 完整报错：
• 当前目录：
• 当前分支：
• 是否有未提交改动：

不要只复制最后一行错误。

2. 环境记录

• Node 版本：
• npm/yarn/pnpm 版本：
• 操作系统：
• 是否在 VS Code 终端：
• 是否在项目根目录：

依赖冲突有时来自版本，有时来自跑错目录。

3. 包管理器记录

• 是否有 package-lock.json：
• 是否有 yarn.lock：
• 是否有 pnpm-lock.yaml：
• 项目 README 推荐哪个包管理器：
• 最近是否混用过不同包管理器：

锁文件混乱时，先记录，不要立刻删除。

4. 冲突对象

• 冲突包名：
• 当前版本：
• 要求版本：
• 谁提出要求：
• 是直接依赖还是间接依赖：

看清“谁和谁冲突”，再谈修复。

5. 修复候选

• 固定兼容版本：
• 升级插件：
• 降级主包：
• 使用项目推荐的包管理器重新安装：
• 临时使用风险命令：

最后一项只适合在理解风险后尝试，并且要写进记录。

6. 验证命令

• install：
• lint：
• test：
• build：
• 启动页面或接口检查：

安装通过不等于修好。至少要运行项目要求的验证命令。

最低交付记录

交付记录至少写七项：报错、冲突包、原因判断、尝试动作、改动文件、验证结果、剩余风险。如果没有改代码，也可以交付“依赖冲突诊断报告”，但要说明哪些事项需要客户确认。

做项目时可以把服务分成两档：第一档只诊断并给建议；第二档在客户授权后调整依赖并验证。不要把两档混成一个模糊承诺。

判断结论怎么分级

检查完后，把结论分成四类会更清楚。第一类是环境问题，比如 Node 版本不符合项目要求、包管理器用错、命令跑错目录。第二类是依赖版本问题，比如主框架版本和插件要求不一致。第三类是项目规范问题，比如 README 要求使用 pnpm，但你用了 npm。第四类是权限或材料问题，比如私有包源、客户仓库、部署平台或 token 未授权。

这四类结论对应不同下一步。环境问题先补环境；版本问题先查兼容范围；项目规范问题先回到项目说明；权限或材料问题先让客户确认。不要把所有结论都写成“依赖冲突”，那样无法指导下一步。

如果你要把清单交给客户，建议写一句人能看懂的总结：当前失败主要来自哪一类，已经确认了哪些证据，下一步需要谁配合。这个总结比一堆命令输出更适合作为交付入口。

CTA：下一步

复制这份清单，先填报错、包管理器、锁文件和冲突对象。需要解释日志时，用 报错解释器；需要估算诊断时间时，用 报价计算器。

免责声明

本文是学习和排查流程，不构成法律、财务、安全或职业承诺。依赖版本、包管理器行为和项目约束会变化，实际修复必须结合项目文档、真实日志、测试结果和客户授权判断。