npm依赖管理：dependencies、devDependencies与peerDependencies的区别与实战

做前端或者 Node.js 开发的同学几乎每天都要和package.json打交道但真要说清楚dependencies、peerDependencies、devDependencies这三个字段有什么区别能讲明白的人其实不多。我见过太多项目线上崩溃是因为一个运行时依赖被写进了devDependencies也见过插件作者把 React 直接写进dependencies导致使用方装出两个 React 实例页面白屏半天查不出原因。这篇文章就围绕这三个字段把它们各自的定位、安装机制、传递规则、坑点一次性讲透。很多人以为这只是装生产依赖还是装开发依赖的简单选择题实际上背后牵扯到 npm 的依赖解析策略、模块寻址方式、以及包管理工具在安装时的落盘行为。理解透这三个字段不仅能帮你写出更规范的package.json还能让你面对node_modules里莫名其妙的包时有清晰的排查思路。1. 为什么 npm 要拆出三个依赖字段从依赖解析机制讲起1.1 依赖声明在装包时刻的三种去向package.json本质上是一份告诉包管理器该装什么、装到哪里、什么时候装的清单。npm 在安装一个项目时会分别读取dependencies、devDependencies、peerDependencies这三个字段然后按照不同的规则执行安装、传递和链接。先看一个最简单的例子{ name: my-app, dependencies: { lodash: ^4.17.21 }, devDependencies: { typescript: ^5.0.0 }, peerDependencies: { react: 17.0.0 } }当你在项目根目录执行npm install时npm 会做这几件事dependencies里的包会被安装到node_modules并且会写入package-lock.json最终会残留在npm install --production的环境里。devDependencies里的包同样会被安装到node_modules但不会进入npm install --production的安装范围通常也不会被引入生产环境。peerDependencies里的包比较特殊npm 不会主动为你安装它而是检查当前环境里是否已经存在这个包并且版本是否满足声明的范围。如果不存在npm 会给出警告在 npm v7 之后甚至会尝试自动安装。从这个层面看三个字段不是简单的生产/开发二分法而是分别对应了运行时必须的依赖、开发过程需要的依赖、宿主环境必须提供的依赖三种不同的场景。1.2 一条最简单的规则把它们想成三个不同的清单我经常用一个类比帮助团队新人理解dependencies是你做菜时需要买的食材缺了它菜就做不成上桌时必须齐备属于产品的一部分。devDependencies是厨房里的锅碗瓢盆、燃气灶只有做饭时需要用到客人吃饭时不会把这些东西端上桌。peerDependencies是你只负责提供菜谱但不负责买菜——你预设吃菜的人家里已经有某种调料比如盐你告诉对方请准备盐品牌不限至少是食用盐。如果对方家里没有盐你可以提醒但你不打包盐过去。这个类比能解释大多数场景但实际工程中还会有更复杂的情况比如插件、组件库、Babel 插件、ESLint 插件、Webpack loader 等这些场景下的peerDependencies不是可有可无的提醒而是绝对不能在插件内部直接依赖的硬约束这一点在后面第 3 部分会详细展开。2. dependencies 与 devDependencies运行时与开发时的分界线怎么划2.1 生产环境需要什么就放什么dependencies的筛选标准非常朴素项目在运行、构建产物在提供服务时离不开的第三方库必须放在这里。举例说明一个 Express 服务端项目express肯定是运行时依赖因为启动服务、处理请求都需要它。一个 React 前端项目构建之后会打包出静态文件但react和react-dom仍然应该放在dependencies因为在做 SSR、测试、或某些不经过打包的 Node.js 环境运行时它们依然是运行时代码的一部分。就算你的构建流程把 React 打进了 bundle构建产物可能还需要读取 React 的运行时数据结构。一个工具库、组件库它暴露给使用者的 API 依赖了某个第三方库那么这个库也必须放进dependencies否则使用者安装你的库之后import一个来自第三方库的函数会直接报模块不存在。如果你把运行时依赖错误地放进了devDependencies后果通常在 CI/CD 流程的安装生产依赖阶段暴露npm install --production npm run start # Error: Cannot find module lodash这类报错往往让新手摸不着头脑——明明本地npm install后运行一切正常为什么一到线上就缺模块因为本地安装时devDependencies也被一并安装了node_modules里什么都有而生产安装只装dependencies缺的那个包自然就找不到了。2.2 devDependencies 里到底该放什么devDependencies的筛选标准是这些包只在开发、构建、测试、代码检查阶段使用不会进入生产运行时的代码路径。典型成员包括构建工具webpack、vite、rollup、esbuild等。编译工具babel、typescript、sass、less等。代码检查与格式化eslint、prettier、stylelint等。测试框架jest、vitest、cypress、playwright等。各种类型声明包types/react、types/node、types/express等。Node.js 进程管理或开发热更新工具nodemon、ts-node、concurrently等。类型声明包是很多人的争议点。严格来说types/*只在 TypeScript 编译阶段被用到编译产物是 JavaScript运行时完全不关心类型定义所以放在devDependencies是正确的。但有一个例外如果你在开发一个 TypeScript 编写的库并且需要把d.ts文件一起发布给使用者那么这个库本身的类型依赖应该在dependencies里同步声明否则使用者在 IDE 里会看到一屏的类型报错。2.3 常见误判哪些包其实是运行时依赖我见过最经典的误判是把axios放进devDependencies理由是我只是在接口联调时用一下。但实际上只要你的业务代码在运行时import axios from axios它就是实打实的运行时依赖打包工具可能把它打进 chunk也可能走 CDN但开发环境和生产环境运行的代码都离不开它。还有一个高频错误是前端项目把vue-router、redux、react-redux放进了devDependencies。这些路由和状态管理库是应用运行时的一部分页面跳转、状态更新都要执行它们的代码放进devDependencies后如果你在某些场景下省略了devDependencies安装比如 Docker 构建时用了npm install --omitdev构建阶段可能勉强通过因为构建镜像里也许残留了缓存但一旦换一台干净的机器或者升级了包管理器问题立刻爆发。判断标准可以总结成一句话在最终产物的运行代码里import或者require到了某个包它就必须在dependencies里。打包工具、代码检查工具之类只存在于构建过程的才属于devDependencies。2.4 NODE_ENVproduction 时最容易踩的坑很多 Node.js 服务端项目习惯在启动命令里设置NODE_ENVproduction但这跟 npm 的依赖安装模式没有直接关系。npm install --production才是不安装devDependencies的安装模式NODE_ENVproduction只是应用层面的环境变量不会自动让 npm 跳过开发依赖。但某些部署平台会做聪明的处理比如先设置NODE_ENVproduction再执行npm install某些老版本 npm 会自动进入生产模式跳过devDependencies。这意味着你准备在部署机上跑测试脚本时会发现jest不存在进而报错。更稳妥的做法是如果需要同时安装开发依赖显式使用npm install --includedev或者干脆把NODE_ENV的设置放在npm install之后再执行。3. peerDependencies插件与宿主之间的契约3.1 为什么插件需要 peerDependencies 而不是 dependenciespeerDependencies的中文语义是同伴依赖它表达的是我这个包正常运行的前提是使用方宿主项目已经安装了某个版本的特定包并且我希望直接复用宿主环境里的那个包而不是自己再装一份。最典型的是 React 组件库。假设你开发了一个名为cool-ui的组件库内部使用了react和react-dom。如果你把react写进dependencies那么使用方安装cool-ui时npm 会顺便安装一份react哪怕宿主项目里已经有一个react也可能会装上第二个不同的版本。两个 React 共存会导致什么问题React 的hooks机制依赖内部的单例状态多个 React 实例会让useState、useContext在不同实例之间无法正确共享最常见的结果就是报错Invalid hook call或者组件状态诡异的错乱。这相当于你的插件在宿主环境里另起炉灶不仅浪费空间还会破坏 React 的单例约定。正确做法是把react和react-dom写进peerDependencies{ name: cool-ui, version: 1.0.0, peerDependencies: { react: 17.0.0, react-dom: 17.0.0 } }这样 npm 在安装cool-ui时会检查宿主项目里的react版本是否满足17.0.0满足就直接复用不满足就报警告。组件库本身不再打包 React代码体积更小也不会引发多实例冲突。3.2 npm v7/v8/v9 自动安装 peer 依赖后的行为变化这个变化非常关键很多人还在用 npm v6 的思路理解peerDependencies导致升级 npm 后项目行为大变。在 npm v6 时代peerDependencies如果缺失npm 只会在安装日志里输出一个警告依赖照装不误。但从 npm v7 开始npm 会把peerDependencies当作必须满足的依赖如果宿主项目里没有安装对应的包npm 会自动安装一份满足版本范围的最新版本。举个例子你的项目里安装了eslint-plugin-react这个插件声明peerDependencies: { eslint: ^7.0.0 || ^8.0.0 }但你的项目还没有安装eslint。npm v7 会直接把eslint装进node_modules。如果项目中已有的eslint版本不满足范围npm v7 会尝试安装一个满足范围的新版本如果新版本和其他依赖冲突就会报ERESOLVE错误。这个变化带来两个实际影响旧项目在 CI 环境中突然出现ERESOLVE unable to resolve dependency tree报错往往就是 npm v7 的 peer 依赖自动安装导致的。以前靠不装 peer 依赖就能跑的项目现在可能会被强制装上多余的包或者被版本冲突卡死。遇到这类问题我的建议是优先解决真实的版本冲突而不是一股脑用--legacy-peer-deps跳过校验。--legacy-peer-deps是保留旧版行为的快捷方式但长期依赖这个参数会让依赖树处在一种假装正常的状态隐患会一直留着。3.3 peerDependenciesMeta 与 optionalPeerDependenciespeerDependenciesMeta用来描述peerDependencies中的可选性。通过它你可以告诉 npm这个 peer 依赖不是必须的你没有的话也可以。 例如{ peerDependencies: { react: ^18.0.0, react-dom: ^18.0.0 }, peerDependenciesMeta: { react-dom: { optional: true } } }当你把react-dom标记为optional: true之后如果宿主项目只装了react没装react-domnpm 不会再因为缺少react-dom而报错也不会有严重的警告。实际开发中我会把一些仅用于增强功能的 peer 依赖标记为 optional比如何时使用 CSS-in-JS 方案的补充包、按需引入的图标库等避免使用方因为不愿意安装某个重量级依赖而放弃使用整个插件。npm 还支持optionalDependencies字段这跟peerDependenciesMeta是两回事。optionalDependencies指的是某个依赖安装失败不会影响整体安装过程程序运行时可以动态判断是否使用它。它解决的是装不上也不要紧的问题典型的例子是平台相关的包比如fsevents在 Windows 上会安装失败但代码里可以通过process.platform判断来跳过相关功能。3.4 组件库、插件和工程化工具中的真实场景peerDependencies在几个典型场景中的应用原则并不完全相同UI 组件库react、react-dom、vue必须是 peer。有些组件库还依赖antd之类的同层 UI 库这些也应该作为 peer而不是直接 dependencies。Babel 插件 / ESLint 插件需要把自己的宿主工具babel/core、eslint声明为 peer因为插件的解析对象来自宿主工具宿主工具的实例必须全局唯一。Webpack loader / pluginwebpack必须作为 peer因为 loader 内部会调用 webpack 的 API如果出现两份 webpackloader 可能会莫名其妙失效。构建工具链例如vitejs/plugin-react它的 peer 依赖是vite和react这是由插件必须与宿主同版本链运行的性质决定的。这里有一个容易被忽略的细节peerDependencies的版本范围应该尽量宽不要写死某个精确版本。很多插件会写react: ^18.0.0这个范围其实只允许 18.x如果宿主项目用 React 17npm 会报 peer 依赖不满足。合理的写法是尽可能覆盖主流大版本{ peerDependencies: { react: 16.8.0, react-dom: 16.8.0 } }不过范围也不能宽到没有语义比如写成*虽然安装时最省事但意味着你不对宿主版本做任何约束运行时如果遇到 API 不兼容问题会暴露在用户侧而且排查起来很难。4. 纸上谈兵装不出来的锅依赖字段错放引发的连锁故障4.1 把运行时依赖写进 devDependencies线上模块缺失我在第 2 节提到过这个问题的典型表现但这里想补充一个真实案例。之前帮一个团队排查线上 500 错误日志显示Error: Cannot find module dayjs这个项目是一个 Node.js 服务package.json里dayjs被放在了devDependencies开发环境的同事本地装完一切正常因为 dev 依赖全都在。但生产服务器的部署脚本执行的是npm ci --omitdevnpm ci会严格按照package-lock.json安装同时--omitdev跳过了 dev 依赖所以dayjs根本没被装上。第一次遇到这种问题的人会觉得很魔幻package.json 里明明写了dayjs为什么线上没有其实不是没有而是写错了字段。排查步骤也分享一下先看报错的模块是不是被import在业务代码中。查看它在package.json中的位置。确认部署环境是否使用--omitdev或--production安装。在本地模拟生产安装删除node_modules执行npm ci --omitdev然后尝试启动应用。这类故障的修复很简单把依赖从devDependencies挪到dependencies然后提交新的lockfile即可。关键在于dependencies与devDependencies的边界必须在写代码的那一刻就明确而不是等到 CI 出问题再返工。4.2 把插件核心依赖写进 dependencies重复实例与白屏组件库把react写进dependencies的案例我也见过不少。表面上看问题不大因为组件库确实能装上 React但运行时往往出现两个 React 实例。排查这类问题最有效的方式是在浏览器控制台执行window.React1 require(react) // 如果项目使用了 webpack 之类的打包工具这个办法不一定直接生效大多数情况下你会看到 React DevTools 提示 There are multiple instances of React on this page.。根源就是组件库的node_modules里放了一份 React宿主项目里还有一份 React浏览器加载时两个副本都被打进了 bundle。这个问题的修复方案有两个组件库把react挪到peerDependencies。如果组件库不好修改使用方可以用npm dedupe尝试去重或者配置打包工具的 alias强制所有react引用指向同一个路径。但这些都是绕过方式长期来看治标不治本。所以在开发任何给别人用的包时默认原则就是凡是宿主环境里应该已经存在的同层框架一律放进peerDependencies而不是dependencies。这个判断不需要犹豫。4.3 版本漂移与 lockfile 不提交的问题除了字段写错还有一类隐性故障来自dependencies的版本范围写得过于宽泛。假设你的dependencies写成{ lodash: ^4.17.21 }如果项目使用npm install而非npm ci每次安装时^4.17.21范围允许安装到4.17.x的最新版。周一安装可能拿到4.17.21周五安装可能拿到了4.17.23如果某个 patch 版本引入了行为变化你的代码可能昨天还能跑今天就挂了。这就是 lockfile 的价值。package-lock.json会把实际解析到的精确版本固定下来npm ci会完全按照 lockfile 安装确保每个人、每次构建的依赖树一致。但我见过不少项目把package-lock.json加进了.gitignore这等于放弃了 npm 最重要的可复现能力依赖漂移只是时间问题。我的习惯是dependencies的范围符号尽量保持合理——库的维护者写范围时需要能接受更新应用项目的dependencies最好依靠 lockfile 精确锁定package-lock.json必须提交到代码仓库npm ci才是 CI 环境的首选安装命令。4.4 一次典型的 these dependencies were not found 排查思路很多前端项目在跑vite或webpack时会遇到这样的报错These dependencies were not found: * /api/system/task in ./node_modules/cac这个报错的最终原因往往和package.json的三个字段有关但/api/system/task这个路径看起来又不像 npm 包名很可能是项目里路径别名的解析问题——构建工具在编译某个第三方包cac时遇到了不认识的/路径而/通常被配置为指向项目src下的某个目录。排查链路先确认报错来源是哪个文件、哪个依赖查看node_modules/cac中哪些代码引用了/api/system/task。确认/别名是在项目根级配置的还是只在构建配置里配置的。如果第三方包内部引用了/那说明这个包本身有路径解析问题或者依赖的某个子依赖版本不兼容。检查node_modules里是否存在多个版本的同一个包因为 npm 的扁平化 node_modules 在版本冲突时会进行嵌套安装嵌套包内部的路径解析有时候会采用错误的上下文。运行npm ls查看依赖树确认被报错文件所在的依赖版本是否与package.json中声明的范围一致。这类问题其实和peerDependencies也有关系如果cac声明了某个 peer 依赖但你没有安装对应的版本npm v7 可能自动装上了不兼容的版本导致cac内部解析失败。所以排查依赖相关报错时第一反应应该是查看npm ls输出其次才是考虑代码问题。5. 用最小 demo 彻底验证依赖安装规则5.1 准备一个双包工程来观察安装结果理论讲再多不如自己动手验证一遍。准备一个临时目录建两个包host-app模拟宿主项目依赖了my-lib。my-lib模拟一个组件库分别声明dependencies、devDependencies、peerDependencies。my-lib的package.json可以这样写{ name: my-lib, version: 1.0.0, dependencies: { is-number: ^7.0.0 }, devDependencies: { chalk: ^5.0.0 }, peerDependencies: { react: ^18.0.0 } }然后在host-app里通过npm install ../my-lib安装本地包。安装完成之后观察host-app/node_modules里会出现什么is-number会被安装因为它是my-lib的 dependenciesnpm 会自动传递安装。chalk不会被安装因为它是my-lib的 devDependencies作为依赖包安装时不会带devDependencies。react可能会被安装取决于你使用的 npm 版本和host-app里是否已有react。这个实验直观展示了三者的安装差异尤其是devDependencies的不传递特性很多人第一次跑这个实验时会有恍然大悟的感觉原来在安装一个本地依赖包时它的devDependencies根本不会被安装。5.2 各种安装模式下的 node_modules 差异验证接着在host-app里执行不同安装模式观察差异安装命令dependencies 是否安装devDependencies 是否安装peerDependencies 行为npm install是是缺失时自动安装npm v7npm install --production是否同npm installnpm install --omitdev是否同npm installnpm install --includedev是是同npm installnpm ci是按 lockfile是按 lockfile同npm installnpm ci --omitdev是否同npm install这个表格值得收藏。很多部署脚本里会混用--production、--omitdev、--onlyprod这些写法的效果基本一致但 npm 在不同版本里的推荐写法略有区别建议统一使用--omitdev更清晰也更靠近官方语义。5.3 用 npm ls、npm explain 定位依赖归因当node_modules里出现预期的包时可以用两个命令快速定位来源npm ls is-number npm explain is-numbernpm ls会显示依赖树中某个包的版本和路径npm explain会告诉你它是通过哪条路径被依赖上的。举个例子如果host-app里出现了chalk而你并没有在自己的dependencies里声明过它npm explain chalk的输出可能会显示chalk5.0.0 dev /host-app/node_modules/chalk root也可以这样定位某个包为什么会被安装。这套排查思路对理解三个依赖字段非常有帮助还能解决很多node_modules 里多了什么包、少了什么包的迷茫。6. 版本声明、锁定与迁移到 pnpm/yarn 的额外提醒6.1 semver 范围与 ^、~、精确版本依赖字段的值通常是 semver 范围表达式。工程里最高频的是这三个^1.2.3允许安装 1.x 的最新版但不允许 2.x。~1.2.3允许安装 1.2.x 的最新补丁版本但不允许 1.3.0。1.2.3精确固定为 1.2.3。很多人在写依赖时会默认全部使用^但对于拥有稳定 API 的库来说补丁版本可能只是修 bug升级是安全的但^允许的范围包含全部 minor 更新而 minor 更新可能引入新的 API 或行为变化。如果你更希望排除 minor 升级的风险可以使用~或者精确版本。在实际项目中包管理器写入package.json时的默认前缀取决于安装时的参数npm install lodash默认写入^npm install --save-exact lodash会写入精确版本。我个人的建议是应用项目尽量使用锁文件和npm cipackage.json里写^问题不大如果你维护的是供他人使用的库dependencies的范围最好宽松合理peerDependencies的范围适当放宽。6.2 lockfile 提交与依赖漂移治理只要项目存在超过一周就一定会遇到明明没改代码为什么同事那边装出来的包不一样的问题。原因几乎都出在 lockfile 未提交或安装命令不一致上。治理手段就三条package-lock.json必须提交到 git。CI 和本地统一使用npm ci不要用npm install做可复现安装。如果使用 yarn对应的是yarn.lock如果使用 pnpm对应的是pnpm-lock.yaml原理完全相同。另外要养成一个习惯每次手动改package.json后重新生成 lockfile 并检查 diff。不要直接在 lockfile 里手改版本那样很容易破坏锁文件的内部一致性导致后续npm ci报错。6.3 pnpm 的严格 node_modules 对依赖声明的校验如果你把项目迁移到 pnpm会立刻体验到一种不习惯pnpm 使用符号链接管理依赖默认的node_modules结构更严格。pnpm 会严格校验一个包是否只使用了自己声明的依赖如果代码里import了一个没有在package.json中声明的包在 npm 项目里往往能跑通但 pnpm 的严格模式下会直接报幽灵依赖相关的错误。这和本文主题强相关npm 允许你未声明就先使用是因为 node_modules 里实际存在这个包往往是依赖提升或嵌套安装的结果而 pnpm 明确告诉你这不是你的依赖别用。这其实是好事能倒逼你把dependencies、devDependencies、peerDependencies声明得清清楚楚。我见过不少项目在迁移 pnpm 后暴露出大量依赖字段缺失的问题修复后整个依赖结构健康了很多。6.4 我个人的依赖清单管理习惯最后分享几个我实际维护项目时沉淀下来的习惯不一定适合所有团队但至少能帮你少走弯路每次新增依赖时先问一句这个包在生产代码的哪个路径被引用如果只在构建脚本或者测试里被引用果断放devDependencies。如果你在开发一个库凡是使用方环境里已经具备的依赖一律放到peerDependencies并用peerDependenciesMeta把纯可选的项标记为optional。定期执行npm ls --depth0检查安装的顶层依赖有没有明显多余的。很多项目升级几年后package.json里保留了大量不再使用的依赖每次安装都在拖慢速度而且增加安全隐患。遇到EMAS、ERESOLVE之类的依赖冲突报错先尝试找到冲突的真实来源再决定是否使用--force或--legacy-peer-deps。把报错直接压下去很简单但压下去之后安装结果可能完全不符合package.json的声明预期。这三种依赖字段的差别本质上就是 npm 对依赖从哪里来、到哪里去、谁替谁负责的统一约定。真正的工程化不是会写npm install就完事而是能在每次报错时准确判断出依赖声明和实际安装行为之间的偏差出在哪一环。搞懂dependencies、peerDependencies、devDependencies的区别之后再回看很多莫名其妙的构建失败和线上崩溃你会发现那些问题的答案早就写在package.json里了。