两者都是 Node.js 的包管理器,命令高度兼容,但依赖在磁盘上的组织方式完全不同,由此带来了安装速度、磁盘占用、幽灵依赖等方面的差异。
node_modules 下,同一个包如果版本范围兼容就复用一份。好处是兼容性老代码,坏处是产生 幽灵依赖。~/.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) |
指代码里 require 了一个没有写在 package.json 里的包,只因它被别的依赖提升到了顶层而“恰好”能用。
Cannot find module,问题在开发期就暴露。.npmrc 里设置 shamefully-hoist=true 关闭严格隔离。| 操作 | 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。# npm vs pnpm ## 本质区别 ### npm:扁平化 node_modules ### pnpm:全局 store + 硬链接 + 符号链接 ### pnpm 依赖树严格,无法访问未声明的包 ## pnpm 优势 ### 磁盘占用小(多项目共享一份) ### 安装更快(链接代替复制) ### 无幽灵依赖 ### 多版本隔离清晰 ### 原生 Monorepo workspaces ## npm 优势 ### 生态兼容性最广 ### 老项目、老 CI 零改造成本 ### 无符号链接兼容问题 ## 幽灵依赖 ### 引入未在 package.json 声明的包 ### npm 下能跑,升级即崩 ### pnpm 下直接报错,开发期暴露 ### 兼容旧代码:shamefully-hoist=true ## lock 文件 ### npm:package-lock.json ### pnpm:pnpm-lock.yaml ## 命令对照 ### install / add / add -D ### pnpm dev 可直接跑脚本 ### npx ↔ pnpm dlx ### cache clean ↔ store prune ## 迁移步骤 ### 删 node_modules 与 package-lock.json ### pnpm import 转换 lock ### pnpm install 验证兼容性 ### 统一团队与 CI 的包管理器