上周三,新同事把仓库 clone 下来,npm install 跑完,npm run dev 直接报:
Module not found: Can't resolve 'lodash-es'
他的 package.json 和主分支一模一样,node_modules 是刚装的,Node 版本也对。同一时间,我这台机器跑得好好的。再一问,他用 npm,我用的是 pnpm;仓库里还同时躺着 package-lock.json 和 pnpm-lock.yaml 两个锁文件,README 没写到底该用哪个。
代码里那行 import debounce from "lodash-es" 是真的,但 package.json 里没有 lodash-es。它一直能跑,是因为 npm 把某个依赖的依赖提升到了 node_modules 顶层,恰好让这段代码蹭到了。pnpm 不做这种全局提升,于是「一直能用」的代码第一次装就断。
这篇讲什么:package.json 里的版本范围是什么意思,锁文件锁的到底是什么,npm 和 pnpm 装出来的目录为什么不同,幽灵依赖、重复版本和 peer 冲突怎么查。读完你能做到:让同一份代码在两台机器上装出同一棵树;看懂 ERESOLVE 这类报错;把一个老项目从 npm 迁到 pnpm,且知道迁移会暴露哪些历史问题。
事故现场:同一份代码,两台机器两种结果
很多人对依赖的理解是「package.json 里写了什么,就装什么」。实际上它只写了「允许装什么范围」。真正决定这次装到哪个版本的,是锁文件、registry 当时的状态,以及包管理器怎么摆放 node_modules。三个变量里任何一个不同,两台机器就可能得到不同的结果。
先把一次安装拆开看。它不是一个动作,而是四步:
出问题时,大家习惯盯着第一步看,改 package.json;但真正让人「昨天还好好的」的,往往是第二、第四步。锁文件换了,或者包管理器换了,依赖树就变了。
package.json 写的不是版本,是范围
依赖分四类,作用完全不同,放错位置会带来实际问题:
| 字段 | 放什么 | 放错的后果 |
|---|---|---|
dependencies | 运行时真正需要的包 | 漏放会让生产环境装不上;多放会把构建工具带进生产依赖 |
devDependencies | 构建、测试、类型、Lint 工具 | 放到 dependencies 会拖慢安装、增大产物体积 |
peerDependencies | 「我要求使用方也得装这个」 | 写成 dependencies 容易装出两份实例,单例失效 |
optionalDependencies | 装不上也能跑的包,比如平台相关的二进制 | 把关键依赖放这里,失败会被静默吞掉 |
版本号前面的符号不是装饰,是允许升级的边界。下面这张表以 1.4.2 为例:
| 写法 | 允许的范围 | 适合的场景 |
|---|---|---|
1.4.2 | 只装 1.4.2 | 需要绝对稳定,或者这个包发版不守规矩 |
~1.4.2 | 1.4.x,不跨到 1.5.0 | 只接受补丁修复 |
^1.4.2 | 1.x.x,不跨到 2.0.0 | 默认选择,接受新功能和内部修复 |
>=1.4.2 <2 | 1.x.x | 需要明确表达区间时 |
* 或留空 | 任何版本 | 基本不该出现在业务项目里 |
两个容易踩的细节。第一,0.x 版本不按常理出牌:^0.2.3 只允许 0.2.x,因为语义化版本规定主版本为 0 时 API 还不稳定,次版本号的变化都可能破坏兼容。第二,预发布版本默认不满足普通范围,^1.0.0 不会装到 1.1.0-beta.1,要显式写 ^1.1.0-beta.1 或更精确的版本。
还有一类「看起来是版本问题,其实是包本身的问题」:某些包在次版本里塞了破坏性改动,范围符拦不住。遇到这种情况,把范围收紧到具体版本,并在注释或变更日志里写清楚原因,比祈祷上游守规矩现实。
锁文件:把「这次装了什么」钉死
锁文件记录的不只是版本号,还有每个包的下载地址、完整性校验值和它自己的依赖关系。它的价值是「可重复」:只要锁文件不变,任何人、任何 CI 装出来的树应该一致。
三种常见锁文件:package-lock.json(npm)、pnpm-lock.yaml(pnpm)、yarn.lock(Yarn)。它们不能互相替代,也不建议一个仓库里同时存在两个。
关键是区分 npm install 和 npm ci:
npm install
会读锁文件,但也会根据 package.json 的范围更新它;会保留已有的 node_modules,做增量安装。适合日常开发。
npm ci
只认锁文件,先删掉整个 node_modules 再装;package.json 和锁文件对不上会直接失败。适合 CI 和线上构建。
npm ci 失败时的报错通常是:
npm error `npm ci` can only install packages when your package.json
and package-lock.json are in sync.
这不是 CI 环境坏了,而是有人改了 package.json 没提交锁文件。正确做法是本地跑一次 npm install,把新的锁文件一起提交,而不是在 CI 里改成 npm install 绕过。后者会让构建变得不可重复,今天过、明天挂。
锁文件冲突也很常见。两个分支各加了一个依赖,合并时 package-lock.json 几十行冲突。不要手改锁文件,也不要简单选一边。标准流程:先解决 package.json 的冲突,保留双方新增的依赖,然后删掉 node_modules 和锁文件重新安装一次,提交新生成的锁文件。手改的锁文件往往语法正确、语义错误,问题要到几天后装不上某个包才暴露。
files 字段排除锁文件,别把它发进包里。npm 与 pnpm,差的不是速度,是目录结构
两者最核心的差异在第四步「建立链接」:npm 把依赖尽量扁平地提升到 node_modules 顶层,pnpm 用内容寻址仓库加符号链接,只在顶层放你声明过的包。
扁平提升带来一个副作用,业内叫「幽灵依赖」:你用了包 A,A 依赖 B,npm 把 B 提到了顶层,于是你的代码可以直接 import "B",尽管你从没声明过它。这种代码在 npm 下能跑,换 pnpm 立刻报找不到;等哪天 A 升级换了依赖,B 被移走,你的代码又会突然坏。
这不是 pnpm 故意找麻烦,而是它把「你没声明的东西不该用」变成了硬约束。迁到 pnpm 时冒出来的一批报错,多半是过去几年攒下的幽灵依赖,属于迟早要还的债。
速度方面,pnpm 的优势主要来自全局内容仓库和硬链接:第二次装、多项目装、CI 有缓存时差距明显;首次在一个全新机器上装,网络才是瓶颈,别指望包管理器能变出带宽。磁盘占用差距更稳定,尤其是同时维护三四个项目的人。
Yarn 还有第三种形态 PnP,不生成 node_modules,直接从压缩包解析依赖。它最严格、安装最快,但对工具链兼容性要求高,生态里没适配的包会直接报错。团队没有明确收益诉求,不建议为了「先进」上 PnP。
幽灵依赖、重复版本与 peer 冲突
这三类问题看起来都是「装包出错」,排查路径完全不同,先分清再动手。
幽灵依赖的表现是「本地能跑,换包管理器或换机器就找不到模块」。查法很直接:看报错里的包名有没有出现在 package.json 里。没有就补声明,而不是去装一个「能跑」的旧版本。用 pnpm 时还可以 pnpm why 包名 看它是被谁带进来的。
重复版本更隐蔽。两个依赖分别要求 react@^17 和 react@^18,npm 可能同时装两份,各自被提升到不同层级。页面不报错,但 hooks 会报「Invalid hook call」,或者 Context 读不到,因为两份 React 是两套运行时。查法:
npm ls react
pnpm why react
# 输出里出现多个版本,就是重复了
解决方式不是删 node_modules 重装,而是统一版本。临时可以把其中一方升到兼容版本;确实升不动时,用覆盖规则强制统一:
// package.json(npm 10+)
{
"overrides": {
"react": "18.3.1"
}
}
// pnpm 放在 pnpm.overrides,或 pnpm-workspace.yaml 里
{
"pnpm": {
"overrides": {
"react": "18.3.1"
}
}
}
覆盖规则是强力的,也会掩盖真实的不兼容。用完记得在上游修,别把它当成永久方案;否则半年后升级依赖,没人记得这里埋了一个强制版本。
peer 冲突的典型报错是 ERESOLVE unable to resolve dependency tree。意思是某个包声明了「我需要 React 17」,而你装的是 18。npm 7 以后会自动安装 peer 依赖,也会因此更频繁地报冲突。
npm error While resolving: my-app@1.0.0
npm error Found: react@18.3.1
npm error Could not resolve dependency:
npm error peer react@"^17.0.0" from some-ui@2.4.0
先读最后两行:谁要求了什么版本,你实际装的是什么。能升就升 some-ui;升不了就评估 --legacy-peer-deps。这个参数让 npm 回到旧行为,忽略 peer 冲突,装是能装,但运行时可能真的不兼容。它适合「临时解封」,不适合写进 CI 配置长期使用。
pnpm 10 的构建脚本白名单
pnpm 10 收紧了依赖生命周期脚本:默认不执行第三方包的 postinstall。原因是供应链攻击里,恶意包最常用的入口就是安装时执行脚本。代价是某些需要编译或下载二进制的包(esbuild、sharp、better-sqlite3)装完不能用,会看到:
Ignored build scripts: esbuild, sharp.
Run "pnpm approve-builds" to pick which dependencies should be allowed to run scripts.
本地可以交互式放行:
pnpm approve-builds
CI 里没有交互,必须把白名单写进配置。以 pnpm 10 的常见写法为例:
// package.json
{
"pnpm": {
"onlyBuiltDependencies": ["esbuild", "sharp"]
}
}
完整场景走查:一个三年老项目迁到 pnpm
背景:一个后台管理系统,40 个直接依赖,锁文件里一千多个包,三个人维护。原来用 npm,CI 每次装依赖四分钟。团队决定迁到 pnpm,顺便把仓库里两个锁文件清理掉。
第一步,固定包管理器版本,并删掉旧的 package-lock.json。package.json 里加一行:
{
"packageManager": "pnpm@10.18.0"
}
这一步很重要。不写 packageManager,A 用 10、B 用 9,锁文件格式可能对不上,CI 也会因为版本差异报错。团队用 corepack 的话,进入目录会自动切到指定版本;没装 corepack 的机器需要手动装对应 pnpm(不同 Node 版本对 corepack 的处理有差异,按自己的 Node 发行说明来,待确认)。
第二步,转换锁文件。pnpm 提供了 pnpm import,能从 package-lock.json 生成 pnpm-lock.yaml,比从零解析更接近原来的版本组合:
pnpm import
pnpm install
第一次 pnpm install 就报了 Ignored build scripts: esbuild。按上一节的做法,用 pnpm approve-builds 放行 esbuild,把结果写进 package.json。这一步如果不做,本地开发服务器起不来,报的是二进制找不到,很容易误判成 Vite 坏了。
第三步,跑构建。构建失败,报 Cannot find module 'query-string'。查 package.json,确实没有这个包;pnpm why query-string 显示它是某个请求库的依赖。典型的幽灵依赖,过去靠 npm 提升活着。补进 dependencies 后解决。整个迁移一共暴露出四个这样的包,都是历史遗留。
第四步,改 CI。安装命令从 npm ci 换成 pnpm install --frozen-lockfile。pnpm 在 CI 环境默认就开启 frozen 行为,但显式写出来更清楚。缓存目录换成 pnpm 的 store:
- uses: actions/setup-node@v4
with:
node-version: 22
cache: pnpm
- run: pnpm install --frozen-lockfile
- run: pnpm run build
第一次流水线跑了六分钟,因为缓存是空的;第二次开始稳定在一分五十秒,构建本身占大头。安装时间从四分钟降到四十秒左右,冷装从三分半降到一分二十秒。这个收益在单项目上不算翻天覆地,但同时维护三个项目时,共享 store 省下的磁盘和重复下载更明显。
第五步,Docker 构建。这里最容易出错:镜像里没有 corepack,或者只拷了 package.json 没拷锁文件,导致每次构建都重新解析,装出来的版本和生产不一致。
FROM node:22-alpine AS build
WORKDIR /app
RUN corepack enable
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm run build
FROM nginx:1.27-alpine
COPY --from=build /app/dist /usr/share/nginx/html
COPY deploy/nginx.conf /etc/nginx/conf.d/default.conf
最后一步是收尾:删掉 README 里关于 npm 的说明,在仓库根目录加 .npmrc,把容易踩的默认值写清楚;CI 里加一条检查,确保只有 pnpm-lock.yaml 一个锁文件。迁移完成后,最难的不是命令,而是让所有人接受「没声明的包不能直接用」这条规则。它会让历史问题集中爆发一次,但爆发完,依赖关系就干净了。
错误现象对照
下面这些报错在装依赖、换包管理器、接 CI 时出现频率最高。先对现象,再看原因,最后按第三列查。
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
Can't resolve 'x',但本地曾经能跑 | 幽灵依赖,x 没在 package.json 声明,靠提升活着 | 搜 package.json 有没有 x,再跑 pnpm why x |
npm ci 报 lock 与 package.json 不同步 | 改了依赖没提交锁文件 | 本地 npm install 后看 git diff 是否有锁文件变化 |
ERESOLVE unable to resolve dependency tree | peer 依赖要求的版本与实际装的不一致 | 读报错最后两行,确认谁要求了什么版本 |
| 本地正常,CI 装出不同版本 | 锁文件没提交、registry 不同、Node 版本不同 | 对比两边的锁文件、.npmrc 和 Node 版本 |
| Invalid hook call,或 Context 读不到 | 同一个库装了两份,运行时实例不共享 | npm ls react 或 pnpm why react 看是否多版本 |
Ignored build scripts: esbuild | pnpm 10 默认拦截依赖的安装脚本 | 跑 pnpm approve-builds,再把白名单写进配置 |
| 锁文件合并冲突几十行 | 两个分支各自改了依赖 | 先合 package.json,删锁文件重装,不要手改 |
边界与代价
包管理器不是越严格越好,收益和项目规模直接相关。一个人维护的单页项目,npm 自带、零学习成本,没必要为了省几百兆磁盘去装 pnpm。项目的转折点通常出现在三个地方:多人协作开始出现「我这能跑」、CI 安装时间成为瓶颈、仓库从单项目变成多包 workspace。到了这三步,pnpm 的严格和共享才真正值钱。
严格也有代价。迁到 pnpm 的第一周,团队会被幽灵依赖集中打脸,构建失败、页面报错,看起来像「换个工具把项目搞坏了」。实际是过去的问题被提前暴露。管理者要接受这个短期的噪音,否则迁到一半又退回去,两套锁文件继续共存,问题只会更乱。
锁文件也有维护成本。依赖机器人每天开 PR 升级版本,锁文件跟着变,评审的人很难判断风险。可行的做法是:补丁和次要版本合并成一周一批,主版本单独开 PR 并写明迁移点;锁文件冲突的 PR 不手工合,让机器人重新生成。把「升级」当成一件有节奏的事,而不是随缘点合并。
覆盖规则和 --legacy-peer-deps 都是止痛药。用一次要留一条记录:为什么用、计划什么时候去掉。没有记录的覆盖规则会变成事实上的版本锁,下一代人不敢动,也不知道动了会怎样。
还有一个常被忽略的边界:私有 registry 和鉴权。.npmrc 里经常出现 token,提交到仓库就是泄露。用环境变量注入,把 .npmrc 里的敏感行排除在版本控制之外;CI 用仓库 secrets,不要写进命令行参数,命令行会进日志。
小结
npm ls、pnpm why 找到来源,再决定升级、覆盖还是放弃。这几件事今天就能在自己项目里验证:
- 把某个依赖的范围从
^改成~,删掉锁文件重装,用npm ls 包名对比实际版本。 - 删掉
node_modules,分别跑npm install和npm ci,观察哪个会删目录、哪个会改锁文件。 - 在 pnpm 项目里故意
import一个没声明的包,复现报错,再用pnpm why找到它的来源。 - 造一个 peer 冲突:装一个要求旧版 React 的组件库,读完整条
ERESOLVE,再尝试用overrides统一版本。 - 在 CI 里把安装命令从
npm install换成npm ci,看流水线是否因为锁文件不同步而失败,并修好它。
下一篇讲Vite 与打包。依赖装好只是原材料,接下来要回答的是:这些包和你的代码怎么变成浏览器能执行的文件,为什么开发时快得离谱,上线前却还要打包。这一篇里遇到的「装出来的版本不一样」,到下一篇会变成「本地和线上的产物不一样」,本质都是环境不一致。