必须在合并前识别并统一版本，不能靠merge后手动删改；package.json冲突会破坏整个依赖树，导致npm install失败、ci卡住或require报错，需验证语义兼容性、协商版本、重建lock文件并提交。
依赖包版本冲突不是“改完代码就能推”的问题，它直接导致 npm install 失败、CI 构建卡住、甚至本地 require 报错——必须在合并前识别并统一版本，不能靠 merge 后手动删改 package.json 或 node_modules。
为什么 package.json 冲突比普通代码冲突更危险
普通文件冲突只影响逻辑，而 package.json 冲突会破坏整个依赖树：
- Git 只对比文本行，但
^1.2.0和~1.2.3在语义上可能兼容，Git 却判定为冲突； - 不同分支可能引入互不兼容的子依赖（比如 A 分支用
lodash@4.17.21，B 分支升级到@types/lodash@4.17.25但未同步主包）； - IDE 自动 resolve 时容易保留双版本字段（如两个
"react"字段），npm install直接报错； -
lock文件（package-lock.json或yarn.lock）若未提交或被忽略，会导致本地与 CI 环境行为不一致。
git merge 时遇到 package.json 冲突怎么办
不要直接删标记、不要盲目选 HEAD 或远端版本——先验证语义兼容性：
- 打开冲突文件，定位到
和 <code>>>>>> branch-name之间的dependencies/devDependencies区块； - 对每个冲突项，查 npm 官网或
npm view <pkg> versions --json</pkg>确认版本范围是否重叠（例如"axios": "^1.4.0"和"axios": "1.5.0"兼容）； - 若版本无交集（如
"typescript": "~4.9.5"vs"typescript": "^5.0.0"），需协商降级或升级，并同步检查tsconfig.json和构建脚本兼容性； - 解决后务必运行
npm install（或yarn install），确认node_modules重建成功且无 WARN/ERROR； - 生成新
package-lock.json并提交——这是关键动作，否则别人拉代码仍会装错版本。
如何避免下次再为依赖冲突停线
靠人工 merge 前 eyeball 版本是不可持续的，得从流程卡点：
- 所有分支基于同一
main提交拉出，每次git pull origin main后先npm install验证； - 在 CI 流程中加一步：
npm ci && npm ls <pkg></pkg>检查关键包是否唯一； - 用
resolutions（yarn）或overrides（npm >=8.3）强制统一子依赖，避免 “A 依赖 X@1.0，B 依赖 X@2.0” 导致的隐式冲突； - 禁用
npm install自动生成package-lock.json的行为，要求所有修改必须通过npm install <pkg>@version</pkg>显式声明。
依赖冲突真正难的不是解决，而是发现——很多人直到 npm run build 报 Cannot find module 'xxx' 才意识到 lock 文件没生效。把 lock 文件当成和源码同等重要的产物去管理，比纠结某一行 package.json 冲突重要得多。
