pnpm 全称 "Performant npm"，是一个高性能、节省磁盘空间的 Node.js 包管理器。它通过独特的依赖管理方式，解决了 npm 和 Yarn 传统方案中的诸多痛点，被誉为“最先进的包管理工具”。

一、核心概念与原理

pnpm 的核心创新在于它重新定义了 node_modules 的结构，并充分利用了操作系统的文件系统特性。

1. 传统 npm 的问题（pnpm 的动机）

在理解 pnpm 之前，有必要先了解它试图解决的问题：

npm v2 的嵌套地狱：每个包都有自己的 node_modules，导致目录嵌套极深（尤其在 Windows 上引发路径过长问题），且相同依赖会被多次复制，造成磁盘空间极大浪费。
npm v3+ / Yarn 的扁平化问题：为了解决嵌套过深，npm v3 引入了扁平化提升（hoist），将所有依赖平铺在顶层 node_modules。这带来了两个新问题：

- 幽灵依赖：由于依赖被拍平，项目可以引用到 package.json 中未声明的包。这可能导致代码在不同环境下出现意外错误。 - 分身（Doppelgangers）：当项目需要同一个包的不同版本时，除了被提升到顶层的一个版本外，其他版本仍会被重复安装到各自的 node_modules 中，造成了重复和浪费。

2. pnpm 的解决方案：内容寻址存储 + 符号链接

pnpm 巧妙地结合了 npm v2 的嵌套结构和 npm v3 的平铺优势，引入了一套全新的机制。

结构解析

pnpm 安装依赖后，node_modules 的结构与 npm/Yarn 完全不同：

链接过程

pnpm 的依赖管理分为三个层次：

全局存储：所有下载过的包都会保存在一个全局的、基于内容寻址的 .pnpm-store 文件夹中。同一个包在全球范围内仅存储一份。
项目虚拟存储：在项目 node_modules/.pnpm 下，pnpm 通过硬链接关联到全局存储中的文件。硬链接的多个副本指向磁盘上的同一份数据，因此不占用额外空间。
项目引用：最后，pnpm 在项目 node_modules 根目录下创建符号链接，将这些链接指向 .pnpm 文件夹。

简单来说： 项目根目录/nodemodules/依赖包 (符号链接) -> .pnpm/依赖包@版本/nodemodules/依赖包 (硬链接) -> 全局磁盘Store (真实文件)。

通过这种方式，pnpm 既避免了重复存储节省了磁盘空间，又通过严格的链接层级杜绝了幽灵依赖，同时保持了极快的安装速度。

二、核心优势

三、常用命令与 CLI

pnpm 的命令与 npm 高度相似，上手成本极低，但有自己特有的优化。

四、安装与配置

1. 安装方式

最推荐的方式是通过 Corepack（Node.js 16.13+ 内置），它可以确保团队成员使用一致的工具链版本：

corepack enable
corepack prepare pnpm@latest --activate

你也可以通过 npm 全局安装：

npm install -g pnpm

在 macOS 或 Linux 系统上，也可以直接运行安装脚本：

curl -fsSL https://get.pnpm.io/install.sh | sh -

或在 Windows PowerShell 中执行：

iwr https://get.pnpm.io/install.ps1 -useb | iex

2. 常见配置

国内镜像加速：为了提高国内用户的下载速度，可配置淘宝镜像：

pnpm config set registry https://registry.npmmirror.com

兼容传统项目：一些老旧项目（如 Vue2 + Webpack4）可能无法兼容 pnpm 默认的严格 nodemodules 结构。此时可以通过在项目根目录创建 .npmrc 文件，设置 node-linker=hoisted 来让 pnpm 生成类似 npm 的扁平化 nodemodules 结构，从而确保项目正常运行。

五、Monorepo 工作区实践

pnpm 通过 pnpm-workspace.yaml 文件来管理 Monorepo。这在多个项目共享代码或依赖时非常有用。

packages:
      # 所有在 packages/ 目录下的包
      - 'packages/*'
      # 所有在 apps/ 目录下的应用
      - 'apps/*'

{
      "dependencies": {
        "@my-project/shared": "workspace:*"
      }
    }

这里的 workspace:* 协议告诉 pnpm 直接链接本地的包，而不是从 npm 仓库下载。

六、高阶特性：注入依赖

在 Monorepo 中，如果被引用的本地包有复杂的对等依赖关系，普通的 workspace:* 符号链接可能无法满足需求。pnpm 提供了 注入依赖 功能。

通过在 package.json 中配置 dependenciesMeta，可以将本地包像普通的 npm 包一样复制到引用者的 node_modules 中，而不是进行符号链接：

{
  "dependenciesMeta": {
    "my-local-lib": {
      "injected": true
    }
  }
}

这能确保对等依赖被正确解析，但需要借助 pnpm-sync 等工具来处理更新同步问题。

七、与 npm/Yarn 的选择建议

新项目 / 大型项目：直接选用 pnpm。尤其是在需要高效的 Monorepo 支持时，它是当前最佳选择之一。
生态兼容性：虽然 pnpm 已经非常成熟，但极少数底层依赖或者老旧的构建工具可能依赖于扁平化的 node_modules 结构。如果遇到此类问题，可以通过之前提到的 node-linker=hoisted 配置解决，也可以暂时使用 npm 或 Yarn。

pnpm 详解：高性能的 Node.js 包管理器