npm Conflicting peer dependency 报错

如果你没有耐心看完全文，可以临时性地把 npm install 改为以下其中一个：

1. npm install --legacy-peer-deps
2. npm install --force

接下来解释为什么会报错？为什么以上两条命令有用？还有更好的解决办法吗？

这里以 @markdoc/next.js 为例子进行说明。

遇到的问题

@markdoc/next.js 0.2.0 版本的 peerDependencies 包括 @markdoc/markdoc 的 0.1.4 版本，后来 @markdoc/markdoc 从 0.1.4 升级到 0.2.0，但 @markdoc/next.js 依然使用 @markdoc/markdoc 的 0.1.4 版本。

此时，如果你的项目中的 package.json 是这样的：

"dependencies": {
    "@markdoc/markdoc": "^0.2.0",
    "@markdoc/next.js": "^0.2.0", //使用 @markdoc/markdoc 的 0.1.4 作为 peer dependency
}

此时执行 npm i 就会报错：

npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR!
npm ERR! While resolving: @markdoc/next.js@0.2.0
npm ERR! Found: @markdoc/markdoc@0.2.0
npm ERR! node_modules/@markdoc/markdoc
npm ERR!   @markdoc/markdoc@"^0.2.0" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer @markdoc/markdoc@"^0.1.4" from @markdoc/next.js@0.2.0
npm ERR! node_modules/@markdoc/next.js
npm ERR!   @markdoc/next.js@"^0.2.0" from the root project
npm ERR!
npm ERR! Conflicting peer dependency: @markdoc/markdoc@0.1.13
npm ERR! node_modules/@markdoc/markdoc
npm ERR!   peer @markdoc/markdoc@"^0.1.4" from @markdoc/next.js@0.2.0
npm ERR!   node_modules/@markdoc/next.js
npm ERR!     @markdoc/next.js@"^0.2.0" from the root project
npm ERR!
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force, or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.

需要注意的是，npm 7 及以上的版本才会报 Conflicting peer dependency 的错误，而 npm 4 ~ 6 不会报错，只会显示黄字警告。

这就是为什么使用 npm install --legacy-peer-deps 就能避开报错，因为 --legacy-peer-deps 的作用是告诉 npm 使用 npm 6 的模式安装依赖，npm 6 没 7 那么严格。

为什么

理由是 0.2.0 的 @markdoc/next.js 的 peerDependencies 指定的是 "@markdoc/markdoc": "^0.1.4"，"^0.1.4" 中的 ^ 表示：

Allows changes that do not modify the left-most non-zero element in the [major, minor, patch] tuple. （即版本号中，除了左边第一个不是零的数字外，其他数字都可以更新，出处）

具体地说：@markdoc/next.js 可以搭配 0.1.x 的 @markdoc/markdoc 使用，但不能搭配 0.2.x 的 @markdoc/markdoc 使用。

如果你非要安装 0.2.x 的 @markdoc/markdoc，npm 就会报 Conflicting peer dependency 错误，提示你 peer dependency 冲突了。

解决方法

有冲突并不代表无法使用，如果你确定这个冲突不影响使用，可以执行 npm i --force 或 npm i --legacy-peer-deps 正常安装依赖。

如果你不确定冲突是否影响使用，有两种解决方法：

1. 提醒 @markdoc/next.js 的开发者更新 peer dependency；
2. 按照 @markdoc/next.js 的 peer dependency 指定的版本号安装 @markdoc/markdoc；

值得注意的是，其实从 npm 7 开始，peer dependency 是会被自动安装的，无需额外添加。比如你在 package.json 声明使用 @markdoc/next.js，当你 npm i 时，npm 会自动地把 @markdoc/markdoc 也装上，所以把 "@markdoc/markdoc": "^0.2.0" 从 package.json 中删除就不冲突了：

"dependencies": {
    "@markdoc/next.js": "^0.2.0",
}

但并不建议这样做，因为自动安装 peer dependency 是 npm 7 及以上才有的功能，npm 4 ~ 6 并不会自动安装 peer dependency。如果你的同事还在使用 npm 4 ~ 6，当他 npm i 时，就会出现依赖缺少的问题，所以最好不要把 peer dependency 从 package.json 删除，建议暂时不要使用最新的 peer dependency：

"dependencies": {
    "@markdoc/markdoc": "^0.1.4", //暂时不要使用 0.2.0 版本
    "@markdoc/next.js": "^0.2.0", //peer dependency 是 0.1.4 版本
}