====== 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` | ===== 迁移注意 ===== 1. 先删除旧的 `node_modules` 与 `package-lock.json`。 2. `pnpm import` 可把 `package-lock.json` 转成 `pnpm-lock.yaml`。 3. `pnpm install`,观察是否有包因符号链接报错;必要时调整 `.npmrc`。 4. 统一团队与 CI 的包管理器,避免 lock 文件互相覆盖。 ```mdk height=520 color=#059669 # 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 的包管理器 ```