pnpm 使用教程

现代 JavaScript 项目的首选包管理器pnpmperformant npm是一个快速、节省磁盘空间的包管理器它通过全局存储和硬链接机制解决了 npm 传统的依赖重复和“幽灵依赖”问题。本教程将带你从零开始掌握 pnpm 的核心用法并说明它为何成为越来越多开发者的首选。一、pnpm 的核心优势在开始之前先了解 pnpm 相比 npm/yarn 的几个关键优势极快的安装速度利用全局缓存和硬链接已安装过的包无需重新下载直接链接即可。节省磁盘空间所有包在全局只存一份多个项目共享避免重复存储。严格的依赖隔离强制只能使用 package.json 中声明的依赖杜绝“幽灵依赖”。原生 Monorepo 支持内置工作区workspace功能管理多包项目非常方便。兼容性强命令与 npm 高度相似学习成本低。二、安装 pnpm1. 通过 npm 安装npminstall-gpnpm2. 通过独立脚本安装推荐Linux / macOS / WSLcurl-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 initpnpm init安装所有依赖npm installpnpm install添加依赖npm install pkgpnpm add pkg添加开发依赖npm install -D pkgpnpm add -D pkg全局安装npm install -g pkgpnpm add -g pkg移除依赖npm remove pkgpnpm remove pkg更新依赖npm updatepnpm update运行脚本npm run scriptpnpm run script 或 pnpm script四、依赖管理原理1. 全局存储与硬链接pnpm 将所有下载的包存放在一个全局存储目录默认 ~/.pnpm-store。当项目需要某个包时pnpm 会创建硬链接指向全局存储中的文件而不是复制一份。这样即使有 100 个项目使用相同的包磁盘上也只保存一份物理文件。2. node_modules 结构与 npm 的扁平化不同pnpm 使用 符号链接 构建严格的依赖树。例如项目目录下的 node_modules 结构如下node_modules/ .pnpm/# 虚拟存储目录包含所有包的真实文件express -.pnpm/express4.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 中引入 utilsbashcd apps/webpnpm add utilsworkspace:* --filter web–filter 用于指定操作的目标工作区包workspace:* 表示使用本地工作区版本。3. 常用工作区命令在根目录安装所有依赖pnpm install会自动处理工作区依赖在指定包中运行脚本pnpm --filter web run dev发布所有包pnpm -r publish-r 递归执行六、配置文件 .npmrcpnpm 使用与 npm 相同的 .npmrc 配置文件但新增了一些专属选项。常见配置示例# 设置全局存储路径store-dir/path/to/custom/store# 设置 node_modules 链接方式默认 isolated可选 hoistednode-linkerisolated# 允许使用锁文件默认 pnpm-lock.yamllockfiletrue# 设置镜像源registryhttps://registry.npmmirror.com你可以将 .npmrc 放在项目根目录或用户目录下。七、从 npm 迁移到 pnpm1. 迁移步骤删除 node_modules 和 package-lock.jsonrm-rfnode_modules package-lock.json使用 pnpm 安装pnpminstall检查项目是否正常运行。2. 处理可能的兼容问题极少数情况下某些库或工具依赖于 npm 的扁平化结构例如硬编码了 …/…/ 路径。此时可以通过配置 .npmrc 中的 node-linkerhoisted 让 pnpm 模拟 npm 的扁平化结构。但通常现代框架和工具都已完全支持 pnpm。3. 保持 lock 文件一致性如果团队同时使用 npm 和 pnpm可能会出现 lock 文件冲突。建议团队统一使用 pnpm并在 CI 中检查 pnpm-lock.yaml 的更新。八、常见问题与技巧Q1: pnpm 如何清理缓存pnpmstore prune# 删除全局存储中未被任何项目引用的包Q2: 如何查看全局存储路径pnpmstore pathQ3: 如何强制重新安装某个包pnpmaddpkg--forceQ4: pnpm 支持 npm 脚本的钩子吗支持。例如preinstall、postinstall等与 npm 完全一致。Q5: 如何在 CI 环境中加速安装可以利用缓存。例如在 GitHub Actions 中-uses:actions/setup-nodev3with:node-version:18-uses:pnpm/action-setupv2with: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