pnpm 使用教程
现代 JavaScript 项目的首选包管理器
pnpm（performant npm）是一个快速、节省磁盘空间的包管理器，它通过全局存储和硬链接机制，解决了 npm 传统的依赖重复和“幽灵依赖”问题。本教程将带你从零开始掌握 pnpm 的核心用法，并说明它为何成为越来越多开发者的首选。
一、pnpm 的核心优势
在开始之前，先了解 pnpm 相比 npm/yarn 的几个关键优势：
极快的安装速度：利用全局缓存和硬链接，已安装过的包无需重新下载，直接链接即可。
节省磁盘空间：所有包在全局只存一份，多个项目共享，避免重复存储。
严格的依赖隔离：强制只能使用 package.json 中声明的依赖，杜绝“幽灵依赖”。
原生 Monorepo 支持：内置工作区（workspace）功能，管理多包项目非常方便。
兼容性强：命令与 npm 高度相似，学习成本低。
二、安装 pnpm
1. 通过 npm 安装
npminstall-gpnpm2. 通过独立脚本安装（推荐）
Linux / macOS / WSL
curl-fsSLhttps://get.pnpm.io/install.sh|sh-Windows (PowerShell)
iwr https://get.pnpm.io/install.ps1-useb|iex安装完成后，重新打开终端，验证安装：
pnpm--version三、基础命令使用
pnpm 的命令与 npm 几乎一致，只需将 npm 替换为 pnpm 即可。
| 操作 | npm 命令 | pnpm 命令 |
|---|---|---|
| 初始化项目 | npm init | pnpm init |
| 安装所有依赖 | npm install | pnpm install |
| 添加依赖 | npm install <pkg> | pnpm add <pkg> |
| 添加开发依赖 | npm install -D <pkg> | pnpm add -D <pkg> |
| 全局安装 | npm install -g <pkg> | pnpm add -g <pkg> |
| 移除依赖 | npm remove <pkg> | pnpm remove <pkg> |
| 更新依赖 | npm update | pnpm update |
| 运行脚本 | npm run <script> | pnpm run <script> 或 pnpm <script> |
四、依赖管理原理
1. 全局存储与硬链接
pnpm 将所有下载的包存放在一个全局存储目录（默认 ~/.pnpm-store）。当项目需要某个包时，pnpm 会创建硬链接指向全局存储中的文件，而不是复制一份。这样，即使有 100 个项目使用相同的包，磁盘上也只保存一份物理文件。
2. node_modules 结构
与 npm 的扁平化不同，pnpm 使用 符号链接 构建严格的依赖树。例如，项目目录下的 node_modules 结构如下：
node_modules/ .pnpm/# 虚拟存储目录，包含所有包的真实文件express ->.pnpm/express@4.18.2/node_modules/express# 直接依赖的符号链接只有 package.json 中声明的依赖才会被直接链接到 node_modules 顶层，而间接依赖被隐藏在 .pnpm 目录中。这确保了代码无法意外引入未声明的包。
3. 幽灵依赖的解决
在 npm 中，由于依赖被扁平化提升，项目可能引用到并未在 package.json 中声明的包（例如 lodash 是某个依赖的子依赖），这在团队协作或部署时可能导致“缺少模块”的错误。pnpm 彻底消除了这种现象。
五、工作区（Workspace）— Monorepo 支持
pnpm 内置了工作区功能，非常适合管理 Monorepo（多包仓库）。
1. 创建工作区
在项目根目录创建 pnpm-workspace.yaml 文件：
packages:-"packages/*"-"apps/*"2. 添加项目间依赖
假设 packages/utils 和 apps/web 是两个子包，在 apps/web 中引入 utils：
bash
cd apps/web
pnpm add utils@workspace:* --filter web
–filter 用于指定操作的目标工作区包，workspace:* 表示使用本地工作区版本。
3. 常用工作区命令
在根目录安装所有依赖：pnpm install（会自动处理工作区依赖）
在指定包中运行脚本：pnpm --filter web run dev
发布所有包：pnpm -r publish（-r 递归执行）
六、配置文件 .npmrc
pnpm 使用与 npm 相同的 .npmrc 配置文件，但新增了一些专属选项。常见配置示例：
# 设置全局存储路径store-dir=/path/to/custom/store# 设置 node_modules 链接方式（默认 isolated，可选 hoisted）node-linker=isolated# 允许使用锁文件（默认 pnpm-lock.yaml）lockfile=true# 设置镜像源registry=https://registry.npmmirror.com你可以将 .npmrc 放在项目根目录或用户目录下。
七、从 npm 迁移到 pnpm
1. 迁移步骤
删除 node_modules 和 package-lock.json：
rm-rfnode_modules package-lock.json使用 pnpm 安装：
pnpminstall检查项目是否正常运行。
2. 处理可能的兼容问题
极少数情况下，某些库或工具依赖于 npm 的扁平化结构（例如硬编码了 …/…/ 路径）。此时可以通过配置 .npmrc 中的 node-linker=hoisted 让 pnpm 模拟 npm 的扁平化结构。但通常现代框架和工具都已完全支持 pnpm。
3. 保持 lock 文件一致性
如果团队同时使用 npm 和 pnpm，可能会出现 lock 文件冲突。建议团队统一使用 pnpm，并在 CI 中检查 pnpm-lock.yaml 的更新。
八、常见问题与技巧
Q1: pnpm 如何清理缓存？
pnpmstore prune# 删除全局存储中未被任何项目引用的包Q2: 如何查看全局存储路径？
pnpmstore pathQ3: 如何强制重新安装某个包？
pnpmadd<pkg>--forceQ4: pnpm 支持 npm 脚本的钩子吗？
支持。例如preinstall、postinstall等，与 npm 完全一致。
Q5: 如何在 CI 环境中加速安装？
可以利用缓存。例如在 GitHub Actions 中：
-uses:actions/setup-node@v3with:node-version:18-uses:pnpm/action-setup@v2with:version:8-run:pnpm install--frozen-lockfile九、总结
pnpm 通过创新的依赖管理机制，为 JavaScript 开发者带来了更快的安装速度、更小的磁盘占用和更严格的依赖安全。无论你是个人开发者还是团队协作，pnpm 都是一个值得投入的现代工具。
推荐使用场景：
新项目：直接使用 pnpm 作为默认包管理器。
大型 Monorepo：借助 pnpm workspace 高效管理。
对磁盘空间敏感或需要快速 CI 的环境。
快速上手：
# 安装curl-fsSLhttps://get.pnpm.io/install.sh|sh-# 使用pnpminitpnpmaddlodashpnpmrun start