从 UNMET PEER DEPENDENCY 中理解依赖版本管理
lang
中文
link
date
Dec 1, 2021
slug
unmet-peer-dependency
status
Published
tags
Tools
summary
日常开发过程中可能会遇到依赖管理器 npm 或 yarn 提示 unmet peer dependency,本文对提示出现的原因和依赖版本管理规则进行介绍
type
Post
什么是 UNMET PEER DEPENDENCY
当在使用 NPM 或 Yarn 命令时可能遇到过如下提示

🤔 什么,你说你没见过
UNMET PEER DEPENDENCY,翻译过来就是 “不满足对等依赖”,意思就是父依赖缺少了这个依赖的对等版本。拿上图例子来说,就是安装
maze-ui 这个包时,react 的版本需要满足 ≥ 17.0.2 和 < 18.0.0因此,我们可以通过 package.json 来查看项目当前的依赖。
"dependencies": {
"maze-ui": "^1.2.3",
"prop-types": "^15.7.2",
"react": "^18.0.0-beta-a65ceef37-20211130",
"react-dom": "^18.0.0-beta-a65ceef37-20211130",
}可见项目安装的
react 版本为 18.0.0 不满足 maze-ui 版本约束。其实这正是模块分析工具的需求痛点,项目下的某个包,往往会在依赖树的不同节点,存在多种版本。在包安装时,依赖管理器会检查这些版本约束,提示版本不兼容。在深究原因之前,我们需要了解平时常见的版本号规则,以及依赖管理器在 install 的时候是如何进行依赖管理的。依赖版本管理规则
当开发者在发布 NPM 包时,会在 package.json 的 dependencies 字段对相关依赖设定不同程度的约束:
"dependencies": {
"signale": "1.4.0",
"figlet": "*",
"react": "16.x",
"table": "~5.4.6",
"yargs": "^14.0.0"
}上面的这些版本号表示,都是基于 SemVer规范 而来的。它是由 Github 起草的一个具有指导意义的,统一的版本号表示规则。实际上就是 Semantic Version(语义化版本)的缩写。
SemVer规范官网:https://semver.org/
首先
x.y.z 分别对应 MAJOR.MINOR.PATCH (主版本号.次版本号.修订号)1. 主版本号:当你做了不兼容的 API 修改 2. 次版本号:当你做了向下兼容的功能性新增 3. 修订号:当你做了向下兼容的问题修正
前面三个包的形式很容易理解:
"signale": "1.4.0": // 固定版本号
"figlet": "*": // 任意版本(>=0.0.0)
"react": "16.x": // 匹配主要版本(>=16.0.0 <17.0.0)
"react": "16.3.x": // 匹配主要版本和次要版本(>=16.3.0 <16.4.0)^ 和 ~ 则比较特别,它们分别可以做到上面第三条规则和第四条规则的效果 (最高版本为最新版本),同时又兼容了主版本号 / 次版本号为 0 的情况:
- ~ : 当安装依赖时获取到有新版本时,安装到
x.y.z中z的最新的版本。即保持主版本号 / 次版本号不变的情况下,保持修订号的最新版本。
- ^ : 当安装依赖时获取到有新版本时,安装到
x.y.z中y和z都为最新版本。 即保持主版本号不变的情况下,保持次版本号、修订版本号为最新版本。
当主版本号为 0 的情况,会被认为是一个不稳定版本,情况与上面不同:
- 主版本号和次版本号都为 0:
^0.0.z、~0.0.z都被当作固定版本,安装依赖时均不会发生变化。
- 主版本号为 0:
^0.y.z表现和~0.y.z相同,只保持修订号为最新版本。
PS: 发布包的时候,我们也需要严格按 SemVer规范 来指定版本号,可以用 semver 这个包来帮助我们对版本号做一些比较。
- 安装
yarn add semver- 使用
semver.valid('1.2.3') // '1.2.3'
semver.valid('a.b.c') // null
semver.clean(' =v1.2.3 ') // '1.2.3'
semver.satisfies('1.2.3', '1.x || >=2.5.0 || 5.0.0 - 7.2.3') // true
semver.minVersion('>=1.0.0') // '1.0.0'间接依赖的结构
在理解了版本号规则之后,我们可以开始慢慢窥探 npm 依赖管理背后的问题了。开发者在 publish 一个 npm 包之后,或多或少要约束某些包的版本,防止相关依赖的更新,造成功能的变化,尤其是在相关依赖还没有经过完善的测试的情况下。比如说,我发布了一个 A 包,里面依赖了 lodash 的 ^2.2.0:
// node_modules/A/package.json
"dependencies": {
"lodash": "^2.2.0"
}在某个项目中,我使用到了 A 包:
// project/package.json
"dependencies": {
"A": "^1.0.0"
}对于 项目 → A 包 → lodash 这样一条简单的间接依赖链路,似乎没有看出太大问题,只要 A 包的开发者足够信任 lodash 的测试和发布环节,A 包的功能不会出太多岔子。我们尝试 npm install 之后,依赖树大概会是这样子的:
`-- A@1.1.0
`-- lodash@2.9.9显然 lodash 有着更新的版本,但 A 包的开发者并没使用到,它的 package.json 写死了低版本。这个时候假如现在我们的项目又引入了其他的依赖,比如说一个 B 包,人家用的 lodash 是最新的(
^4.17.20)。// project/package.json
"dependencies": {
"B": "^4.3.2",
"A": "^1.0.0"
}再次尝试 npm install,依赖树是这样子的:
+-- lodash@4.17.20
+-- B@4.3.2
`-- A@1.1.0
`-- lodash@2.9.9现在我们有两条间接依赖的链路了,分别是 项目 → A 包 → lodash,项目 → B 包 → lodash,而且 lodash 版本不相同,其中 B 包的 lodash 来到了和 A包 / B包同一层级的位置。这是 npm 3.x 版本以后 node_modules 的扁平结构。npm install 时会将dependencies 中位置靠前的包中的依赖,提升到上一级,这是为了解决 npm 3.x 版本之前嵌套结构造成的模块冗余问题,当父级目录的 lodash 能够满足 C 包、D 包等依赖的 lodash 版本,那么就不必重复安装,npm install 将会跳过这一过程。
再来看看文章开始我们安装
maze-ui 后项目的依赖树
react@18.0.0 被提升作为项目中 react 的版本依赖罪魁祸首 —— peerDependencies
到这里,我们大概已经知道 npm install 给我们的 node_modules 形成了怎样的结构,现在可以来看看 UNMET PEER DEPENDENCY 是怎么出现的了。首先来介绍一下,package.json 中和依赖管理相关的几个字段:
- dependencies 开发环境 / 生产环境依赖
- devDependencies 开发环境依赖包
- optionalDependencies 可选择的依赖包
- peerDependencies 同等依赖
- bundledDependencies 捆绑依赖包
前两个应该大家都比较了解,下面介绍一下剩下三个字段的作用:
optionalDependencies
optionalDependencies 指的是可以选择的依赖,当你希望某些依赖即使下载失败或者没有找到时,项目依然可以正常运行或者 npm 继续运行的时,就可以把这些依赖放在 optionalDependencies 对象中。
optionalDependencies 会覆盖 dependencies 中的同名依赖包,所以不要把一个包同时写进这两个对象中。
peerDependencies
peerDependencies 用于指定你当前的插件兼容的宿主必须要安装的包的版本。举个例子:有 react 组件库
maze-ui@1.2.x 的 package.json 中的配置如下:"peerDependencies": {
"react": "^17.0.2",
"react-dom": "^17.0.2",
},项目中我们使用
maze-ui@1.2.x 这个插件,此时我们的项目就必须先安装 react >= 17.0.2 和 react-dom >= 17.0.2 的版本。在 npm 2 中,peerDependencies 中指定的依赖会随着包一起被强制安装,所以我们不需要在宿主项目的 package.json 文件中指定 peerDependencies 中的依赖。 在 npm 3 中,不会再强制安装 peerDependencies 中所指定的包,而是通过警告的方式来提示我们,此时就需要手动在 package.json 文件中手动添加依赖。
bundledDependencies
与其他几种依赖项不同,他不是一个键值对的对象,而是一个数组,数组里是包名的字符串,例如:
{
"name": "project",
"version": "1.0.0",
"bundleDependencies": [
"axios",
"lodash"
]当使用 npm pack 的方式来打包时,上述的例子会生成一个 project-1.0.0.tgz 的文件,在使用了 bundledDependencies 后,打包时会把 Axios 和 Lodash 这两个依赖一起放入包中,之后有人使用 npm install project-1.0.0.tgz 下载包时,Axios 和 Lodash 这两个依赖也会被安装。需要注意的是安装之后 Axios 和 Lodash 这两个包的信息在 dependencies 中,并且不包括版本信息。
"bundleDependencies": [
"axios",
"lodash"
],
"dependencies": {
"axios": "*",
"lodash": "*"
},如果我们使用常规的 npm publish 来发布的话,这个属性是不会生效的,所以日常情况中使用的较少。
怎么解决 UNMET PEER DEPENDENCY ?
peerDependencies 尽管指定了使用某些插件时,必须要安装的包的版本。但在不影响开发的情况下,UNMET PEER DEPENDENCY一般是可以无视的,因为现存的很多UNMET PEER DEPENDENCY 错误,都将已安装的包版本指向了一个较低的版本。
或者这么说,开发者已经很久没对 peerDependencies 这个字段进行更新了,像我们在描述间接依赖的时候,A 包可能在 peerDependencies 这个字段里面,制定我们的 lodash 必须安装
^2.2.0 版本,可我们项目全局早就有一个 4.17.20 的船新版本了。如果我们手动安装
^2.2.0 版本,那不就覆盖了更新的 4.17.20 版本了嘛 😂,所以当出现这种问题了,其实应该尽可能要求包的发布者去更新一下peerDependencies。最后
其实这篇文章的重点,不在于说怎么去解决 UNMET PEER DEPENDENCY 这个问题,而是希望通过这个奇怪的现象,去理解包的依赖管理规则,以及 npm install 过程中的一些细节,便于今后我们使用或开发自己的 npm 包。
最后在放上文中提到
maze-ui 组件库,也是最近自己正在开发的组件库: