跳到正文

peerDependencies 的来龙去脉:从 ESLint 到依赖树冲突

2022 年,ESLint 刚推出 Flat config 的首个实现。Nicholas C. Zakas 回顾旧配置系统时,把早期最棘手的问题之一追溯到 2015 年的 npm 3。那一版停止自动安装 peerDependencies 后,一些项目能装完共享配置,跑 ESLint 时却找不到插件。等到 npm 7 恢复自动安装,ESLint 生态早已为这次变更付出了代价。

npm 7 恢复自动补装并在安装时求解 peer 后,另一批项目执行 npm install 时就遇到了冲突。Angular CLI 一度把 npm 限制在 6.x,Vue CLI 用户也遇到了升级失败。

为什么 npm 改了对 package.json 里一个字段的处理,有的项目装完却跑不了,有的项目连依赖都装不上?要回答这个问题,得先弄清 peerDependencies 约束的是谁和谁,再回到 npm 第一次为插件引入它的时候。

peerDependencies 是什么

peerDependencies 声明一个包需要和消费环境里的哪个依赖一起工作,以及它支持的版本范围。在插件体系里,这个依赖称为「宿主」,通常是 React 或 ESLint 这样的框架或工具。包作者声明兼容范围,消费环境提供宿主,包管理器据此判断两者能否配在一起。npm 文档也用插件与宿主之间的兼容关系解释这个字段。

普通依赖写在 dependencies,意思是「给这个包准备一份能用的依赖」。安装器可以让几个包共用同一个版本,也可以给每个包各装一份。写在 peerDependencies 里,意思是「让我用消费环境提供的那一份,并检查它在我的兼容范围内」。应用直接使用宿主时,通常就在自己的 dependencies 里声明它。消费关系还有中间层时,提供者也可能是安装了插件的框架或工具。

因此,检查 peer 要回答两个问题。宿主的版本在不在声明的范围里?这个包实际能不能解析到消费环境提供的那一份?如果宿主缺失,安装器可以提示消费方补齐,也可以尝试自己选一个符合范围的版本。是否自动补装、找不到合适的版本时是否中止安装,由包管理器决定。

React 组件库为什么要用 peer

假设有一个组件库 widget@1.0.0,里面的组件会从 react 导入 useState。它的 package.json 把 React 写在 peerDependencies,范围 ^19.0.0 表示接受 React 19.0.0 及后续的 19.x 正式版本。

{
  "name": "widget",
  "version": "1.0.0",
  "peerDependencies": {
    "react": "^19.0.0"
  }
}

应用用 react-dom 把组件渲染到网页上。它的 package.json 把组件库、React 和渲染器都列在 dependencies 里,并为这个应用选定 React 19.0.0。

{
  "name": "demo-app",
  "private": true,
  "dependencies": {
    "react": "19.0.0",
    "react-dom": "19.0.0",
    "widget": "1.0.0"
  }
}

两份清单里的 react 各有作用。应用说「这个项目用 React 19.0.0」,widget 说「我可以跟你选的这一版一起用,因为它满足 ^19.0.0」。React DOM 19.0.0 自己的包清单也声明了相同的 peer 范围,所以渲染器和组件库都要解析到应用提供的 React。

应用和组件库分别加载 React,与两者共用应用提供的 React

先看上半棵树。假如 widget 把 React 写进自己的 dependencies,安装器有可能在 widget 下面放一份独立的 React。应用和渲染器读到实例 A,组件库的 useState 却来自实例 B。react-dom 在实例 A 上设置当前渲染所用的 Hook 实现,实例 B 里的 useState 读不到它,于是可能触发 Invalid hook call。哪怕 A 和 B 都是 19.0.0,也会遇到这个问题。这里需要共用的是同一个模块对象。

再看下半棵树,它对应上面两份清单。应用节点往下的实线连着 react@19、react-dom 和 widget,对应应用的三个直接依赖。react-dom 和 widget 各自下面的虚线框 peer react@^19.0.0 表示它们的兼容范围。沿着两条虚线箭头往上找,终点都是应用提供的 react@19。两个包各声明了一条约束,应用提供的一份 React 同时满足了两条。

这个要求的范围是一套共同工作的渲染环境。同一个 monorepo 可以有两个独立应用,各自使用不同的 React,组件库也会按各自的消费环境绑定宿主。

普通依赖允许各用各的。应用用着一版日期处理库,组件用另一版,只要双方没有交换依赖特定实现的对象,就可以独立升级。安装器发现两个范围能共用一个版本时,还可以去重。Yarn 维护者在介绍 React 插件的依赖写法时,就用这个区别解释了为什么共享实例需要单独声明。

应用和组件各自使用一个日期库版本,两条调用链独立

早期 npm 用 peer 管插件和宿主的版本

Domenic Denicola 在 2013 年介绍 peer dependencies 时以 Chai 插件为例。chai-as-promised 1.x、2.x 配 Chai 0.5,3.x 则配 Chai 1.x。插件把支持范围写进元数据,安装器才知道两者要搭配使用。

chai-as-promised 的 1.x 和 2.x 配 Chai 0.5,3.x 配 Chai 1.x

这个字段最初进入 npm 1.2.0,经过几次修订,随 Node.js 0.8.19 分发的 npm 1.2.10 已能报告 peer 冲突。Denicola 给出的安装例子已经会把缺少的 Chai 一起装上。冲突则可以在安装时就暴露。他用 jitsu 依赖的 Flatiron 举例。jitsu 直接依赖 Flatiron 0.3.0,而 flatiron-cli-config 和 flatiron-cli-users 分别要求 Flatiron ~0.1.9 和 ~0.3.0,安装器找不到共用版本,最后由 jitsu 更新依赖来解决。

jitsu 的直接依赖 Flatiron 0.3.0 满足 flatiron-cli-users,但与 flatiron-cli-config 的范围冲突

npm 3 为什么停止自动补装

早期的自动安装经常卡在插件之间的版本冲突上。npm 团队的 Forrest Norvell 在 npm 3 的讨论里说,他们听到 Grunt、Gulp、Angular 等插件生态的反馈。安装因为 peer 冲突中止,用户不知道该先换哪个包。有些自动补装还超出了预期,比如全局安装 Yeoman 时一并装上全局的 Bower 和 Grunt。npm 3 因此把选择宿主的责任交给项目,等依赖树解析完成再检查 peer。缺失或不兼容时先给警告,让安装有机会继续。

npm 3 的变更记录还宣布了另一项改动,尽量把依赖提升到项目顶层的 node_modules。提升决定的是已经选中的包放在哪里。停止补装决定的是缺失的包会不会被选进树里。旧 ESLint 共享配置遇到的问题,恰好涉及这两件事。

旧 ESLint 配置靠什么找到插件

ESLint 的规则插件也有宿主约束,调用方向和 React 组件里用 Hook 的例子不同。一个规则即使从来没有 import 'eslint',它返回的访问器、收到的 context、用到的规则 API,仍然得符合执行它的那版 ESLint。到了共享配置这一层,还会遇到另一个问题,ESLint 得先找到配置指定的插件。

ESLint 调用规则并传入 context,插件即使不导入 ESLint 也依赖宿主 API

旧版 .eslintrc 里,共享配置常用 plugins: ['react']。这里传的是一个名字,后续由 ESLint 把它换成包名 eslint-plugin-react,再按查找规则(以 ESLint 7 为例)加载。共享配置即使在 dependencies 里列了插件,插件也可能只装在配置包下面,入口项目的查找路径未必能看到。早期支持 peer 的 npm 1.x 和 2.x 会把这类插件装到入口项目能查到的位置,旧配置就借助这一点把插件列为 peer。

到了 npm 3,插件只出现在共享配置的 peer 声明里,应用又没有显式安装它时,依赖树里可能根本没有这个插件可供提升。安装器发出警告后可以退出,ESLint 则还要解析配置里的字符串,缺的包会在这一步变成报错。共享配置能否用普通依赖提供插件,后来成了一个长期讨论的问题。

相同的 eslintrc 配置在 npm 2 会装插件,在 npm 3 只警告,直到运行 ESLint 才找不到插件

这也解释了 Airbnb 共享配置的安装说明为什么那么长。除了配置和 ESLint,还要装 eslint-plugin-import、eslint-plugin-react、eslint-plugin-react-hooks 和 eslint-plugin-jsx-a11y。它给了两种办法,用 install-peerdeps 一次装齐,或查出清单再逐个装。这份清单要由每个接入项目分别维护。下图用 eslint-config-airbnb@19.0.4 的包清单里的版本范围。

Airbnb 共享配置需要消费项目同时提供 ESLint 与四个插件

旧配置按名字查找插件,Flat config 由配置模块导入插件

Flat config 把插件的解析交还给模块系统。共享配置可以自己 import 插件,把得到的对象传给 ESLint。共享配置使用的插件可以放进自己的 dependencies,ESLint 本身仍是配置包的 peerDependencies。共享配置的发布说明也按这个分工组织。配置包负责提供自己组合好的插件,消费项目负责运行一版兼容的 ESLint。ESLint 在 2023 年的迁移计划里建议移动这类插件声明,v10 已移除旧的 eslintrc 配置系统。

npm 7 为什么把 peer 放回依赖求解

只发警告可以少打断安装,找宿主和排查冲突的工作却留给了每个消费项目。RFC 25 的动机记录了 npm 6 时期的一个后果。用户经常把警告报给库维护者,有的维护者干脆删掉了 peer 声明。警告随之消失,安装器也失去了检查插件兼容范围的依据。RFC 把这当作旧做法的代价。在比较维持现状的选项时,提案还特地点到 React 生态,刚接触 npm 的开发者要从一条警告开始追查该装什么,装完还要判断选的版本对不对。

缺少宿主是一类问题,装了宿主却绑错位置是另一类。RFC 举了测试工具 tap 的例子。它自带 React 16,并依赖同样需要 React 16 的终端界面库 ink。应用如果装了 React 15,旧安装器可能把 ink 提升到应用这一层,结果 ink 就读到了 React 15。即使 tap 已经带上正确的版本,安装器仍可能因为改变了依赖的位置而破坏这条约束。

ink 从 tap 的嵌套位置提升到应用层以后,查找到 React 15 而非 React 16

2019 年的 npm 路线图把恢复自动安装放进了安装器重写计划。到 npm 7,安装器在构建依赖树时就处理 peer。缺少必需宿主时会尝试选一个版本补齐,已经有宿主时也要检查插件实际会读到哪一份。按 RFC 25 的放置规则,插件应能从同层或上层解析到兼容的宿主。如果提升后的 ink 会读到 React 15,安装器就得另找一个能让它读到 React 16 的位置。

宿主在插件同层或上层可以满足 peer,装进插件自己的 node_modules 则无法满足这条关系

假设插件 A 支持 ESLint 8 和 9,插件 B 只支持 ESLint 9。两者共用同一个宿主时可以选 9。应用如果再明确要求 ESLint 10,三个范围就没有共同版本。分别给插件塞一份 ESLint 9,应用执行规则时依然用的是 ESLint 10。从 npm 7 起,这类顶层冲突会导致 ERESOLVE。较深层的冲突有时能换位置解决,有时 npm 默认会依据附近的普通依赖选一个版本并警告。开启 strict-peer-deps 后,这类默认能带警告通过的冲突也会导致失败。

两个插件的范围都接受 ESLint 9,加入项目对 ESLint 10 的要求后无解

一条约束怎样传到下游项目

应用显式选定的宿主,经常要同时满足几个插件的范围。要求它的包也可能是共享配置或脚手架带进来的,应用的 package.json 里甚至看不到那个包名。那些包原来发布的清单会在下游重新安装时按新规则处理。一个在 npm 6 里只产生警告的范围,到了 npm 7 就可能让整个项目找不到可用的依赖树。即使插件代码实际上已经兼容,只要已发布的范围排除了项目选定的版本,也可能得等上游发布修正。

改动还会随运行环境升级一起到达项目。npm 7 随 Node.js 15.0.0 和 Node.js 16.0.0 分发,Node.js 14.21.3 随附的则是 npm 6.14.18。如果 CI 直接用 Node.js 发行包附带的 npm,即使项目清单和代码没改,更换镜像也可能让重新安装走上另一套求解规则。

不同的 Node.js 发行包分别随附 npm 6 或 npm 7,更换运行环境可能改变依赖解析

脚手架还得决定能支持哪一代安装器。Angular CLI 10.2.2 的发布记录显示,它当时会在选用 npm 时检查版本,临时把上限设为 6。这道检查把一部分失败拦在 CLI 入口,项目还没走到依赖求解。

Angular CLI 10.2.2 使用 npm 时把支持上限暂时设为 6

Vue CLI 的安装日志能看见一条约束怎么从工具链传回应用。项目请求 vue@3.1.4,同时使用 TypeScript CLI 插件。插件把 @vue/compiler-sfc 列为可选 peer,但项目中已经存在 3.0.11 的编译器。这个编译器的 peer 精确要求 Vue 3.0.11,于是应用和编译器同时要求同一个宿主位置上的 Vue,却给了两个不同版本,npm 报出了 ERESOLVE。

Vue CLI 项目直接请求 Vue 3.1.4,TypeScript CLI 插件引用的编译器要求 Vue 3.0.11,npm 输出 ERESOLVE

Laravel Mix 6 的测试版则有一个深层冲突的例子。Mix 的清单同时依赖 webpack 5 和 webpack-dev-server。日志找到了 webpack 5.1.3,但开发服务器依赖的 webpack-dev-middleware@3.7.2 只接受 webpack 4。npm 7 给出的是覆盖 peer 的警告,和顶层冲突导致的退出错误属于两种结果。

Laravel Mix 一边依赖 webpack 5,另一边经 webpack-dev-server 引入要求 webpack 4 的中间件,npm 7 输出覆盖警告

这种冲突也可以在包管理器版本完全不变时出现。React 19 发布后,Create React App 创建项目时会选到 React 19,默认模板里的 @testing-library/react 则仍停在要求 React 18 的 13.x。两个版本分别看都有效,放进同一个新项目就可能装不上。这里变的是脚手架选到的宿主,安装器只是把已有的约束算了出来。

Create React App 选到 React 19,默认模板的 Testing Library 13.x 仍然要求 React 18

npm、Yarn 和 pnpm 各自怎么处理

安装时要分别看缺失时是否补装,以及版本不匹配时是否中止。还可以从应用和插件各加载一次,看看它们实际能读到哪一份宿主。

同一份清单会装出三种结果

建一个空项目,只安装 demo-peer-required。插件要求 is-number 的 ^7.0.0,入口会返回它实际读到的宿主版本。用三种安装器的默认配置,各自在空目录安装一次,再从项目和插件分别调用 require。各组输入的原始输出可以在 安装策略对照弹窗 里查到。

同样只安装插件,npm 的项目和插件都能读到宿主,pnpm 只有插件能读到,Yarn 报缺失

npm 把 is-number 作为 peer 补进依赖树。在这个项目里,它落到了应用也能查到的位置。pnpm 也补了 7.0.0,但只把它接到插件的依赖上下文,应用本身的 require('is-number') 会失败。Yarn 给出 YN0002,安装命令以 0 退出,插件启动时仍找不到宿主。Yarn 4 改用 nodeLinker: node-modules 重跑也没有补装。

迁移到 Yarn 时,如果应用只调用插件,要补上插件需要的宿主才能继续运行。如果应用自己也导入 is-number,它在 npm 默认布局中碰巧可用,换到 pnpm 或 Yarn 都可能失效。

自动补装还会把宿主及其传递依赖带进锁文件。要比较两个环境,先看它们是不是用同一个包管理器、版本和配置,再看锁文件。npm ci、pnpm install --frozen-lockfile 和 yarn install --immutable 各自复现自己的锁定结果。同一份 package.json 拿去换工具重算,求解策略和可见位置都可能变。

npm、pnpm 和 Yarn 各自用对应的锁文件和安装命令复现锁定结果

Yarn 会沿着消费关系检查谁提供了宿主

Yarn 在 2018 年对 Classic 的解释里,把 peer 讲成消费方提供给插件的一份依赖。Yarn 后来保留了这个分工,即使换了加载方式,也仍然从声明里确定谁负责提供宿主。

到 2020 年,两边的维护者已经在 Yarn 的 peer 默认值 RFC 里讨论过同一个问题。假设 monorepo 里的两个 workspace 分别使用 Next.js 和 Gatsby,各有自己的 Webpack。Next.js 的插件如果依靠提升碰巧找到 Webpack,可能拿到 Gatsby 的那一份。npm 的 Isaac Schlueter 提出,让框架和插件都声明 Webpack 为 peer,npm 7 就能在安装时给它们匹配同一份。Yarn 的 Maël Nison 也认可这条路径能满足例子的需求,同时希望把是否补装的选择留给包作者,避免改变已有包的安装行为。

两人还讨论了该去哪里找缺失的包。Nison 举了 Git 仓库的例子,同一条 peer 范围可以接受多个版本,作者的默认值却可能需要指向某个 Git 地址。Yarn 后来支持了带默认值的 peer。包作者同时声明 peer 和普通依赖,分别给出兼容范围和兜底来源。消费端提供宿主时优先使用那一份。2021 年,一条关于开发时补装项目自身 peer 的功能讨论再次提到 npm 7。Nison 解释,Yarn 把 peer 范围用于匹配已经解析的依赖,整体改成自动补装的收益不足以覆盖破坏性变更的代价。

Yarn 2 起的 Plug’n’Play(PnP) 把每个包能看到的依赖写进解析表,可以从声明上追问是哪一层提供了宿主。Nison 用过一个 Babel 共享 preset 的例子。应用使用自己的 @babel/core,共享 preset 再载入某个 Babel 插件时,preset 也要把 Core 作为 peer 接过来,插件才能沿同一条消费关系找到应用选的 Core。

应用提供 Babel Core,经由 preset 的 peer 声明传给 class properties 插件

把 Babel Core 换成实验里的 is-number,提供关系仍然一样。demo-app 同时依赖 is-number 和共享配置 demo-preset,配置又依赖 demo-peer-required。共享配置声明 is-number 为 peer,插件就能沿这条链找到应用提供的 7.0.0。

应用把 is-number 7.0.0 经共享配置的 peer 声明传给插件

在漏掉这条声明的对照组里,yarn explain peer-requirements 指出了断点在 preset。Yarn 4 默认的 pnpFallbackMode: dependencies-only 仍允许这个外部插件从顶层回退读取,换成 pnpFallbackMode: none 后加载就失败。补上 preset 的 peer 后,即使关闭回退也能运行。只测「当前能不能跑」会漏掉这种问题,安装诊断和包自己的依赖声明还要单独看。

对照默认回退、关闭回退与补齐 preset peer 三种情况

在实测的单层例子中,Yarn 2 和 3 用 YN0002 报缺失,用 YN0060 报版本不匹配。Yarn 4 也给出这两个代码,并附一条 YN0086 汇总。Yarn 2.4 引入的 p 编号可以查到参与约束的包。使用 nodeLinker: node-modules 会改变落盘和运行时查找方式。迁移时,如果以前靠提升碰巧拿到了宿主,应检查声明链和实际加载结果。

Yarn 用 YN0002 标记提供者缺失,用 YN0060 标记范围不匹配

pnpm 为什么把补装改成默认

pnpm 6.26 引入 auto-install-peers 时,它只在 pnpm add <包> 时把缺少的 peer 写进项目的 devDependencies。7.1.3 改成可在安装时补齐,同时保留项目原有的 package.json。这时选项默认还是关闭的。

pnpm 6.26 写开发依赖,7.1.3 支持安装时补齐,8.0 把自动补装设为默认

pnpm 8 的发布说明直接写了这组默认值的目标。从其他包管理器迁移过来时,用户此前常需要手动开启这些设置解决 peer 问题,改成默认开启可以少遇到这类问题。自动补装解决缺少宿主,从 workspace 根查找能用到已经声明的宿主,去重则合并可以共用的 peer 变体。发布说明把三项作为一组调整来讲。

在 pnpm 8 发布之前,也有人提出过只在某次命令上加 --peers。维护者 Zoltan Kochan 在当时的讨论里指出,这种开关如果只用一次,删掉锁文件后再用默认配置安装,peer 可能就不会重新装上。要让团队重算依赖树时沿用同一个策略,需要把设置留在项目里。

关掉 autoInstallPeers 后,pnpm 仍能给插件绑定一份已经存在的宿主。比如根项目声明 is-number,子项目 apps/consumer 只装插件,默认的 resolvePeersFromWorkspaceRoot: true 会让它找到根提供的 7.0.0。下图里发生的是解析已有的提供者,磁盘上的宿主来自根项目的直接依赖。

关闭自动补装后,pnpm 仍把 workspace 根提供的 is-number 绑定给子项目的插件

在这个用例里,同时关闭根查找和 dedupePeerDependents 后,插件在锁文件里失去了这条绑定,pnpm peers check 也报告缺失。加载探针仍能沿 Node.js 的目录查找碰到根项目的宿主。工作区其他位置已有的兼容包也可能经过去重被复用,验证可选 peer 缺席时宜用独立的消费项目。

关闭根查找和去重后锁文件没有 peer 绑定,但 Node 仍可能沿目录查找到根依赖

可选 peer 同样可能绑定工作区中已有的兼容版本。单独安装插件、环境里没有该宿主时,pnpm 默认不会因为可选 peer 而去 registry 新选一版。

pnpm 可复用工作区里已有的可选宿主,独立项目缺少它时允许缺席

各版本默认行为一览

包管理器 缺少必需 peer 项目直接提供了不匹配的 peer
npm 1.2 起、2.x 默认补装 旧解析器可能因 peer 冲突报错
npm 3–6 不补装,提示手动安装 警告,通常可以装完
npm 7–12 默认补装 顶层无解时 ERESOLVE。较深层冲突受位置和 strict-peer-deps 影响
Yarn Classic 1.x 不补装,警告 警告,通常可以装完
Yarn 2、3、4 不补装,由消费层提供,缺失时提示 YN0002 警告,通常可以装完。当前可用 yarn explain peer-requirements 查明谁提供、谁要求
pnpm 6.x 默认不补装 默认警告
pnpm 7.0–7.13 默认不补装,缺失时安装失败 默认严格,不匹配时安装失败
pnpm 7.14–7.33 不补装,警告 strict-peer-dependencies 默认改回 false,会警告
pnpm 8–12 默认补装缺失的必需 peer 默认警告,打开 strictPeerDependencies 后会把未满足的约束当作错误

版本基线是 2026 年 11 月 10 日的 npm 12.2.2、Yarn 4.18.1 和 pnpm 12.18.0。指定版本在全新项目里的退出码、警告和宿主加载结果,可以打开 安装对照记录弹窗 查阅。

扁平安装和符号链接会改变 React 从哪里加载

回到开头的 React 例子。应用、react-dom 和 widget 都在请求名为 react 的包,最后共不共用一份,要看三个入口分别解析到哪里。在同一个 Node.js 进程里,默认的 CommonJS 加载方式会跟随符号链接得到真实路径,并按解析出的文件名缓存模块。三个入口解析到同一路径,就会拿到同一个模块对象。即使文件内容和版本完全相同,走两个不同的真实路径也可能各执行一次。

npm 和 Yarn Classic 的提升会让一些依赖碰巧共用

npm 默认的 hoisted 布局和 Yarn Classic 的提升都会尝试把包往上放。假如 widget 把 React 写成普通依赖,而且它的范围允许复用应用的 react@19,安装器可能只在应用的 node_modules 放一份。组件库从自己的目录向上查找,就和渲染器找到了同一个 React。于是声明写错了也可能暂时跑得好好的。换一棵依赖树,组件库如果解析到自己下面的一份 React,就会出现开头树形图里的实例 A 和 B。提升还可能让应用碰巧读到自己从未声明过的间接依赖。

提升也能解释为什么有的 Yarn Classic 项目报了缺失 peer,却一直能运行。用 Yarn 1.22.22 实测,应用只安装两个示例包。demo-hoist-plugin 声明 is-number@^7.0.0 为 peer,demo-hoist-carrier 把 is-number@7.0.0 列为普通依赖。应用自己的清单里没有 is-number。Yarn Classic 按依赖关系检查 peer,对插件报了 unmet peer dependency。但另一个包带进来的 is-number 被提升到了应用的 node_modules,插件运行时沿目录向上查找,实际加载到了 7.0.0。移除带入宿主的包后全新安装,还是这条警告,插件这次加载失败了。

大型项目里,常用宿主有机会从别的依赖分支进入安装树。只要提升后的位置可见、版本也兼容,漏声明就可能一直没暴露。宿主没有其他来源时,提升没有包可搬。npm 3 到 6 同样采用提升,npm 7 的 RFC 仍记录了用户需要追查和手动补齐宿主的困难。pnpm 8 的发布说明则把默认补装和另外两项 peer 设置一起用来减少迁移问题。两次改动都降低了使用者手工处理缺失宿主的成本。

同样是提升,也可能把插件搬离原来的宿主。前面的 tap 已经为 ink 准备了 React 16,旧 npm 把 ink 提到应用层后,ink 的查找起点变了,结果读到了应用的 React 15。这就是 npm 7 在提升时也要把 peer 一起算进去的原因。

npm 把补来的宿主放在插件同层或上层

用 npm 12.2.2 在空项目里只安装 demo-peer-required。插件声明 is-number@^7.0.0,npm 把插件和自动补来的 is-number@7.0.0 都放进应用的顶层 node_modules。从应用或插件发起 require.resolve('is-number'),都能找到 node_modules/is-number/index.js。

npm 的放置规则要求插件从同层或上层找到兼容宿主。应用如果显式装了 is-number@6.0.0,直接安装在应用这一层的插件又要求 ^7.0.0,同一个位置就没有兼容解。这组安装实测报 ERESOLVE。把 7.0.0 放进插件自己的 node_modules 会让插件用上私有副本,满足不了这条 peer 关系。

两版宿主可以在各自的消费环境里共存。把插件移进 demo-peer-toolkit,由 toolkit 同时依赖插件和 is-number@7.0.0,应用仍显式使用 6.0.0。npm 把应用用的 6.0.0 留在顶层,把 toolkit 的插件和 7.0.0 装进同一层子目录。

node_modules/
├── is-number/                       # 6.0.0,应用显式声明
└── demo-peer-toolkit/
    └── node_modules/
        ├── demo-peer-required/      # peer: is-number@^7.0.0
        └── is-number/               # 7.0.0,toolkit 显式声明

Yarn 后续版本能不能靠提升找到宿主

从 Yarn 2 起,默认的 PnP 通过解析表确定一个包可以加载哪些依赖。用上面同一份应用清单和两个示例包,在 Yarn 4.18.1 上分别全新安装,再用 yarn node 从插件入口加载 is-number。三种设置的安装诊断都是 YN0002,运行结果取决于加载方式。

Yarn 4.18.1 设置 插件实际加载结果
默认 PnP 找不到 is-number。只有另一个依赖分支声明了它,插件的解析关系里没有这个宿主
nodeLinker: node-modules 加载到顶层 node_modules 中的 7.0.0,复现了 Classic 的表现
PnP 加 pnpMode: loose 加载到 7.0.0,运行时仍有警告。这个模式模拟了 Classic 提升后的可见性

默认 PnP 也有兼容性回退。前面的 preset 例子里,应用已经在顶层声明了 is-number,外部插件即使缺少中间那条声明,也能回退读取应用提供的版本。上面的新例子里,应用顶层没有这条依赖,默认 PnP 的回退也没有找到它。

两个应用分别提供 React 18 和 19 时,Yarn 可以给同一个 widget 版本分配两个虚拟路径。每个 widget 都会解析到对应应用提供的 React。即使两套 widget 引用同一份磁盘文件,运行时也可以有两个 widget 实例。

热门仓库里,新版 Yarn 也常配 node_modules

这次 GitHub 抽样取的是 2026 年 11 月 11 日的公开仓库快照。JavaScript 和 TypeScript 各按星标数取前 100 个,要求 5 月 1 日以来有推送,排除 fork 和归档仓库。按根目录的 packageManager 或锁文件,有 163 个仓库可以归类。原始记录和未归类的原因见 抽样步骤和逐仓库数据弹窗。

仓库主语言 npm pnpm Yarn Bun 未归类
JavaScript 51 10 11 1 27
TypeScript 24 47 12 7 10
合计 75 57 23 8 37

23 个 Yarn 仓库里,14 个用 Classic,9 个用 Yarn 4。这 9 个仓库都显式配置了 nodeLinker: node-modules。Prettier 从 Classic 升到 Yarn 3,到 Yarn 4 仍然保留 node_modules。Yarn 官方迁移指南也允许项目先保留原来的安装布局,再决定是否切换 PnP。

有些 Yarn 项目很少遇到缺失 peer 导致的运行故障,可能是因为应用自己声明了兼容宿主,也可能是插件靠提升读到了其他依赖带进来的宿主。抽样记录了包管理器版本和安装布局,哪些宿主由项目显式提供,还得逐个查依赖图。没有可用的宿主时,Yarn 即使装完,插件运行时仍可能找不到它。

pnpm 用符号链接把每个包接到自己的宿主

用 pnpm 12.18.0 在空项目里只安装同一个 demo-peer-required。在默认的 isolated 布局下,自动补来的宿主文件在虚拟存储里,插件所在目录旁边的 is-number 链接指向它。实测的目录如下,插件目录名中省略了本地 tarball 的标识。

node_modules/
├── demo-peer-required -> .pnpm/demo-peer-required@…/node_modules/demo-peer-required
└── .pnpm/
    ├── is-number@7.0.0/node_modules/is-number/
    ├── demo-peer-required@…/node_modules/
    │   ├── demo-peer-required/
    │   └── is-number -> ../../is-number@7.0.0/node_modules/is-number
    └── node_modules/
        └── is-number -> ../is-number@7.0.0/node_modules/is-number

插件沿同层链接加载到了 7.0.0。应用顶层只有插件的链接,所以应用自己的 require('is-number') 失败。.pnpm/node_modules 里的另一条链接来自 pnpm 的私有提升,供虚拟存储里的包查找。应用可见的顶层提升由 publicHoistPattern 控制,默认匹配列表为空。

应用如果显式提供宿主,pnpm 会给应用的 node_modules 建相应的链接。比如开头两份 React 清单在 pnpm 12.11.2 上的实测,应用、react-dom 和 widget 三个入口都解析到了 node_modules/.pnpm/react@19.0.0/node_modules/react。如果应用显式装的是 is-number@6.0.0,而同层插件要求 ^7.0.0,pnpm 12.18.0 默认给出 peer 警告,插件实际仍读到应用选的 6.0.0。打开 strictPeerDependencies 可以让这类不匹配阻断安装。

pnpm 用符号链接组织包之间的依赖,包的文件则可以用硬链接等方式复用。即使两个硬链接共享磁盘上的文件,Node 也可能因为解析出的路径不同而分别加载它们。

假设同一个 widget@1.0.0 同时兼容 React 18 和 19。两个子应用分别提供 React 18 和 19 时,pnpm 会按宿主组合给 widget 分配两套依赖目录。从 apps/a 导入 widget 会进入绑定 React 18 的目录,从 apps/b 导入则进入绑定 React 19 的目录。锁文件里可以出现两个 widget 条目,虽然组件库自己的版本没变。分别渲染时,每个应用都可以让自己的组件库和渲染器共用各自的 React。

两个子项目使用同一 widget 版本,pnpm 锁文件分别记录 React 18 和 React 19 的绑定

想改默认规则,可以改哪一层

如果想由应用显式提供宿主,同时保留安装检查,Yarn 默认就这么做,pnpm 可以单独关闭自动补装。npm 7 及以后的配置把「是否求解 peer」和「是否把选出的包写到磁盘」分成了两个开关。

npm 7 及以后区分求解和落盘

想让磁盘上只出现应用自己声明或经普通依赖引入的宿主,可以运行 npm install --omit=peer,或在消费项目根目录的 .npmrc 写 omit=peer。应用直接声明的 React 仍会正常安装。只由 peer 引入的宿主会留在磁盘之外,但 npm 依然会选出可行版本并记入 package-lock.json。顶层冲突仍可能报 ERESOLVE。如果项目漏声明了宿主,只要 npm 算得出兼容版本,安装就可能完成,等插件运行时才发现磁盘上没有这个包。

开启 --legacy-peer-deps 后,npm 则在构建树时跳过 peer 关系,原有的普通依赖仍照常安装。原本互斥的 peer 范围也可能被跳过。因此,要保留校验、又完全不为缺失的宿主选版本,npm 目前没有和 autoInstallPeers: false 等效的开关。

npm 默认安装、omit=peer 和 legacy-peer-deps 分别影响求解、锁文件和磁盘

要临时恢复自动补装,可以运行 npm install --legacy-peer-deps=false --include=peer。前一个选项恢复求解,后一个覆盖 omit=peer 的落盘省略。--include=peer 单独控制落盘,仍开着 legacy-peer-deps 时,求解器会跳过 peer。需要团队共享安装策略时,可以在项目的 .npmrc 里固定设置。若锁文件是在 --legacy-peer-deps 下生成的,npm ci 也应使用相同的树形设置。

include 覆盖 omit 的落盘设置,但无法恢复 legacy 跳过的 peer 求解,项目直接依赖仍会安装

npm 1.2 和 2 默认补,npm 3–6 默认由应用手动装。npm 2 的配置项和 npm 3–6 都没有上述这组独立开关。要在 npm 3–6 下把必需宿主补齐,可以让消费项目把宿主和插件一起列进清单。Airbnb 安装说明里的 install-peerdeps 就是代为执行显式安装的工具。

pnpm 可以分别控制补装与严格检查

pnpm 11、12 在项目根的 pnpm-workspace.yaml 使用驼峰字段。想关闭自动补装,可以这样配。

autoInstallPeers: false

关闭 autoInstallPeers 后,pnpm 仍会检查 peer,也能使用应用或 workspace 已经提供的兼容宿主。缺失或不兼容时,默认可以带着警告装完。团队希望这些问题直接阻断安装时,再加一行 strictPeerDependencies: true。

pnpm 的自动补装和严格检查分别决定宿主是否补齐及缺失时的退出码

