Yarn安装冲突解决：resolutions与lockfile实践

脚本专家

Yarn 安装冲突是前端工程中的常见问题，通常可以分为依赖版本冲突和 yarn.lock 合并冲突两类。Yarn 对依赖版本有一套自动处理流程：自动版本协商、依赖提升（Hoisting）、重复安装去重（Dedupe），最后才需要人工通过 resolutions 干预。当不同包对同一个依赖的版本要求没有交集时，例如 antd@4.x 需要 react@^16/17，而 next.js@13.x 需要 react@^18，自动策略就会失效，此时必须人工统一版本。

先诊断冲突来源。可以用 yarn why 查看某个包被谁依赖、依赖了哪些版本，用 yarn list 查看完整依赖树；Yarn 4.x+ 还可以查看 peer dependency 冲突详情：

2. yarn why lodash
3. yarn list --pattern lodash
4. yarn explain peer-requirements <hash>

复制代码

依赖版本冲突的核心解决办法是在 package.json 中添加 resolutions 字段，强制统一依赖版本：

2. {
3.   "dependencies": {
4.     "antd": "^4.24.0",
5.     "next": "^13.0.0"
6.   },
7.   "resolutions": {
8.     "react": "18.2.0",
9.     "react-dom": "18.2.0"
10.   }
11. }

复制代码

如果需要更精确地控制子依赖版本，可以按包路径和通配路径写 resolutions：

2. {
3.   "resolutions": {
4.     "package-a/lodash": "4.17.21",
5.     "package-b/**/lodash": "^4.17.0"
6.   }
7. }

复制代码

修改 package.json 后重新执行 yarn install，让 resolutions 生效。

引擎版本冲突也需要区分处理。当 Yarn 提示 Node.js 版本不兼容时，可以用 yarn install --ignore-engines 做单次临时忽略，也可以用 yarn config set ignore-engines true 做全局配置。但推荐做法是升级 Node.js 到符合要求的版本，而不是永久忽略引擎检查。

Lockfile 合并冲突是团队协作中更棘手的问题。yarn.lock 在多人并行修改依赖时容易产生 Git 合并冲突。错误做法包括手动编辑冲突标记，以及直接删除 yarn.lock 后重新生成。手动改锁文件容易破坏依赖完整性；直接删除并重新生成会一次性升级所有依赖，引入不可控的回归风险。

方案一是在保留 package.json 合并结果的前提下重新生成 lockfile：

2. rm yarn.lock
3. yarn install
4. git add yarn.lock
5. git commit -m "Resolve yarn.lock conflict"

复制代码

方案二更安全，先恢复冲突前的 lockfile，再基于当前 package.json 做增量更新：

2. git log --oneline -5
3. git restore --source <commit-sha> yarn.lock
4. yarn install
5. git add yarn.lock
6. git commit -m "Resolve yarn.lock conflict"

复制代码

这种方式可以避免一次性升级所有依赖，只更新因为 package.json 变化而必要的部分。

预防冲突可以从团队规范入手。在 package.json 中设置 packageManager，确保团队使用一致的 Yarn 版本：

2. {
3.   "packageManager": "yarn@1.22.22"
4. }

复制代码

CI 中执行严格校验：Yarn 1 使用 yarn install --frozen-lockfile，Yarn 2+ 使用 yarn install --immutable，防止 lockfile 与 package.json 不同步。每次修改 package.json 后，必须一并提交 yarn.lock。定期执行 yarn audit 和 yarn upgrade-interactive，及时发现安全漏洞和过期依赖。如果准备升级到 Yarn Berry（v2+），可以执行 yarn set version berry，并引入 PnP 模式来更高效地管理依赖、减少冲突。

遇到安装冲突时，可以按以下顺序快速排查：先清理环境，执行 rm -rf node_modules yarn.lock 和 yarn cache clean；然后重新执行 yarn install；如果仍然冲突，用 yarn why <conflict-package> 查看依赖树；再通过 package.json 的 resolutions 强制统一版本；如果是引擎版本不兼容，可临时使用 yarn install --ignore-engines，或升级 Node.js 到推荐版本。