依赖版本冲突

一句话：项目中多个包要求的版本不一致，导致安装、构建或运行时出现冲突。

它是什么

依赖版本冲突常见于前端、Node.js、Python和移动端项目。比如一个包需要React 18，另一个包只支持React 17；或者TypeScript、Vite、ESLint、Tailwind等工具链版本不匹配。

适合干什么

• 安装开源项目遇到peer dependency错误的人
• 升级框架版本后构建失败的开发者
• 用AI改项目后依赖变乱的团队
• 需要维护老项目的人

不适合干什么

• 硬件、网络或权限导致的安装失败
• 没有依赖清单的项目
• 完全不愿意回滚版本的人
• 生产项目里随便强制忽略冲突的人

普通人怎么用

• 阅读报错里哪个包要求哪个版本
• 检查package.json里的相关依赖
• 优先按主框架版本选择兼容包
• 不要一上来强制安装
• 修复后重新运行测试和构建

进阶用户怎么用

• 用npm ls或pnpm why追踪依赖来源
• 建立升级分支单独处理大版本升级
• 锁定关键工具链版本
• 把依赖升级记录写进CHANGELOG

常见误区

• 看到冲突就直接--force
• 同时升级太多包，无法定位问题
• 只改package.json不更新锁文件
• 忽略peerDependencies提示

和相似工具的区别

• 依赖冲突 vs 模块找不到：依赖冲突是版本要求不兼容，模块找不到通常是包没装、路径错误或导出变化。
• 大版本升级 vs 补丁升级：大版本升级可能有破坏性变化，补丁升级通常用于修复小问题和安全漏洞。

入门步骤

• 定位冲突包
• 查看版本要求
• 确定主框架版本
• 选择兼容版本
• 更新锁文件
• 重新安装
• 运行测试

推荐工具（第三方）

npm、pnpm、Yarn、npm ls、pnpm why、Codex