pnpm 版本 怎么切换
6.26 之前 消费项目显式安装宿主
6.26–7.1.2 .npmrc 里的 auto-install-peers=true 作用于 pnpm add,把缺失项写进 devDependencies
7.1.3–7.x .npmrc 里显式开启 auto-install-peers=true,安装时补齐且无需改清单
8–10 默认已经开启,可用 .npmrc 的 auto-install-peers=false 关闭
11–12 在 pnpm-workspace.yaml 写 autoInstallPeers: true 或 false。从 11 起,普通 pnpm 设置由 YAML 文件承载

旧项目迁移时,先确认配置由哪一代 CLI 读取。7.14 前后还要留意严格检查默认值的变化。

如果两个插件要求 is-number 的 ^6.0.0 和 ^7.0.0,没有宿主的项目默认会收到警告,pnpm 不会随便补一版。启用 autoInstallPeersFromHighestMatch: true 后,pnpm 会把范围按 || 合并,再取命中其中任意一段的最高版本。这个用例里两个插件都会拿到 7.0.0,要求 ^6.0.0 的插件仍有冲突。这个设置解决的是要选哪个候选,无法让原先互斥的范围变得相容。

默认不补互斥的 peer,开启择高补装后两个插件都得到 7.0.0,但要求 6.x 的仍不满足

Yarn 由消费项目显式安装

Yarn Classic 和当前 Yarn 4 都没有对应 autoInstallPeers: true 的内置开关。用 yarn add 在消费包里安装宿主,例如 yarn add is-number@^7.0.0。如果宿主只用于开发时的 lint 或构建,使用 yarn add -D。在 monorepo 里,可以进对应目录运行,或用 yarn workspace <项目名> add 指定真正消费它的 workspace。yarn add -P 会把声明写进 peerDependencies,适合正在编写插件的包用来声明需求。

消费项目用 yarn add 或 yarn add -D 提供宿主,插件仓库用 yarn add -P 声明范围

如果问题出在第三方共享配置漏声明,可以用 .yarnrc.yml 的 packageExtensions 给那个配置补一条 peer,消费项目再显式提供宿主。以实验里的 demo-preset-loose 为例,应用已经装好 is-number@7.0.0 时,只需要补上转交关系。

packageExtensions:
  demo-preset-loose@1.0.0:
    peerDependencies:
      is-number: ^7.0.0

这个规则只修当前项目使用的依赖图。共享配置作者需要在发布包自己的 package.json 里修好,才能让下游都受益。

项目在 Yarn 配置里补上中间 preset 的 peer,让内部插件绑定应用已有的宿主

自动装还是手动装更合理

理想情况下,每个宿主都由实际运行它的应用、工具包或 workspace 显式提供,安装器负责检查版本和解析位置。应用自己用 react-dom 渲染组件,就在 dependencies 里选定 react 和 react-dom 的组合。应用在 CI 里运行 ESLint,也可以把 ESLint 和共享配置一起写进 devDependencies。升级这些宿主时,维护者能直接审查版本变更,并跑自己的渲染或 lint 测试。

大型项目里,逐个手动补齐整棵树的 peer 很难长期维护。比如应用只升级了一个共享配置,新版配置却引入了一个需要宿主的插件。应用的代码和清单里原本都没有这个插件,维护者得沿着间接依赖找到是谁要求宿主、需要哪个范围、该由哪一层提供。下一次升级可能又换了一套要求。不同子项目还可能各自需要一版宿主,根清单里的一个版本声明也表达不了这种关系。

自动补装把这部分工作交给安装器。缺少必需宿主时,安装器可以按声明找兼容版本,放到插件能解析到的位置。npm 7 的 RFC 提到让用户从警告里追查依赖的成本,pnpm 8 启用补装等默认设置也希望减少迁移时需要手动处理的 peer 问题。对已经用 npm 或 pnpm 的大型项目,保留自动补装是个务实的选择。应用显式声明自己使用的宿主,间接插件缺少必需宿主时让安装器尝试补齐。同一个宿主有互斥的版本要求时,维护者仍得调整插件或宿主的版本组合。

按运行者和提供者区分开发依赖、普通依赖、peer 和可选依赖

发布一个包时,什么时候该写 peer

依赖该写在哪个字段,取决于谁运行或选择宿主,以及包和调用方是否要共用它的 API、对象或状态。ESLint 插件、Babel 插件、React 组件库、Webpack loader 都可能需要 peer。独立 CLI 如果把解析器封装在内部,并由自己负责升级,解析器通常是普通依赖。

实际关系 声明位置 消费端怎么用
包自己控制的运行时实现,例如私有的解析、格式化工具 dependencies 安装包时带上它,由包维护兼容
宿主由调用方运行,包依赖它的扩展 API 或共享实例 peerDependencies 调用方在实际使用该包的应用或 workspace 提供宿主
宿主只在某个集成功能开启时使用 peerDependencies 加 peerDependenciesMeta 的 optional: true 用到该功能才安装对应宿主
包自行引入的可选运行时实现,安装失败后有降级路径 optionalDependencies 包负责探测是否可用以及如何降级
只在维护这个包时使用的构建、测试工具 devDependencies 发布后的消费项目无需提供

宿主确实由消费项目选定时,即使安装器的默认行为不同,发布包也应该保留 peerDependencies。如果有人反馈装不上,先核对报错里的宿主版本和包发布时写的范围。代码已经兼容就补测试、更新范围并发版。确实需要改代码才能支持的版本,继续让安装器指出冲突。如果核对后发现包可以独立管理自己的依赖,或对应功能允许宿主完全缺席,再考虑改成普通依赖或可选 peer。

开发时用一版,发布时声明兼容范围

回到开头的 widget。如果组件库自己的测试要导入 React,就在组件库本身的 package.json 加上开发用的版本。同一个包名可以出现在两个字段里。

{
  "name": "widget",
  "version": "1.0.0",
  "peerDependencies": {
    "react": "^19.0.0"
  },
  "devDependencies": {
    "react": "19.0.0"
  }
}

克隆组件库仓库、在这个包里安装和跑测试时,它的 package.json 就是开发项目的清单。devDependencies 提供了日常测试使用的 React 19.0.0。用户安装发布后的 widget 时,安装器读取的仍是这个包的清单,但库自己的开发依赖只服务于开发仓库。消费项目用自己的 package.json 提供 React,widget 的 peerDependencies 用来检查消费端选的版本是否符合范围。

工作区根目录可以给仓库级命令提供测试工具。如果某个宿主只由独立的示例或测试应用运行,也可以由那个应用声明,比如专门测试 ./portal 的应用提供 react-dom。这时组件库仍可声明对应的可选 peer,组件库本身要不要再写一条 devDependencies,取决于它自己的开发命令是否也会用到这个宿主。

用同一份发布声明支持不同包管理器

同一个 React 组件库可以用一份 peerDependencies 发给 npm、pnpm 和 Yarn 用户。安装说明写清支持的宿主范围,给出在实际消费的应用或 workspace 里同时声明组件库与宿主的示例。应用已经有兼容的 React 时,沿用它即可。这样 Yarn 用户可以直接使用,npm 和 pnpm 用户也有明确的版本选择。发布包表达的是兼容关系,是否自动补装由消费项目的包管理器和配置决定。库仓库里的 .npmrc 只影响在这个仓库里运行的 npm。

