npm Conflicting peer dependency 报错

这里以 @markdoc/next.js 为例子分享 npm 为什么会报 Conflicting peer dependency 的错误，以及解决方法。

遇到的问题

@markdoc/next.js 0.2.0 版本的 peerDependencies 字段包括了 "@markdoc/markdoc": "^0.1.4"，后来 @markdoc/markdoc 也发布了 0.2.0，如果你项目中的 package.json 文件同时声明了使用这两个依赖的最新版本，即如下：

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

这时候 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，不会报错，只会显示黄字警告。

为什么

理由是 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.1.x 更新到 0.2.x 后，最左边第一个不是零的数字改变了，这是不允许的。

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

解决方法

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

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

• 提醒 @markdoc/next.js 的开发者更新 peer dependency 的版本号；
• 暂时不要安装最新版本的 @markdoc/markdoc，而是按照 @markdoc/next.js 的 peer dependency 指定的版本号安装 @markdoc/markdoc；

另外，npm 7 开始，npm 会自动安装 peer dependency。比如你在 package.json 声明使用 @markdoc/next.js，当你 npm i 时，npm 会自动地把 @markdoc/markdoc 也装上，因为 @markdoc/next.js 指定了 @markdoc/markdoc 作为它的 peer dependency。

所以对于第二种解决方案，我们只需要把 "@markdoc/next.js": "^0.2.0" 从 package.json 中删除即可，当然这可能不是最好的解决方法，如果你的项目是和其他开发者共同维护的，那其他开发者可能不知道你用了这个依赖。

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

另外 npm 4-6 不会自动安装 peer dependency，你必须同时安装这两个依赖：

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