**这是本文档旧的修订版!**
npm 和 pnpm 的区别
两者都是 Node.js 的包管理器,命令高度兼容,但依赖在磁盘上的组织方式完全不同,由此带来了安装速度、磁盘占用、幽灵依赖等方面的差异。
核心差异:node_modules 结构
- npm:采用「扁平化」安装。所有依赖尽量提升(hoist)到顶层的
node_modules下,同一个包如果版本范围兼容就复用一份。好处是兼容性老代码,坏处是产生 幽灵依赖。 - pnpm:内容寻址 + 硬链接。真实文件只存在全局仓库
~/.pnpm-store,项目里的node_modules/.pnpm保存实际版本,顶层node_modules里只有符号链接指向它们。项目依赖树是严格的:只有 package.json 里声明过的包才能被 import。
# npm(扁平)
node_modules/
lodash/ ← 真实文件,所有包共用
a/ ← 可以 require('lodash'),即使没声明
# pnpm(符号链接 + 全局仓库)
node_modules/
lodash -> .pnpm/lodash@4.17.21/node_modules/lodash
.pnpm/
lodash@4.17.21/node_modules/lodash/ ← 硬链接到全局 store
对比总表
| 维度 | npm | pnpm |
|---|---|---|
| 磁盘占用 | 每个项目各存一份,重复占用大 | 全局仓库 + 硬链接,多项目共享同一份文件 |
| 安装速度 | 较慢(大量小文件复制) | 通常更快(链接代替复制,缓存命中高) |
| node_modules 结构 | 扁平提升 | 严格嵌套 + 符号链接 |
| 幽灵依赖 | 常见 | 基本不存在 |
| 依赖版本冲突 | 可能出现「版本串味」 | 每个版本独立目录,隔离清晰 |
| Monorepo 支持 | 需 workspaces | 内置 workspaces,且对多包依赖处理更好 |
| 生态兼容性 | 最广,老项目首选 | 少数包因不识别符号链接(如需要物理路径的)会报错 |
| lock 文件 | package-lock.json | pnpm-lock.yaml |
| 命令兼容 | — | 基本同 npm,另有 pnpm dlx(≈ npx) |
幽灵依赖(Phantom Dependency)
指代码里 require 了一个没有写在 package.json 里的包,只因它被别的依赖提升到了顶层而“恰好”能用。
- npm 下这类代码能跑,换环境或升级依赖后就崩。
- pnpm 下直接报
Cannot find module,问题在开发期就暴露。 - 需要兼容历史代码时,可以在
.npmrc里设置shamefully-hoist=true关闭严格隔离。
什么时候选哪个
npm 更适合
- 老项目、CI 环境只预装了 npm
- 依赖里有强依赖物理路径、不兼容符号链接的包
- 团队不想引入额外约定
pnpm 更适合
- 多个项目 / Monorepo,想省磁盘、省 CI 时间
- 新项目,希望依赖声明严格可靠
- 想避免「本地能跑、服务器跑不了」
常用命令对照
| 操作 | npm | pnpm |
|---|---|---|
| 安装全部依赖 | npm install | pnpm install |
| 添加依赖 | npm i lodash | pnpm add lodash |
| 添加开发依赖 | npm i -D vite | pnpm add -D vite |
| 全局安装 | npm i -g xxx | pnpm add -g xxx |
| 运行脚本 | npm run dev | pnpm dev(也可 pnpm run dev) |
| 执行远程包 | npx create-vite | pnpm dlx create-vite |
| 查看依赖树 | npm ls | pnpm list |
| 清理缓存 | npm cache clean --force | pnpm store prune |
迁移注意
- 先删除旧的
node_modules与package-lock.json。 pnpm import可把package-lock.json转成pnpm-lock.yaml。pnpm install,观察是否有包因符号链接报错;必要时调整.npmrc。- 统一团队与 CI 的包管理器,避免 lock 文件互相覆盖。