包即使不直接导入宿主,也可能需要转交它。typescript-eslint 的包清单把自己组合的 parser、插件等列在 dependencies,把 ESLint 和 TypeScript 列在 peerDependencies。消费项目运行它们,官方入门安装命令也把这些包一并列出来。独立发布共享配置时,可以照这个分工检查每条关系。把自己导入、维护的插件列作依赖,把需要由消费项目提供并传给内部插件的宿主列作 peer。

应用为 typescript-eslint 提供 ESLint 和 TypeScript,包自己引入 parser 和规则插件

Yarn 的 manifest 还有一种带默认值的 peer。如果同一个包名同时出现在 dependencies 和 peerDependencies,Yarn 可以先找消费端提供的宿主,找不到时回退到普通依赖。只有当包确实能独立使用自己的副本时,这种回退才符合它的职责。需要与应用共用 React 实例的库应保留 peer 契约,并让开发测试用的版本放在 devDependencies。

Yarn 带默认值的 peer 先找消费端宿主,缺席时回退到包声明的普通依赖

范围写到支持的最低版本,再用测试给它兜底

假设一个共享配置使用 ESLint 9.20.0 起才提供的能力,同时已经在 10.x 上验证过。它可以把 ESLint 9 的下限写到 9.20.0,用 || 纳入已支持的 10.x。配置自己导入的 eslint-plugin-acme 是这里的示例包,交给配置包维护。

{
  "name": "@acme/eslint-config",
  "dependencies": {
    "eslint-plugin-acme": "^2.4.0"
  },
  "peerDependencies": {
    "eslint": "^9.20.0 || ^10.0.0"
  },
  "devDependencies": {
    "eslint": "10.0.0"
  }
}

示例把日常开发用的 ESLint 固定在 10.0.0。兼容测试还要分别运行 9.20.0、10.0.0,以及准备支持的各主版本当前版本。假设其中某一支的最低版本跑不过,就提高对应下限,或者修改实现。配置包还要检查其插件本身的 peer 范围。上面的配置支持 ESLint 10,插件只支持 ESLint 9,消费端依然可能无法同时满足两条约束。

共享配置自己维护插件,消费端选择受支持的 ESLint,维护仓库单独固定测试版本

范围宽度按 API 和测试证据来定。npm 建议用范围表达已知兼容版本,例如 ^9.20.0 || ^10.0.0,避免 >=9.20.0 顺手承诺未来所有主版本。对于 0.x,^0.3.2 只允许同一个 0.3 系列内的更新。预发布版本有额外的匹配限制,想支持某个 RC 时应单列并实测。宿主的新主版本只有元数据过时的情况下,放宽范围才足够。用到了移除的 API,就得先改代码。提高最低版本、移除一支兼容范围会让部分原有消费项目无法再安装,应按破坏性变更评估。

用 ESLint 两代范围、0.x 和预发布版本示例比较 SemVer 匹配

可选的是宿主能否缺席

假设组件库的主体依赖 React,但只有 ./portal 入口使用 React DOM。可以把 react-dom 声明为可选 peer。

{
  "peerDependencies": {
    "react": "^18.2.0 || ^19.0.0",
    "react-dom": "^18.2.0 || ^19.0.0"
  },
  "peerDependenciesMeta": {
    "react-dom": {
      "optional": true
    }
  }
}

主入口不能在加载时就静态导入 react-dom 或转出会加载它的模块,否则即便安装成功,不用 Portal 的人也可能无法导入组件库。可以用独立子路径或按需导入,把加载留到功能被调用时。peerDependenciesMeta 的 optional: true 允许宿主缺席,npm 不会为此自动补装。项目已经提供了不兼容的 react-dom 时,包管理器仍可能警告或失败。此外,上面两个范围是各自判断的,React 和 React DOM 的版本配对仍要单独检查。

npm RFC 30 用 ORM 举过一个例子。它可以声明自己支持哪些数据库适配器以及版本范围,用户按实际使用的数据库安装对应适配器。把每种适配器都补进来,会连带装上项目用不到的依赖,有些还会执行安装脚本。

主入口只加载 React,Portal 子入口才使用消费项目提供的 React DOM

用打包后的消费项目验证

发布库时,可以先用 npm pack 生成 tarball,再安装进干净的消费项目。消费端显式装上希望验证的宿主版本,然后真的运行 ESLint 或渲染组件。用源码目录软链接时,库可能解析到开发仓库里的宿主,刚好掩盖了发布包的声明问题。对于打包后的 React 库,还要确认 React 以及 react/jsx-runtime 这类实际引用的子路径没有被打进产物。peerDependencies 是包管理器读的字段,是否外置要按构建工具的配置验证,例如 Vite 库模式的 external。

库如果支持多种包管理器,用同一份 tarball 验证应用显式提供宿主的情况,至少用关闭自动补装的 pnpm 或 Yarn PnP 跑一遍。安装说明如果还支持 npm 或 pnpm 自动补装,再单独测试这种装法。必需 peer 要测最低支持版本和各主版本,可选 peer 还要测宿主缺席和启用集成两种情况。对需要共享实例的库,可以比较应用与库解析到的模块,或者直接跑一次依赖共享状态的功能。一次安装成功只能说明依赖树建出来了。

源码软链接可能读到开发依赖,打包后的干净消费项目才测到真实发布边界

遇到安装冲突或重复 React 时怎么查

  1. 先找谁要求什么、谁实际提供了什么。npm 看错误中的 Found 和 Could not resolve dependency,已有安装树时用 npm explain <包名> 或 npm ls <包名>。Yarn 用 yarn explain peer-requirements <p 开头的编号>。pnpm 12 用 pnpm peers check 列出 peer 问题,再用 pnpm why <包名> 查来源。
  2. 缺宿主,就在实际消费它的项目或 workspace 明确声明。版本冲突,就一起看宿主和插件的发行记录,选它们共同支持的版本组合。修好中间包漏报的 peer 与放宽一个确实过时的范围,是两种不同的上游修复。
  3. 确认代码兼容、上游声明还没更新时,可以用项目级修补暂时恢复安装。Yarn 的 packageExtensions 可以补漏掉的声明,pnpm 的 peerDependencyRules.allowedVersions 可以针对特定包允许指定范围。把实际跑过的组合和对应的上游问题留在项目里,等新版本发布后移除规则。

项目在换包管理器时才报缺失,可以从「这个宿主原来由谁装进来的」开始查。若旧安装靠自动补装或根目录提升,先把宿主接到真正使用它的包,再决定是否需要临时的项目级配置。

安装成功后怀疑 React 重复,可以用 Node.js 的 createRequire,分别以应用、组件库和 react-dom 的入口文件为起点,比较各自 require.resolve('react') 的结果,或直接比较加载到的 React 对象。Yarn PnP 项目用 yarn node 跑这个检查。浏览器里仍然报错时,还要查构建产物,组件库可能已把自己的 React 打进 bundle。

