目录

npm 和 pnpm 的区别

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

核心差异:node_modules 结构

# 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 更适合

常用命令对照

操作 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 的包管理器