代码术语:npm和pnpm的区别

npm 和 pnpm 的区别

两者都是 Node.js 的包管理器,命令高度兼容,但依赖在磁盘上的组织方式完全不同,由此带来了安装速度、磁盘占用、幽灵依赖等方面的差异。

  • 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)

指代码里 require 了一个没有写在 package.json 里的包,只因它被别的依赖提升到了顶层而“恰好”能用。

  • npm 下这类代码能跑,换环境或升级依赖后就崩。
  • pnpm 下直接报 Cannot find module,问题在开发期就暴露。
  • 需要兼容历史代码时,可以在 .npmrc 里设置 shamefully-hoist=true 关闭严格隔离。
  • 老项目、CI 环境只预装了 npm
  • 依赖里有强依赖物理路径、不兼容符号链接的包
  • 团队不想引入额外约定
  • 多个项目 / 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
  1. 先删除旧的 node_modules 与 package-lock.json。
  2. pnpm import 可把 package-lock.json 转成 pnpm-lock.yaml。
  3. pnpm install,观察是否有包因符号链接报错;必要时调整 .npmrc。
  4. 统一团队与 CI 的包管理器,避免 lock 文件互相覆盖。
# 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 的包管理器

该主题尚不存在

您访问的页面并不存在。如果允许,您可以使用创建该页面按钮来创建它。

  • 代码术语/npm和pnpm的区别.txt
  • 最后更改: 2026/11/04 10:48
  • 由 张叶安