分别按缺少宿主、宿主版本不匹配和中间包漏声明选择修复方式

热门公开仓库的包管理器和 Yarn 布局抽样

打开原文件 yarn-adoption-snapshot-2026-11-11.json

2026 年 11 月 11 日通过 GitHub 仓库搜索 API取两个查询的第一页。每个查询按星标数降序取 100 个结果,读取各自默认分支的根目录文件。

language:JavaScript archived:false fork:false pushed:>=2026-05-01
language:TypeScript archived:false fork:false pushed:>=2026-05-01
  1. 先找根目录 package.json。有可识别的 packageManager,就按该字段归类。否则检查 package-lock.json、npm-shrinkwrap.json、pnpm-lock.yaml、yarn.lock、bun.lock 和 bun.lockb。只有一种工具的锁文件信号时才归类。
  2. 对 Yarn 仓库先读 packageManager 里的主版本。只能用锁文件判断时,yarn lockfile v1 标记识别为 Classic,__metadata 识别为新版。新版仓库再核对 .yarnrc.yml 的 nodeLinker。有明确配置就按配置记录,未声明时还会找是否提交了 PnP 加载器。
  3. 未归类的 37 个仓库里,21 个根目录没有 package.json,14 个有清单但没有可识别的根目录信号,2 个有不同包管理器的锁文件且没有明确指定。原始 JSON 保留了每个仓库的默认分支、星标数、归类依据和可识别的 Yarn 布局。

这是热门公开仓库的根目录快照。仓库可能在子目录使用另一套工具,私有项目也不在样本内。样本里的布局和版本可以复核,项目的迁移动机和整体生态的采用率需要其他数据。

同一份 peer 声明在 14 个 CLI 版本上的表现

打开原文件 peer-install-results.txt

插件包 demo-peer-required 的 package.json 声明了一个必需 peer。它的入口读取 require('is-number/package.json').version,因此可以分开观察安装的退出码和安装后插件实际能加载到的版本。

{
  "name": "demo-peer-required",
  "version": "1.0.0",
  "peerDependencies": {
    "is-number": "^7.0.0"
  }
}

对照组 demo-peer-optional 用相同范围,再在 peerDependenciesMeta 中给 is-number 设置 optional: true。每次用全新消费项目安装对应 tarball,分别让项目不声明 is-number、明确提供 6.0.0 或明确提供 7.0.0。registry 只提供这两个版本。历史 CLI 使用可运行的 Node.js 版本,Yarn 2–4 使用默认 PnP,安装时关闭生命周期脚本。详细条件和诊断节选见原文件。

复现时,在插件目录保存这份清单和一个 index.js,内容为 module.exports = () => require('is-number/package.json').version,再运行 npm pack。把 tarball 复制到一个新目录,创建私有项目并在 dependencies 中通过 file:./demo-peer-required-1.0.0.tgz 声明插件。随后用目标 CLI 安装并运行 node -p "require('demo-peer-required')()"。Yarn PnP 项目用 yarn node 加载同一个表达式。每换一次宿主版本或包管理器,都重新准备一个消费目录。

观察项 实测结果
只装必需 peer 插件 npm 2.15.12、7.24.2、12.2.2 与 pnpm 8.0.0、12.18.0 都让插件加载到 7.0.0。npm 3.10.10、6.14.18 和所测 Yarn 版本有警告,但退出码为 0,插件找不到宿主
项目明确提供 6.0.0 npm 2.15.12 报 EPEERINVALID,npm 7.24.2、12.2.2 报 ERESOLVE。Yarn 4.18.1 和 pnpm 12.18.0 警告后继续,插件实际加载到 6.0.0
pnpm 7 的严格模式 7.1.0 缺失或不匹配时退出码为 1。7.33.5 对相同输入只警告。pnpm 12.18.0 显式开启 strictPeerDependencies 后,不匹配时再次报错
可选 peer 缺席或版本错误 受测且支持 peerDependenciesMeta 的版本允许它缺席。明确提供 6.0.0 时,npm 7、12 仍报冲突,Yarn 4 与 pnpm 12 默认警告
npm 12 的两种绕过选项 --legacy-peer-deps 下,项目提供 6.0.0 可以装完。--omit=peer 下,只装插件时不会在磁盘安装 7.0.0,但锁文件仍记录该版本。项目明确提供 6.0.0 时依然失败

先固定消费项目提供 is-number@6.0.0,看各安装器如何处理插件要求 ^7.0.0 的冲突。

显式安装 6.0.0 时,npm 2 和当前 npm 失败,受测 Yarn 和 pnpm 警告后加载 6.0.0

再把宿主移走,单独比较 pnpm 7 的两个版本。两者都不默认补装,退出码的差别来自严格检查。

pnpm 7.1.0 缺少必需 peer 时退出 1,pnpm 7.33.5 对同样输入警告后退出 0

把同一个宿主标成可选后,需要分开验证完全缺席与已经装了不兼容版本。

可选宿主缺席时允许安装,已安装 6.0.0 时仍与插件要求的 7.x 冲突

显式安装冲突版本时,--omit=peer 依然会求解这条约束。

面对已显式安装的冲突版本,legacy 跳过 peer 求解后成功,omit 仍然失败

pnpm 和 npm 2 在部分失败场景会留下可加载的包。这只能说明发生了部分落盘,安装是否成功仍看退出码。Yarn 或 pnpm 带警告装完也只说明生成了可用的依赖结构,插件的兼容性要靠自己的测试验证。

当前三个包管理器的 21 组安装策略对照

打开原文件 peer-install-modes.txt

所有场景都用独立项目和固定版本的本地 registry。demo-peer-required 要求 is-number 的 ^7.0.0。为了测试互斥范围,另加一个要求 ^6.0.0 的 demo-peer-legacy。在 Yarn 转交用例里,demo-preset-loose 和 demo-preset-forward 都依赖同一个插件,只有后者声明了相同的宿主 peer。

要核对什么 原始记录里的场景
默认补装与应用的导入权限 npm default、pnpm default、Yarn pnp-default / nm-default
npm 求解、落盘、直接依赖是否会被省略 legacy、omit、omit-include、legacy-include、omit-direct
pnpm 补装、严格检查和 workspace 根供给 no-auto、no-auto-strict、workspace-root、workspace-no-root
两段范围没有交集时,pnpm 是否仍会选一版 conflict、conflict-highest
Yarn 的回退加载和真正补齐声明有何区别 pnp-nested、pnp-no-fallback、pnp-forward、pnp-extension

输出里的 app 和 plugin 分别表示应用直接加载宿主和插件加载宿主的结果。pnpm 有两项要分开看。锁文件里 demo-peer-required 的版本后缀记录实际绑定,require 有时还会沿目录向上找到另一个可见的包。Yarn 用 yarn explain peer-requirements 查看负责提供宿主的包,便于在运行测试之外核对声明是否齐全。