什么是pnpm？使用指南

在前端开发领域，包管理器是我们每天都会打交道的工具。从最早的 npm，到后来的 yarn，再到如今被誉为“最先进”的 **pnpm**，工具的演进始终围绕着三个核心指标：**速度、空间效率、依赖安全性**。

本文将带你了解pnpm，并教你如何使用。

## 什么是 pnpm？

**pnpm** (Performant npm) 是一款极其快速、节省磁盘空间的软件包管理器。

### 核心优点

- **极速（Performance）：** pnpm 比 npm 和 yarn 快得多（通常快 2 倍以上）。因为它采用了独特的安装机制，避免了大量文件的重复拷贝。
- **节省空间（Efficiency）：** 这是 pnpm 的杀手锏。它使用**内容寻址存储（Content-addressable storage）**。如果你有 10 个项目都用到了同一个版本的 `lodash`，在磁盘上它只会被存储一份。
- **完美解决“幽灵依赖”（Safety）：** 传统的 npm/yarn 会将依赖“打平”（flat），导致你可以在代码里访问到你并没有在 `package.json` 中声明的包。pnpm 使用**符号链接（Symlinks）**构建了一个严格的依赖树，只有你声明过的包才能被访问。

## pnpm 的“正确姿势”

### 安装 pnpm

如果你已经安装了 Node.js，推荐直接通过核心管理工具安装：

```Bash
corepack enable
corepack prepare pnpm@latest --activate
```

或者使用 npm 全局安装：`npm install -g pnpm`

### 常用命令对照表

| **操作**     | **npm 命令**          | **pnpm 命令**                   |
| ------------ | --------------------- | ------------------------------- |
| 安装依赖     | `npm install`         | `pnpm install` (或 `pnpm i`)    |
| 添加包       | `npm install <pkg>`   | `pnpm add <pkg>`                |
| 添加开发依赖 | `npm i <pkg> -D`      | `pnpm add <pkg> -D`             |
| 移除包       | `npm uninstall <pkg>` | `pnpm remove <pkg>`             |
| 运行脚本     | `npm run <script>`    | `pnpm <script>` (无需 run 字样) |
| 全局安装     | `npm install -g`      | `pnpm add -g`                   |

### 管理 Node 版本

pnpm 内置了版本管理功能，你甚至可以不用安装 nvm：

- 安装指定版本：`pnpm env use --global 20`



## 进阶

### 设置存储路径（Store Path）

pnpm 的核心逻辑是把所有包存在一个全局的 `store` 里，然后通过硬链接映射到各个项目的 `node_modules`。

默认情况下，store 会在当前盘符的根目录下。如果你想自定义存储位置（例如担心 C 盘空间）：

```Bash
# 查看当前 store 路径
pnpm store path

# 设置自定义路径
pnpm config set store-dir D:\.pnpm-store
```

### Monorepo 最佳实践

pnpm 是目前处理 **Monorepo**（多包管理工程）的最佳选择。你只需要在根目录创建一个 `pnpm-workspace.yaml` 文件：

```yaml
packages:
  - 'packages/*'
  - 'apps/*'
```

然后你可以跨项目安装依赖：`pnpm add lodash --filter @my-app/web`。

### 与 npm/yarn 的区别

- **npm/yarn (v1):** 采用扁平化结构，容易产生依赖冲突，且磁盘占用大。
- **yarn (v2/v3) Berry:** 引入了 PnP 模式，虽然快但兼容性挑战较大。
- **pnpm:** 找到了平衡点。它既保持了 `node_modules` 的物理结构（通过软硬链接），保证了极高的兼容性，又实现了极致的性能。

## 老项目迁移到pnpm

在你的项目根目录下执行以下操作：

1. **安装 pnpm**（如果还没安装）：

   ```Bash
   npm install -g pnpm
   ```

2. **生成 pnpm 锁文件**： 执行以下命令，它会自动读取你现有的 `package-lock.json` 或 `yarn.lock` 并在不下载包的情况下生成 `pnpm-lock.yaml`。

   ```Bash
   pnpm import
   ```

3. **删除旧文件**： 为了保持项目整洁，删除旧的 `node_modules` 和旧的 lock 文件。

   ```Bash
   # Windows 用户可以使用 del 指令或手动删除
   rm -rf node_modules package-lock.json yarn.lock
   ```

4. **重新安装依赖**： 使用 pnpm 完成最后的一步：

   ```Bash
   pnpm install
   ```