服务端5月29日 23:47
pnpm 在 CI/CD 中如何加速安装和构建？pnpm 在 CI/CD 里提速，核心是三件事：固定依赖、缓存 store、只构建必要包。`pnpm install --frozen-lockfile` 保证流水线不重新解析依赖；缓存 pnpm store 可以避免每次从网络下载；Monorepo 里用 `--filter` 只跑受影响的包，比全量构建更省时间。
## 追问
### 为什么优先缓存 pnpm store，而不是只缓存 node_modules？
pnpm 的依赖真实内容放在 store，项目里的 `node_modules` 主要是链接。缓存 store 命中率更稳定，也更适合不同 job 复用。`node_modules` 可以缓存，但跨系统、跨 Node 版本时更容易出问题。
### GitHub Actions 里怎么配？
用 `actions/setup-node` 的 `cache: pnpm`，再配合 `pnpm/action-setup`。如果要手动缓存，key 必须包含 `pnpm-lock.yaml` 的 hash，避免依赖变了还复用旧缓存。
### Docker 构建怎么提速？
先复制 `package.json` 和 `pnpm-lock.yaml`，安装依赖后再复制源码。这样源码改动不会让依赖层失效。BuildKit 环境还可以挂载 pnpm store 缓存。
### Monorepo 怎么避免全量构建？
用 `pnpm -r --filter "...[origin/main]" build` 只构建受影响包；需要并行时加 `--workspace-concurrency`，不要盲目开满 CPU，容易把 CI 机器打爆。
## 写段代码
```yaml
- uses: pnpm/action-setup@v4
with:
version: 9
- uses: actions/setup-node@v4
with:
node-version: 20
cache: pnpm
- run: pnpm install --frozen-lockfile --prefer-offline
- run: pnpm -r --filter "...[origin/main]" build
```标签
PNPM
pnpm（Performant npm）是一个快速的，节省磁盘空间的包管理工具，用于 JavaScript 和 Node.js 生态系统。它是 npm 和 Yarn 的一个替代品，旨在提供更快、更高效的依赖管理解决方案。pnpm 主要通过使用硬链接和符号链接的方式来存储一个版本的包的单一副本，从而减少磁盘空间的使用和加速安装过程。
服务端5月28日 02:26
pnpm 的 shamefully-hoist 配置是什么？什么时候需要使用？`shamefully-hoist` 是 pnpm 提供的一个配置项，设为 `true` 后会将所有依赖提升到 `node_modules` 根目录，模仿 npm/Yarn 的扁平化结构。
## 核心回答
**是什么：** pnpm 默认使用内容寻址存储 + symlink 的严格依赖结构，每个包只能访问自己 `package.json` 中声明的依赖。`shamefully-hoist=true` 会打破这一限制，把全部包提升到根 `node_modules`，允许访问未声明的依赖（即幽灵依赖）。
**什么时候用：** 只在两种场景下考虑使用——遗留项目迁移时临时启用，或者某些存在缺陷的工具（部分 webpack 插件、IDE 插件等）强制要求扁平化结构时。启用后应尽快迁移到 `public-hoist-pattern` 精细控制。
## 默认结构 vs shamefully-hoist
pnpm 默认的 `node_modules` 结构通过 `.pnpm` 目录和 symlink 实现严格隔离：
```bash
# 默认结构（严格）
node_modules/
├── .pnpm/
│ ├── lodash@4.17.21/
│ │ └── node_modules/
│ │ └── lodash/ # 实际文件
│ └── express@4.18.2/
│ └── node_modules/
│ ├── express/
│ └── debug/ # express 的依赖，对 lodash 不可见
└── lodash -> .pnpm/lodash@4.17.21/node_modules/lodash
# require 行为
const lodash = require('lodash'); # OK - 声明了
const debug = require('debug'); # 报错 - 未声明，访问不到
```
启用 `shamefully-hoist=true` 后：
```bash
# 扁平化结构
node_modules/
├── .pnpm/
├── lodash/
├── debug/ # 被提升上来
├── express/
└── ...
# require 行为
const lodash = require('lodash'); # OK
const debug = require('debug'); # 也能访问了（幽灵依赖）
```
## 配置方式
从 pnpm v8 开始，`shamefully-hoist` 推荐配置在 `pnpm-workspace.yaml` 而非 `.npmrc`（auth 和 registry 之外的设置都应如此）：
```yaml
# pnpm-workspace.yaml
shamefullyHoist: true
```
旧版本仍可在 `.npmrc` 中配置：
```ini
# .npmrc
shamefully-hoist=true
```
也可以通过命令行临时启用：
```bash
pnpm install --shamefully-hoist
```
## 更好的替代方案：public-hoist-pattern
`shamefully-hoist=true` 等价于 `public-hoist-pattern=*`，属于"一刀切"方案。绝大多数情况下，只需要提升特定包就够了：
```ini
# .npmrc 或 pnpm-workspace.yaml
public-hoist-pattern[]=*eslint*
public-hoist-pattern[]=*prettier*
public-hoist-pattern[]=*types*
public-hoist-pattern[]=*webpack*
```
三者的区别：
| 配置 | 作用范围 | 提升位置 | 推荐度 |
|------|----------|----------|--------|
| `shamefully-hoist` | 所有包 | 根 node_modules | 低（过渡用） |
| `public-hoist-pattern` | 匹配的包 | 根 node_modules | 高 |
| `hoist-pattern` | 匹配的包 | .pnpm/node_modules | 中（内部可见） |
`public-hoist-pattern` 提升到根目录，应用代码和工具都能访问；`hoist-pattern` 提升到 `.pnpm/node_modules`，只有其他依赖包能访问，应用代码看不到。
## 实际迁移步骤
从 npm/Yarn 迁移到 pnpm 时，推荐分步走：
**第一步：临时启用 shamefully-hoist**
```yaml
# pnpm-workspace.yaml
shamefullyHoist: true
```
确保项目能正常运行：
```bash
pnpm install
pnpm build
pnpm test
```
**第二步：定位幽灵依赖**
```bash
# depcheck 可以检测未声明但使用的依赖
npx depcheck
# pnpm 自带命令查看依赖树
pnpm ls --depth=0
```
**第三步：逐个修复**
将 depcheck 报出的缺失依赖添加到 `package.json`：
```bash
pnpm add missing-dep
```
**第四步：切换到精细控制**
```yaml
# pnpm-workspace.yaml
shamefullyHoist: false
publicHoistPattern:
- "*eslint*"
- "*prettier*"
- "*types*"
strictPeerDependencies: true
```
再次验证构建和测试通过。
## 不推荐长期使用的原因
**幽灵依赖隐患：** 扁平化后代码可以 require 任何包，即使 `package.json` 没声明。这在 CI/CD 环境或版本升级时容易出问题——某个间接依赖升级或移除，你的代码就直接报错。
**版本冲突风险：** 多个包依赖同一个包的不同版本时，扁平化只能保留一个版本，可能引发运行时错误。pnpm 的严格模式通过独立存储天然解决了这个问题。
**丧失 pnpm 的核心优势：** 内容寻址存储的硬链接机制能节省大量磁盘空间（多项目共享同一份包文件），扁平化后这部分优势被削弱。
## 相关追问
**node-linker 是什么？** pnpm 还提供了 `node-linker` 配置，可以切换 `node_modules` 的整体布局方式：`isolated`（默认，symlink）、`hoisted`（类 npm 扁平化）、`pnp`（Yarn PnP 风格）。设置 `node-linker=hoisted` 是另一种实现扁平化的方式，效果和 `shamefully-hoist=true` 类似但不完全相同——它改变了整个布局策略而非仅做提升。
**pnpm v9 的变化？** pnpm v9 进一步收紧了默认的 `public-hoist-pattern`，默认不再提升 eslint/types 等包。如果升级后构建报错，检查是否需要显式配置 `public-hoist-pattern`。服务端5月28日 02:14
pnpm 如何处理 peer dependencies？与 npm 有什么不同？pnpm 通过隔离的 node_modules 结构和严格的依赖图解析，在安装阶段就检测 peer dependencies 冲突，而 npm 的扁平化结构可能让版本不匹配的 peer 依赖静默通过，直到运行时才暴露问题。
## 核心机制差异
npm 采用扁平化 node_modules，依赖会被提升（hoist），包能访问到不该访问的依赖（幽灵依赖）。peer dependencies 版本不匹配时，npm v7 之前直接忽略，v7+ 会自动安装但可能产生重复实例。
pnpm 使用 `.pnpm` 存储目录 + 符号链接的隔离结构，每个包只能访问自己声明的依赖。peer dependencies 从依赖图更高层级解析——如果宿主项目提供了匹配版本，符号链接指向它；否则安装报错：
```
ERR_PNPM_PEER_DEP_ISSUES Unmet peer dependencies
react-dom@18.0.0 requires react@^18.0.0 but you have react@17.0.0
```
这种严格性确保版本一致性，避免运行时因 React 多实例导致的 hooks 报错等问题。
## 实际处理方式
**1. 匹配版本安装**
```bash
pnpm add react@18 react-dom@18
```
**2. 全局覆盖**
```json
{
"pnpm": {
"overrides": {
"react": "^18.0.0"
}
}
}
```
**3. 自动安装 peer 依赖（.npmrc）**
```ini
auto-install-peers=true
strict-peer-dependencies=false
```
`auto-install-peers=true` 让 pnpm 自动解析并安装缺失的 peer 依赖，但不会解决版本冲突。`strict-peer-dependencies=false` 将冲突从报错降级为警告。
**4. 标记可选 peer 依赖**
```json
{
"peerDependenciesMeta": {
"react-dom": { "optional": true }
}
}
```
## monorepo 中的行为
pnpm workspace 内，子包的 peer dependencies 会从同一 workspace 中其他包的 dependencies 中解析。workspace 依赖（`workspace:*`）的 peer 需求会被自动满足，无需额外配置。
## 对比总结
| 维度 | npm | pnpm |
|------|-----|------|
| 检查时机 | v7+ 安装时检查，v6 及以前延迟到运行时 | 始终在安装时严格检查 |
| 版本冲突 | 可能安装多个实例 | 单一实例，冲突直接报错 |
| node_modules 结构 | 扁平化，存在幽灵依赖 | 隔离存储 + 符号链接 |
| peer 解析来源 | 自行安装或从提升结构中查找 | 从依赖图高层级解析 |
## 追问方向
- pnpm 的 `.pnpm` 目录结构如何保证 peer 依赖只链接到正确版本？
- `auto-install-peers=true` 在大型 monorepo 中可能带来什么问题？
- 为什么 React 生态对 peer dependencies 尤其敏感？服务端5月28日 02:12
什么是 pnpm，它与 npm 和 Yarn 有什么区别？## pnpm 是什么
pnpm（Performant npm）是 Node.js 的包管理工具，核心设计目标是通过**内容寻址存储**解决 npm/Yarn 的磁盘浪费和幽灵依赖问题。
## 存储机制：内容寻址 vs 扁平复制
npm 和 Yarn classic 采用扁平化安装：每个项目的 `node_modules` 都复制一份完整的包文件。10 个项目用 lodash，磁盘上就有 10 份副本。
pnpm 的做法不同——所有包只存一份到全局 store（通常在 `~/.local/share/pnpm/store`），项目中通过**硬链接**指向 store 中的文件：
```bash
# 查看全局 store 路径
pnpm store path
# /home/user/.local/share/pnpm/store/v3
# 查看 store 中已缓存的包
pnpm store status
```
安装同一个包 10 次，磁盘上只有 1 份数据，项目中的 `node_modules` 只是硬链接指针。这就是 pnpm 能节省 70%+ 磁盘空间的原因。
## node_modules 结构：严格隔离 vs 幽灵依赖
npm/Yarn 的扁平化结构会产生**幽灵依赖**——你可以在代码中 `import` 一个没有写在 `package.json` 里的包，因为它被其他依赖提升（hoisting）到了顶层。
```js
// 你的 package.json 只声明了 express
// 但 express 依赖了 body-parser，body-parser 又依赖了 qs
// npm 下这段代码能运行，因为 qs 被提升到了顶层
const qs = require("qs") // 危险：没有在 package.json 中声明
// 一天 express 换了依赖不再安装 qs，你的代码就崩了
```
pnpm 的 `node_modules` 结构是这样的：
```
node_modules/
├── .pnpm/
│ ├── express@4.18.2/
│ │ └── node_modules/
│ │ ├── express/ → 硬链接到 store
│ │ └── body-parser/ → express 的依赖，只 express 能访问
│ └── qs@6.11.0/
│ └── node_modules/
│ └── qs/ → 硬链接到 store
└── express/ → 软链接到 .pnpm/express@4.18.2/node_modules/express
```
每个包只能访问自己声明的依赖，`require("qs")` 如果没写在 `package.json` 里会直接报错。
如果遇到必须用扁平结构的兼容性问题，可以在 `.npmrc` 中设置：
```ini
shamefully-hoist=true
```
但这会失去严格隔离的优势，只作为最后的兜底方案。
## 安装速度对比
冷安装（无缓存）和热安装（有缓存）的实际表现：
| 场景 | npm | Yarn | pnpm |
|------|-----|------|------|
| 冷安装（1500 依赖） | ~48s | ~22s | ~14s |
| 热安装（已有缓存） | ~12s | ~3s | ~3s |
| 更新单个依赖 | ~9s | ~1.2s | ~0.9s |
热安装快的原因：pnpm 检测到 store 中已有该包，直接创建硬链接，不需要网络请求和文件复制。
## monorepo 支持
pnpm 原生支持 workspace，通过 `pnpm-workspace.yaml` 配置：
```yaml
# pnpm-workspace.yaml
packages:
- "apps/*"
- "packages/*"
```
```bash
# 只安装某个 workspace 的依赖
pnpm install --filter @myapp/web
# 在所有 workspace 中执行脚本
pnpm -r run build
# 包间依赖引用
pnpm add @myapp/utils --filter @myapp/web
```
相比 npm workspaces，pnpm 的 `--filter` 语法更灵活，且 workspace 间的依赖也遵循严格隔离，不会意外访问兄弟包的内部模块。
## 迁移到 pnpm
```bash
# 从 npm 迁移：导入 lockfile
pnpm import # 自动读取 package-lock.json 生成 pnpm-lock.yaml
# 或直接安装
rm -rf node_modules package-lock.json
pnpm install
# 从 Yarn 迁移同理，pnpm import 也支持 yarn.lock
```
## 追问
**Q: pnpm 的硬链接在跨文件系统时会失效吗？**
会。硬链接要求源文件和目标在同一个文件系统分区。如果全局 store 和项目不在同一分区（比如 store 在 SSD，项目在机械硬盘），pnpm 会回退到复制文件，磁盘节省效果消失。Docker 容器中挂载卷时也需注意这个问题。
**Q: `.npmrc` 中 `shamefully-hoist=true` 和 `hoist-pattern[]` 怎么选？**
优先用 `hoist-pattern` 做精确控制，只提升特定包到顶层：
```ini
# 只提升 eslint 相关包
hoist-pattern[]=eslint*
hoist-pattern[]=@eslint/*
```
`shamefully-hoist=true` 是全部提升，等于放弃严格隔离，只在遇到无法绕过的兼容性问题时使用。服务端5月28日 02:12
pnpm 常用命令有哪些？与 npm 命令有什么区别？## 核心回答
pnpm 常用命令与 npm 高度相似，关键差异在于：`npm install <pkg>` 对应 `pnpm add <pkg>`；`npx` 对应 `pnpm dlx`；monorepo 用 `pnpm -r`（递归）和 `pnpm --filter`（按包过滤）替代 npm workspaces。但命令相似只是表象，真正的区别在于底层机制——pnpm 使用**内容寻址存储**（content-addressable store）+ **符号链接结构**，解决了 npm 的幽灵依赖和磁盘浪费问题。
**追问：为什么 pnpm 不存在幽灵依赖？**
npm 采用扁平化 node_modules，所有依赖都被提升到顶层，导致代码能 import 未声明的包。pnpm 通过 `.pnpm` 目录存放硬链接，再用 symlink 严格映射到项目 node_modules，只暴露 package.json 中声明的依赖。
**追问：pnpm add 和 npm install 的区别？**
`npm install <pkg>` 既用于安装所有依赖（无参数），也用于添加单个包。pnpm 将这两个职责拆分：`pnpm install` 安装已有依赖，`pnpm add` 添加新包，语义更清晰。
## 安装与依赖管理
```bash
# 安装所有依赖
pnpm install
# 添加依赖（默认 dependencies）
pnpm add lodash
pnpm add lodash@4.17.21
# 添加到不同依赖组
pnpm add lodash -D # devDependencies
pnpm add lodash -O # optionalDependencies
pnpm add lodash --save-peer # peerDependencies
# 全局安装
pnpm add -g typescript
```
## 更新与删除
```bash
# 更新
pnpm update lodash # 更新单个包
pnpm up -L # 更新所有包到最新版
pnpm up -i # 交互式选择更新
# 删除
pnpm remove lodash
pnpm rm lodash express # 删除多个包
pnpm remove -g lodash # 删除全局包
```
## 运行脚本与执行包
```bash
# 运行 package.json 中的脚本
pnpm build # 等同 pnpm run build
pnpm test
# 传递参数
pnpm build -- --watch
# 执行远程包（替代 npx）
pnpm dlx create-vite my-app
```
**追问：pnpm dlx 和 npx 有什么区别？**
`pnpm dlx` 下载包到临时目录执行，不污染全局。`npx` 在 npm 5.2+ 中引入，行为类似但会优先查找本地已安装的包。两者核心场景一致，但 `pnpm dlx` 的临时隔离更彻底。
## Monorepo 命令
pnpm 原生支持 monorepo，通过 `pnpm-workspace.yaml` 声明工作区，配合 `--filter` 实现精准的包范围操作：
```bash
# 在指定包中执行
pnpm --filter @scope/pkg build
pnpm -F @scope/pkg build
# 递归执行（所有包）
pnpm -r build
# 并行执行
pnpm -r --parallel build
# 只执行有变更的包
pnpm -r --filter "...[origin/main]" build
```
**追问：pnpm workspace 和 npm workspaces 的核心差异？**
pnpm workspace 默认严格隔离依赖，通过 `.npmrc` 的 `shamefully-hoist=true` 可切换为扁平模式；npm workspaces 默认扁平提升。pnpm 的 `--filter` 支持正则、依赖图范围等灵活选择，npm 的 `--workspace` 功能相对简单。实际项目中 pnpm workspace 的依赖隔离更可靠，避免子包间隐式依赖。
## Store 管理
pnpm 的核心优势来自全局 store，所有项目共享同一份包存储：
```bash
pnpm store path # 查看 store 路径
pnpm store prune # 清理未引用的包，释放磁盘
pnpm store verify # 验证 store 完整性
```
**追问：pnpm store 的硬链接机制如何节省磁盘？**
所有项目共享一个全局 store（默认 `~/.local/share/pnpm/store`），每个包只存一份。项目 node_modules 中通过硬链接指向 store，不复制文件。10 个项目用同一个版本的 lodash，磁盘只占一份空间。这也是 pnpm 安装速度比 npm 快 2-3 倍的原因——大部分包已在 store 中，只需创建链接。
## 命令速查对比
| 功能 | npm | pnpm | 差异说明 |
|------|-----|------|----------|
| 安装依赖 | `npm install` | `pnpm install` | 语义一致 |
| 添加包 | `npm install <pkg>` | `pnpm add <pkg>` | pnpm 语义更清晰 |
| 删除包 | `npm uninstall <pkg>` | `pnpm remove <pkg>` | 命令名不同 |
| 运行脚本 | `npm run <cmd>` | `pnpm <cmd>` | pnpm 可省略 run |
| 执行远程包 | `npx <cmd>` | `pnpm dlx <cmd>` | dlx 隔离更彻底 |
| 查看依赖 | `npm list` | `pnpm list` | 语义一致 |
| 查看过时包 | `npm outdated` | `pnpm outdated` | 语义一致 |
| 安全审计 | `npm audit` | `pnpm audit` | 语义一致 |
| 全局安装 | `npm install -g` | `pnpm add -g` | add vs install |
| Monorepo | `--workspace` | `--filter` | filter 更灵活 |
## 其他实用命令
```bash
pnpm init # 初始化 package.json
pnpm create vite # 用模板创建项目
pnpm import # 从 npm/yarn 锁文件迁移
pnpm link ../local-pkg # 链接本地包
pnpm why lodash # 查看包被谁依赖
pnpm config list # 查看配置
pnpm config set registry https://registry.npmmirror.com # 设置镜像源
pnpm outdated # 检查过时依赖
pnpm audit # 安全审计
```
服务端5月28日 02:10
pnpm workspace 如何配置和使用？pnpm workspace 是 pnpm 内置的 monorepo 方案，让你在一个仓库里管理多个互相依赖的包。相比 yarn workspaces 和 lerna，它零额外依赖、硬链接共享磁盘空间，配置也最简单。
## 如何声明 workspace
在项目根目录创建 `pnpm-workspace.yaml`：
```yaml
packages:
- 'packages/*'
- 'apps/*'
- 'shared/*'
```
根目录的 `package.json` 必须设置 `"private": true`，防止根包被误发布。
## 典型目录结构
```
my-monorepo/
├── pnpm-workspace.yaml
├── package.json # private: true
├── pnpm-lock.yaml
├── .npmrc # pnpm 专用配置
├── packages/
│ ├── ui/
│ │ ├── package.json # name: @my-org/ui
│ │ └── src/
│ └── utils/
│ ├── package.json # name: @my-org/utils
│ └── src/
└── apps/
├── web/
│ ├── package.json # name: @my-org/web
│ └── src/
└── server/
├── package.json
└── src/
```
## 包间依赖如何引用
使用 `workspace:` 协议引用本地包，开发时直接链接源码，不用发布再安装：
```json
// apps/web/package.json
{
"name": "@my-org/web",
"dependencies": {
"@my-org/ui": "workspace:*",
"@my-org/utils": "workspace:^1.0.0"
}
}
```
`workspace:` 后面的版本写法决定了发布时的替换规则：
| 协议写法 | 开发时行为 | 发布时替换为 |
|---------|-----------|-------------|
| `workspace:*` | 链接最新 | 精确版本如 `1.2.3` |
| `workspace:^` | 链接最新 | `^1.2.3` |
| `workspace:~` | 链接最新 | `~1.2.3` |
| `workspace:^1.0.0` | 链接最新 | `^1.0.0`（保留原范围） |
发布时 `workspace:` 会被自动替换为实际版本号，这是 pnpm 的内置行为，不需要额外配置。
## 常用命令速查
```bash
# 安装所有包的依赖
pnpm install
# 在指定包中执行命令（--filter 或 -F）
pnpm --filter @my-org/ui build
pnpm -F @my-org/ui build
# 递归执行：所有包都跑 build
pnpm -r build
# 只构建有变更的包（基于 git diff）
pnpm -r --filter "...[origin/main]" build
# 给指定包添加依赖
pnpm --filter @my-org/web add @my-org/ui
# 给根目录添加公共开发依赖（-w 标志）
pnpm add -Dw eslint prettier
```
`-r`（递归）和 `--filter` 的区别：`-r` 对所有包执行，`--filter` 按条件筛选。生产环境推荐用 `--filter` 精确控制，避免无关包被意外构建。
## .npmrc 关键配置
pnpm workspace 的许多行为可以通过 `.npmrc` 调整：
```ini
# 未在 workspace 找到的包是否从 registry 下载（默认 true）
link-workspace-packages=true
# 依赖提升策略（避免幽灵依赖）
shamefully-hoist=false
node-linker=hoisted # 需要 hoist 时用这个，不推荐
# 严格对等依赖
strict-peer-dependencies=true
```
`link-workspace-packages=true` 配合 `workspace:*` 使用时，如果本地包版本满足范围就链接本地，否则从 registry 下载。这在逐步迁移 monorepo 时很有用。
## 用 changesets 管理版本和发布
多包版本管理推荐用 changesets，它是 pnpm 官方推荐的方案：
```bash
# 安装
pnpm add -Dw @changesets/cli
pnpm changeset init
# 工作流
pnpm changeset # 交互式记录本次变更（选包、选版本类型、写 changelog）
pnpm changeset version # 根据记录更新 package.json 和 CHANGELOG.md
pnpm -r publish # 发布所有有新版本的包
```
`changeset init` 会生成 `.changeset/` 目录和 `config.json`，其中可以配置 changelog 格式、access（public/restricted）等。
## 常见问题
**Q: 修改了子包代码，依赖它的包要重新安装吗？**
不需要。`workspace:*` 链接的是源码，修改即生效（前提是需要重新 build 的包要重新构建）。
**Q: 发布时 workspace: 协议怎么处理？**
`pnpm publish` 时 `workspace:*` 会自动替换为 `package.json` 中的实际版本号。如果版本号不存在会报错。
**Q: 怎么排查某个包的依赖关系？**
```bash
pnpm list --filter @my-org/web --depth 1 # 查看依赖树
pnpm why @my-org/ui --filter @my-org/web # 查看为什么依赖这个包
```
**Q: 子包之间循环依赖怎么办？**
pnpm 会报错。解决方式是抽取共享逻辑到第三个包，或者通过接口/事件解耦。
## pnpm workspace vs 其他方案
| 特性 | pnpm workspace | Yarn Workspaces | Lerna | Turborepo |
|------|---------------|-----------------|-------|-----------|
| 内置支持 | 是 | 是 | 需安装 | 需安装 |
| 依赖存储 | 硬链接（全局 store） | 符号链接 | 各自安装 | 依赖 pnpm/yarn |
| 磁盘效率 | 最高 | 中等 | 最低 | 取决于底层 |
| 任务缓存 | 否 | 否 | 否 | 是 |
| 配置复杂度 | 低 | 低 | 高 | 中 |
| 版本管理 | 需配合 changesets | 需配合工具 | 内置 | 需配合工具 |
pnpm workspace 本身只解决依赖管理和包链接，任务编排（缓存、并行）交给 Turborepo 或 Nx，版本发布交给 changesets——这是目前最主流的组合方案。
服务端5月28日 02:10
pnpm 的 overrides 和 resolutions 有什么区别？如何使用？## pnpm.overrides：原生覆盖机制
`pnpm.overrides` 是 pnpm 原生的依赖覆盖配置，写在 `package.json` 的 `pnpm` 字段中，也可以写在 `pnpm-workspace.yaml` 里。
```json
// package.json
{
"pnpm": {
"overrides": {
"lodash": "^4.17.21",
"react": "^18.0.0"
}
}
}
```
```yaml
# pnpm-workspace.yaml
overrides:
"lodash": "^4.17.21"
"react": "^18.0.0"
```
### 精确路径覆盖
用 `>` 指定只覆盖某个包的依赖，不影响其他包对同一依赖的使用：
```json
{
"pnpm": {
"overrides": {
"webpack>lodash": "^4.17.21",
"antd>rc-util": "^5.30.0"
}
}
}
```
也可以限定只覆盖特定版本的依赖：
```json
{
"pnpm": {
"overrides": {
"minimist@<1.2.6": "^1.2.6"
}
}
}
```
### 引用项目直接依赖
用 `$` 前缀引用项目自身声明的依赖版本，避免硬编码版本号导致不一致：
```json
{
"dependencies": {
"react": "^18.2.0"
},
"pnpm": {
"overrides": {
"react": "$react"
}
}
}
```
这样所有间接依赖的 react 都会使用项目声明的 `^18.2.0`，而不是单独写一个版本。
### 移除依赖
用 `-` 可以把某个依赖从依赖树中移除：
```json
{
"pnpm": {
"overrides": {
"some-package>unused-dep": "-"
}
}
}
```
这在处理可选依赖或减少安装体积时有用。
### 替换包
将一个包替换为另一个：
```json
{
"pnpm": {
"overrides": {
"node-sass": "sass",
"request": "axios"
}
}
}
```
### 对 peerDependencies 生效
`pnpm.overrides` 会覆盖 peerDependencies 的版本解析。这在统一 React 版本时很常见——某些组件库的 peerDependency 声明了旧版 React，但你希望它们都使用项目中的版本。
## resolutions：Yarn 兼容字段
`resolutions` 是 Yarn 的依赖覆盖字段，pnpm 为了方便从 Yarn 迁移的项目也支持读取它：
```json
{
"resolutions": {
"lodash": "^4.17.21"
}
}
```
### resolutions 的局限
resolutions 在 pnpm 中是兼容层，功能比 `pnpm.overrides` 少很多：
- 不支持 `>` 路径指定，只能全局覆盖
- 不支持 `$` 引用直接依赖
- 不支持 `-` 移除依赖
- 不支持 `@版本号` 限定范围
- 只能写在 `package.json` 中，不支持 `pnpm-workspace.yaml`
## 两者优先级
当 `pnpm.overrides` 和 `resolutions` 同时存在时，`pnpm.overrides` 优先级更高。如果同一条目两边都写了，以 `pnpm.overrides` 为准。
有个已知问题：当 `pnpm-workspace.yaml` 中写了 `overrides` 时，`package.json` 里的 `resolutions` 可能被忽略而不是合并。所以迁移项目时建议把 `resolutions` 手动迁移到 `pnpm.overrides`，而不是两边混用。
## 区别对比
| 特性 | pnpm.overrides | resolutions |
|------|----------------|-------------|
| 路径指定（`>`） | 支持 | 不支持 |
| 版本限定（`@版本`） | 支持 | 不支持 |
| 引用直接依赖（`$`） | 支持 | 不支持 |
| 移除依赖（`-`） | 支持 | 不支持 |
| 配置位置 | package.json 或 pnpm-workspace.yaml | 仅 package.json |
| peerDependencies 覆盖 | 支持 | 支持 |
| 优先级 | 高 | 低 |
| 来源 | pnpm 原生 | Yarn 兼容 |
## 什么时候用哪个
**新项目直接用 `pnpm.overrides`**，不需要考虑 `resolutions`。
**从 Yarn 迁移的项目**，短期可以保留 `resolutions` 让项目先跑起来，但应尽快迁移到 `pnpm.overrides`，否则缺少路径指定和版本限定功能，覆盖精度不够，还可能遇到优先级冲突问题。
## 常见使用场景
### 修复传递依赖的安全漏洞
第三方包依赖了有漏洞的旧版本，该包还没更新，你先手动覆盖：
```json
{
"pnpm": {
"overrides": {
"follow-redirects@<1.15.6": "1.15.6"
}
}
}
```
### 统一 React 版本
monorepo 里不同包可能依赖不同版本的 React，用 `$` 引用统一：
```json
{
"dependencies": {
"react": "^18.2.0",
"react-dom": "^18.2.0"
},
"pnpm": {
"overrides": {
"react": "$react",
"react-dom": "$react-dom"
}
}
}
```
### 只覆盖某个包的依赖
某个包依赖了不兼容的版本，但你不想影响其他包：
```json
{
"pnpm": {
"overrides": {
"antd>rc-util": "^5.30.0"
}
}
}
```
## 验证覆盖效果
修改 overrides 后需要重新安装依赖：
```bash
pnpm install
```
用以下命令确认覆盖是否生效：
```bash
# 查看实际安装的版本
pnpm list react
# 查看某个依赖被谁引入
pnpm why lodash
# 查看完整依赖树
pnpm list --depth=10
```
## 注意事项
全局覆盖要谨慎。把所有包的某个依赖强制升到大版本，可能导致不兼容。优先用路径覆盖（`>`）只影响目标包。
修改 overrides 后记得重新 `pnpm install`，如果锁文件没更新，可以 `pnpm install --force` 强制刷新。服务端5月28日 01:05
pnpm 如何处理依赖版本冲突？## pnpm 如何处理依赖版本冲突？
你刚用 pnpm 装完依赖，终端却飘红一片：ERR_PNPM_PEER_DEP_ISSUE。或者更隐蔽——项目跑起来了，但某个库拿到的不是它期望的依赖版本，线上偶发一个幽灵 bug。
这些都是依赖版本冲突的典型表现。pnpm 的严格隔离机制让冲突更容易暴露，但也给了你更精确的解决手段。这篇文章把 pnpm 处理版本冲突的机制和实战解法一次性讲透。
### 冲突是怎么产生的？
一个项目同时依赖 package-a 和 package-b，它们各自要求不同版本的 lodash：
```json
{
"dependencies": {
"package-a": "^1.0.0",
"package-b": "^2.0.0"
}
}
// package-a 依赖 lodash@^4.17.0
// package-b 依赖 lodash@^3.10.0
```
npm/Yarn 把依赖扁平化到 node_modules 顶层，同一时刻只能存在一个版本的 lodash。谁先安装谁占位，另一个包可能拿到错误版本——这种行为是不确定的，换台机器结果可能就不一样。
### pnpm 的核心机制：隔离存储 + 精确链接
pnpm 不做扁平化。它在 node_modules/.pnpm 下为每个包创建独立目录，各自持有完整的依赖树，再通过符号链接暴露给项目：
```bash
node_modules/
├── .pnpm/
│ ├── lodash@3.10.1/
│ │ └── node_modules/lodash
│ ├── lodash@4.17.21/
│ │ └── node_modules/lodash
│ ├── package-a@1.0.0/
│ │ └── node_modules/
│ │ ├── package-a
│ │ └── lodash -> ../../lodash@4.17.21/node_modules/lodash
│ └── package-b@2.0.0/
│ └── node_modules/
│ ├── package-b
│ └── lodash -> ../../lodash@3.10.1/node_modules/lodash
├── package-a -> .pnpm/package-a@1.0.0/node_modules/package-a
└── package-b -> .pnpm/package-b@2.0.0/node_modules/package-b
```
package-a 引用 lodash 解析到 4.17.21，package-b 解析到 3.10.1，两者互不干扰。同时 .pnpm 下的包通过硬链接指向全局 store（默认 ~/.local/share/pnpm/store），同一版本在磁盘上只存一份。
**这意味着：大多数"版本冲突"在 pnpm 下其实不会造成问题——两个版本可以共存。** 真正需要你介入的是 peer dependency 冲突和需要全局统一版本的场景。
### 如何排查依赖冲突？
遇到问题先定位，再动手：
```bash
# 查看项目依赖树
pnpm list
# 追溯某个包被谁依赖
pnpm why lodash
# 查看完整深度依赖树
pnpm list --depth=10
# 检查重复依赖
pnpm list --depth=Infinity | grep lodash
```
### 强制统一版本：overrides
当多个依赖要求同一包的不同版本，而你希望全局统一时，使用 pnpm.overrides：
```json
{
"pnpm": {
"overrides": {
"lodash": "^4.17.21"
}
}
}
```
只覆盖某个包的子依赖，用 `>` 精准定位：
```json
{
"pnpm": {
"overrides": {
"package-b>lodash": "^4.17.21"
}
}
}
```
用版本范围选择器，只重写匹配的版本：
```json
{
"pnpm": {
"overrides": {
"lodash@^3": "^4.17.21"
}
}
}
```
**overrides 会覆盖整个依赖树的解析结果，用前确认这是你想要的。** 如果只想解决某个子树的冲突，优先用 `>` 语法。
### peer dependencies 冲突处理
peer dependency 冲突是 pnpm 用户最常遇到的报错。比如 package-a 要求 react>=16.8.0，package-b 要求 react>=17.0.0，pnpm 默认报 ERR_PNPM_PEER_DEP_ISSUE。
**方案一：安装满足所有约束的版本（推荐）**
```bash
pnpm add react@18
```
react@18 同时满足 >=16.8.0 和 >=17.0.0，冲突自然消除。这是最干净的解法。
**方案二：overrides 强制统一**
```json
{
"pnpm": {
"overrides": {
"react": "^18.0.0"
}
}
}
```
**方案三：peerDependencyRules 宽松处理**
在 .npmrc 中配置规则，允许特定版本范围或忽略缺失的 peer 依赖：
```ini
# 允许特定版本的 peer 依赖
peerDependencyRules.allowedVersions.react=>=16.8.0 <19
# 忽略缺失的 peer 依赖
peerDependencyRules.ignoreMissing=react-dom
```
或开启自动安装 peer 依赖（pnpm v8+ 默认开启）：
```ini
auto-install-peers=true
```
**选择原则：** 能装统一版本就装，不能装就用 overrides，只有当你明确知道忽略是安全的时候才用 peerDependencyRules。
### 依赖去重
pnpm 的 store 机制天然去重：同一版本在全局只存一份，各项目通过硬链接共享。但如果依赖树中存在多个可兼容版本（如 lodash@4.17.20 和 lodash@4.17.21），用 dedupe 合并：
```bash
pnpm dedupe
```
该命令将依赖树中可兼容的重复包合并为单一版本，减少冗余。合并后建议检查 lockfile 变更，确认无意外升级。
### monorepo 中的版本冲突
在 monorepo 中，不同 workspace 可能依赖同一包的不同版本。除了 overrides，还有三种方案：
**方案一：catalog 协议统一版本（pnpm v9+，推荐）**
```yaml
# pnpm-workspace.yaml
catalogs:
default:
react: ^18.2.0
lodash: ^4.17.21
```
各 workspace 引用时：
```json
{
"dependencies": {
"react": "catalog:",
"lodash": "catalog:"
}
}
```
catalog 是 pnpm 原生的版本管理方案，比 overrides 更语义化，改动也更容易追踪。
**方案二：共享 lockfile**
pnpm monorepo 默认共享一个 pnpm-lock.yaml，确保所有 workspace 的依赖解析一致。如果你手动拆分了 lockfile，建议改回共享模式。
**方案三：hoist-pattern 提升公共依赖**
```ini
# .npmrc — 将匹配的包提升到根 node_modules
hoist-pattern[]=*eslint*
hoist-pattern[]=*prettier*
```
提升会破坏 pnpm 的严格隔离，只在确有需要时使用。
### lockfile 合并冲突处理
多人协作时 pnpm-lock.yaml 可能产生 git 合并冲突：
```bash
# 合并后重新生成 lockfile（pnpm 会自动处理冲突）
pnpm install
# CI 环境严格校验 lockfile 一致性
pnpm install --frozen-lockfile
```
pnpm 内置了冲突修复算法（由 @pnpm/merge-lockfile-changes 维护），合并时以目标分支的版本为准。如果冲突复杂，删掉 lockfile 重新生成也是安全的——只是会丢失确定性，建议合并后让团队成员确认。
### npm/Yarn vs pnpm 冲突处理对比
| 特性 | npm/Yarn | pnpm |
|------|----------|------|
| 多版本共存 | 扁平化冲突，可能拿到错误版本 | 独立存储，精确链接，天然共存 |
| 依赖隔离 | 无隔离，可访问未声明的依赖 | 严格隔离，只能访问声明的依赖 |
| 磁盘占用 | 每个项目独立安装 | 硬链接共享 store，多项目共用 |
| 版本统一 | npm overrides / yarn resolutions | overrides + peerDependencyRules |
| monorepo 版本管理 | workspaces | workspace + catalog 协议 |
| lockfile 冲突 | 手动解决 | 内置合并算法 |
### 实战检查清单
遇到 pnpm 依赖冲突，按这个顺序排查：
1. **`pnpm why <package>`** — 搞清楚谁在要什么版本
2. **判断是否真有冲突** — pnpm 的隔离机制允许不同版本共存，多数场景不需要干预
3. **peer dependency 报错** — 优先安装满足所有约束的版本；不行就用 overrides
4. **需要全局统一版本** — 用 overrides，子树隔离用 `>` 语法
5. **monorepo 版本对齐** — 用 catalog 协议，比 overrides 更可维护
6. **lockfile 合并冲突** — 直接 `pnpm install`，pnpm 会自动处理
7. **CI 环境用 `--frozen-lockfile`** — 确保构建可复现，意外冲突在 CI 阶段暴露服务端5月28日 01:04
pnpm 的 node_modules 结构是怎样的？为什么这样设计？## 核心答案
pnpm 的 node_modules 采用**符号链接 + 硬链接**的混合结构，由三层组成：
1. **node_modules/[package]** — 符号链接层，只暴露直接依赖
2. **node_modules/.pnpm/[package@version]/node_modules/** — 实际包内容，硬链接到全局 store
3. **全局 store（~/.local/share/pnpm-store）** — 内容寻址存储，所有项目共享
这样设计的核心目标是：**消灭幽灵依赖 + 节省磁盘空间 + 保持 Node.js 模块解析兼容**。
## 目录结构详解
```
node_modules/
├── .pnpm/ # 实际内容存放区
│ ├── lodash@4.17.21/
│ │ └── node_modules/
│ │ └── lodash/ # 硬链接 → 全局 store
│ ├── express@4.18.2/
│ │ └── node_modules/
│ │ ├── express/ # 硬链接 → 全局 store
│ │ ├── body-parser/ # express 的依赖（符号链接）
│ │ └── ...
│ └── .modules.yaml # pnpm 元数据
├── lodash → .pnpm/lodash@4.17.21/node_modules/lodash # 符号链接
└── express → .pnpm/express@4.18.2/node_modules/express # 符号链接
```
关键点：你的代码 `require('lodash')` 时，Node.js 解析路径是 `node_modules/lodash`，它是一个符号链接，最终指向 `.pnpm` 中的真实包。而 `.pnpm/lodash@4.17.21/node_modules/lodash/` 下的每个文件，都是硬链接到全局 store 的——不占额外磁盘空间。
## 三层结构各自的职责
### 符号链接层：严格隔离依赖
```
node_modules/
├── lodash → .pnpm/lodash@4.17.21/node_modules/lodash
└── express → .pnpm/express@4.18.2/node_modules/express
```
这一层只包含 `package.json` 中声明的直接依赖。你声明了什么，就只能访问什么。
```javascript
// package.json 只声明了 express
// npm/yarn 下 body-parser 被 hoist 到顶层，可以直接访问
const bodyParser = require('body-parser') // npm: ✅ 能用 pnpm: ❌ 找不到
// 这就是"幽灵依赖"——你用了没声明的东西，某天它被移除就挂了
```
### .pnpm 层：依赖的真实组织
`.pnpm` 目录按 `包名@版本` 平铺，每个包下有自己的 `node_modules`，包含该包的所有依赖（也是符号链接）。这样每个包只能看到自己声明的依赖，形成**严格的依赖图**：
```
.pnpm/
├── express@4.18.2/
│ └── node_modules/
│ ├── express/ # 包自身内容（硬链接）
│ ├── body-parser/ # → .pnpm/body-parser@1.20.2/... （符号链接）
│ └── cookie/ # → .pnpm/cookie@0.5.0/... （符号链接）
└── body-parser@1.20.2/
└── node_modules/
├── body-parser/
└── raw-body/ # → .pnpm/raw-body@2.5.1/...
```
每个包的依赖都在自己的 `node_modules` 下，不会泄漏到外部。
### 全局 store：内容寻址去重
```bash
# 查看 store 位置
pnpm store path
# ~/.local/share/pnpm-store/v3
# 同一台机器上 10 个项目都用 lodash@4.17.21
# 磁盘上只存一份，每个项目的 node_modules 里的文件是硬链接
ls -i node_modules/.pnpm/lodash@4.17.21/node_modules/lodash/lodash.js
# inode 号相同 → 同一份磁盘数据
```
硬链接意味着：同一台机器上，无论多少个项目安装同一个包的同一个版本，磁盘上只有一份数据。删除某个项目不会影响 store 中的文件（硬链接引用计数 > 0 就不删除）。
## 为什么这样设计：解决 npm/yarn 的三大痛点
### 痛点一：幽灵依赖
npm v3 之前用嵌套结构，依赖层级太深（Windows 路径 260 字符限制）。npm v3 改成扁平化，所有依赖被 hoist 到 `node_modules` 根目录：
```
# npm 的扁平结构
node_modules/
├── express/
├── body-parser/ ← 你没声明但能访问
├── raw-body/ ← 你没声明但能访问
├── cookie/ ← 你没声明但能访问
└── ...
```
pnpm 的符号链接层只暴露直接依赖，从结构上杜绝了幽灵依赖。
### 痛点二：磁盘浪费
npm/yarn 每个项目的 `node_modules` 都是完整拷贝。10 个项目用 React，磁盘上存 10 份。
pnpm 通过硬链接共享全局 store，同一版本只存一份。实际效果：
```bash
# 用 npm 安装一个新项目
du -sh node_modules # 200MB
# 用 pnpm 安装（已有其他项目装过相同依赖）
du -sh node_modules # 目录大小仍显示 200MB（ls -l 看大小）
# 但实际磁盘占用接近 0（硬链接不占额外空间）
du -sh ~/.local/share/pnpm-store # store 总大小可能也才 200MB
```
### 痛点三：依赖分身
npm 的扁平化可能导致同一个包的多个版本都被 hoist，只有一个能到顶层，其他版本仍嵌套。项目可能同时依赖一个包的两个版本而不自知，产生难以排查的 bug。
pnpm 的 `.pnpm/name@version` 结构天然支持多版本共存，每个版本独立存储、独立链接。
## peer dependencies 的处理
pnpm 对 peer dependencies 的处理比 npm 更严格。如果包 A 声明了 peer dependency React，但项目中没有安装，pnpm 会报错而非静默跳过：
```bash
ERR_PNPM_PEER_DEP_ISSUES Unmet peer dependencies
.
└─┬ foo@1.0.0
└── ✕ missing peer react@>=16.0.0
```
在 `.pnpm` 结构中，peer dependencies 会被正确地提升到依赖它的包可见的层级，而不是像 npm 那样依赖 hoisting 的不确定性。
## 追问：硬链接和符号链接的区别是什么？
**硬链接**：指向文件的 inode，和原文件共享同一份数据块。删除原文件不影响硬链接，反之亦然。pnpm 用它连接 store 和各项目的 node_modules，实现零拷贝共享。
**符号链接（软链接）**：指向文件路径，类似快捷方式。pnpm 用它构建依赖关系图：`node_modules/lodash → .pnpm/lodash@4.17.21/node_modules/lodash`，让 Node.js 的模块解析逻辑正常工作。
两者配合：符号链接解决依赖可见性，硬链接解决磁盘空间。服务端5月28日 01:02
pnpm 的性能优势体现在哪些方面？与 npm/Yarn 对比如何？pnpm 的性能优势集中在三个层面：安装速度、磁盘占用和依赖安全性。下面逐项拆解，并与 npm、Yarn 做横向对比。
## 安装速度：硬链接让缓存安装接近即时
pnpm 在有缓存时的安装速度远超 npm 和 Yarn，核心原因是硬链接机制——同一台机器上只要某个包的版本曾经下载过，后续项目安装时直接从全局 store 创建硬链接，无需重复拷贝文件。
| 场景 | npm | Yarn Berry (PnP) | pnpm |
|------|-----|------------------|------|
| 冷安装（无缓存） | 45-55s | 30-40s | 25-35s |
| 热安装（有缓存） | 18-25s | 10-15s | 2-4s |
| 删 node_modules 重装 | 40-50s | 25-35s | 3-5s |
数据来源：基于 2026 年社区基准测试（Monorepo 场景，~1500 依赖）。冷安装差距主要来自 pnpm 的并行下载策略；热安装差距则完全由硬链接驱动——pnpm 的热安装本质上是创建文件链接，而非文件拷贝。
## 磁盘空间：内容寻址存储节省 70% 以上
npm 和 Yarn 的 node_modules 采用扁平化拷贝：每个项目独立存储所有依赖文件。10 个使用相同技术栈的项目，磁盘占用约为 500MB x 10 = 5GB。
pnpm 使用全局内容寻址存储（content-addressable store）：相同内容的文件只存一份，各项目通过硬链接引用。
| 项目数量 | npm 总占用 | pnpm 总占用 | 节省比例 |
|---------|-----------|------------|--------|
| 1 个 | ~500MB | ~500MB | 0% |
| 5 个 | ~2.5GB | ~550MB | 78% |
| 10 个 | ~5GB | ~600MB | 88% |
项目越多，节省越显著。这对 CI 环境和磁盘受限的开发机尤其重要。
## 依赖安全性：严格模式杜绝幻影依赖
这常常被忽略，但却是 pnpm 架构上最重要的区别。
npm 和 Yarn 采用扁平化 hoisting——所有依赖（包括间接依赖）都被提升到 node_modules 根目录。这意味着你可以在代码中 `require` 一个未在 package.json 中声明的包，只要它恰好被其他依赖安装了。这就是幻影依赖（phantom dependency）。
pnpm 的 node_modules 采用嵌套软链接结构：
```
node_modules/
.pnpm/
lodash@4.17.21/
node_modules/
lodash -> 硬链接到全局 store
lodash -> .pnpm/lodash@4.17.21/node_modules/lodash
```
你只能访问 package.json 中显式声明的包。间接依赖被严格隔离在 `.pnpm` 目录内，不会泄露到你的代码中。这避免了以下常见问题：
- 某个间接依赖被上游移除后，你的代码突然报错
- 不同版本的同名包产生意外冲突
- 团队成员之间依赖行为不一致
## 架构差异决定性能差距
三种包管理器的核心区别在于 node_modules 的组织方式：
| 特性 | npm | Yarn Berry | pnpm |
|------|-----|-----------|------|
| node_modules 结构 | 扁平化拷贝 | PnP 虚拟文件系统 | 嵌套软链接 + 硬链接 |
| 依赖存储 | 每项目独立拷贝 | 单个 .pnp.cjs 映射 | 全局 store 共享 |
| 幻影依赖 | 有 | 无（PnP 模式） | 无 |
| 硬链接复用 | 不支持 | 不支持 | 支持 |
| Monorepo 支持 | 基础 workspaces | 原生支持 | 原生 + workspace 协议 |
## 什么场景选 pnpm
- **多项目开发环境**：磁盘节省最明显，热安装接近即时
- **Monorepo 项目**：内置 workspace 协议和过滤，原生支持子项目间依赖联动
- **CI/CD 流水线**：配合 `prefer-frozen-lockfile=true`，冷安装速度也有明显优势
- **团队协作**：严格依赖模式保证每个人的依赖行为一致，减少"我这能跑你那不行"的问题
## 什么场景不选 pnpm
- 小型项目、原型验证：npm 零配置直接上手更省事
- 依赖大量 native 模块（如 node-gyp）：硬链接有时会遇到权限问题
- 现有项目已深度依赖 Yarn 插件生态：迁移成本需要评估
## 追问：pnpm 的局限性和注意事项
1. **严格模式可能导致兼容问题**：某些包假设了扁平化结构，在 pnpm 下可能报错，可通过 `.npmrc` 中设置 `shamefully-hoist=true` 回退到扁平模式（但会失去幻影依赖保护）
2. **全局 store 需要定期清理**：使用 `pnpm store prune` 清理不再被引用的包
3. **与 Yarn PnP 的取舍**：Yarn PnP 甚至不生成 node_modules 目录，安装更快但生态兼容性更差；pnpm 在性能和兼容性之间取了更好的平衡服务端5月28日 01:02
pnpm 的全局 store 是什么？如何管理和清理？pnpm 之所以能在磁盘占用和安装速度上远超 npm 和 yarn，核心就在于其全局 store 机制。理解 store 的原理，不仅能帮你排查依赖问题，还能在日常开发中做出更好的决策。
## 全局 store 是什么
全局 store 是 pnpm 在本地维护的一个集中式依赖仓库。所有项目安装的包，其文件都只存放在 store 中一份，项目通过硬链接（hard link）引用这些文件，而非复制副本。
这意味着：10 个项目都用 lodash@4.17.21，磁盘上只占一份 lodash 的空间。
## Store 的位置与结构
默认情况下，store 位于用户主目录下：
```bash
# macOS / Linux
~/.local/share/pnpm/store
# Windows
%LOCALAPPDATA%/pnpm/store
# 查看实际路径
pnpm store path
```
你可以通过 `.npmrc` 自定义 store 位置：
```
store-dir = /path/to/custom/store
```
store 内部采用内容寻址存储（Content-Addressable Storage，简称 CAFS）结构：
```
~/.local/share/pnpm/store/
├── v3/ # store 版本号
│ └── files/ # 基于内容 hash 组织的文件
│ ├── 00/
│ │ ├── abc123... # 文件内容，以 sha256 hash 命名
│ │ └── def456...
│ └── ...
└── metadata.json
```
每个文件按其内容的 SHA-256 哈希值存储。内容相同的文件只存一份，无论它属于哪个包的哪个版本。这就是 pnpm 节省磁盘空间的根本原因。
## 内容寻址存储（CAFS）与三层架构
pnpm 的依赖管理采用三层架构：
1. **全局 store（CAFS）**：实际文件存放处，按内容哈希索引
2. **虚拟存储（Virtual Store）**：每个项目的 `node_modules/.pnpm/` 目录，存放硬链接
3. **依赖解析层**：`node_modules` 中的符号链接，形成最终的可访问结构
当执行 `pnpm install` 时，pnpm 先检查 store 中是否已有对应文件的哈希值。如果有，直接创建硬链接到项目的虚拟存储；如果没有，先下载到 store 再创建链接。
### 硬链接与 inode 的关系
硬链接是理解 pnpm store 的关键。在文件系统中，每个文件都有一个 inode（索引节点），硬链接使得多个文件路径指向同一个 inode：
```
全局 store: ~/.local/share/pnpm/store/v3/files/00/abc123 (inode: 98765)
↓ 硬链接
项目A: project-a/node_modules/.pnpm/lodash@4.17.21/lodash.js → inode 98765
项目B: project-b/node_modules/.pnpm/lodash@4.17.21/lodash.js → inode 98765
```
关键特性：
- 硬链接不占额外磁盘空间，因为它们指向同一块数据
- 修改任一链接的文件内容，所有链接都会同步变化（所以不要手动修改 node_modules 里的文件）
- 删除一个链接不影响其他链接，只要还有链接存在，数据就不会丢失
## Store 管理：常用命令
```bash
# 查看 store 路径
pnpm store path
# 查看 store 状态（检查是否有损坏的包）
pnpm store status
# 清理未被任何项目引用的包
pnpm store prune
# pnpm 9+ 可验证 store 完整性
pnpm store verify
```
其中 `pnpm store prune` 是最常用的管理命令。它会扫描 store 中所有包，检查是否还有项目通过硬链接引用它们，未被引用的包将被删除释放空间。
## 什么时候需要清理 store
以下场景建议执行 `pnpm store prune`：
- **升级 pnpm 大版本后**：新版本的 store 结构可能不同，旧版本缓存可清理
- **大量项目删除后**：这些项目曾安装的包可能不再被任何项目引用
- **磁盘空间紧张时**：prune 通常能释放可观的磁盘空间
- **依赖版本迭代后**：项目升级了依赖版本，旧版本包可能不再被引用
注意：`pnpm store prune` 是安全操作，它只删除没有被任何项目引用的包，不会影响正在使用的依赖。
## 多 Store 配置
在特定场景下，你可能需要使用多个 store：
```bash
# 不同分区/文件系统的项目需要独立的 store
# 因为硬链接不能跨文件系统
# project-a/.npmrc
store-dir = /data/store-a
# project-b/.npmrc
store-dir = /data/store-b
```
跨文件系统是使用多 store 最常见的原因。如果项目和 store 在不同磁盘分区，硬链接会失败，pnpm 会退化为复制文件，失去空间优势。
## pnpm 11 的 store 变更
pnpm 11 对 store 做了重要改进：
- **SQLite 索引**：用 SQLite 数据库替代了原来每个包的 JSON 索引文件，减少了系统调用，安装速度进一步提升
- **项目追踪**：通过 `{storeDir}/v11/projects/` 中的符号链接注册项目，pnpm 能准确追踪哪些项目在使用哪些包，让 `store prune` 更加精准
- **全局虚拟存储**：全局安装的包现在有独立的隔离环境，每个 `pnpm add -g` 的包都有自己的目录和 lockfile
如果你在 pnpm 11 中遇到 store 相关问题，先确认 store 版本已正确迁移。
## 常见问题排查
**安装时报硬链接错误**：检查项目与 store 是否在同一文件系统。如果不是，配置 `store-dir` 到同一分区。
**store prune 后磁盘空间没变化**：可能有其他项目仍在引用这些包。用 `pnpm store status` 确认哪些包仍在使用。
**误删了 .pnpm-store 目录**：不会损坏已有项目，但下次安装依赖时需要重新下载。执行 `pnpm install` 即可重建。
服务端5月28日 01:01
pnpm 的 .npmrc 配置有哪些常用选项？pnpm 通过 `.npmrc` 文件管理配置，支持项目级、用户级、全局级三个层级，项目级优先级最高。掌握常用配置不仅影响日常开发效率，也是 Monorepo 和 CI/CD 环境的必备知识。
## 注册表与镜像源
最基础的配置是切换包下载源。国内开发者在项目根目录 `.npmrc` 中配置淘宝镜像几乎是标配：
```ini
registry=https://registry.npmmirror.com/
```
企业私有包则通过作用域隔离：
```ini
@mycompany:registry=https://npm.mycompany.com/
```
这样 `@mycompany/xxx` 包走私有源，其余走公共源，互不干扰。
## 依赖安装策略
几个配置项直接影响安装行为和依赖结构，也是面试高频考点：
**strict-peer-dependencies** — 设为 `true` 时，peer 依赖不满足会直接报错中断安装。默认 `false` 只警告。在大型 Monorepo 中建议开启，避免隐式依赖缺失导致的运行时问题。
```ini
strict-peer-dependencies=true
```
**auto-install-peers** — 自动安装缺失的 peer 依赖。和 `strict-peer-dependencies` 互斥，二选一：要么严格校验，要么自动补全。
```ini
auto-install-peers=true
```
**shamefully-hoist** — 提升所有依赖到根目录 `node_modules`，模拟 npm 的扁平结构。会破坏 pnpm 严格的依赖隔离，仅在遇到不兼容的第三方库（如依赖隐式引用）时才启用：
```ini
shamefully-hoist=true
```
## 存储与缓存
pnpm 的核心优势是内容寻址存储（content-addressable store），全局只存一份，各项目通过硬链接引用：
```ini
# 自定义 store 位置（默认 ~/.local/share/pnpm/store）
store-dir=/path/to/custom/store
# 包元数据缓存目录
cache-dir=/path/to/custom/cache
# 状态文件目录（pnpm-state.json）
state-dir=/path/to/custom/state
```
在 CI 环境中可以把 store 挂载到缓存卷，避免每次重新下载：
```ini
store-dir=/tmp/pnpm-store
```
## 网络与代理
网络配置在团队协作和企业环境中常用：
```ini
# 并发请求数（默认 16，网络好可调大）
network-concurrency=32
# 单次请求超时（毫秒，默认 60000）
fetch-timeout=60000
# 重试次数（默认 2）
fetch-retries=3
```
企业内网需要代理时：
```ini
proxy=http://proxy.company.com:8080
https-proxy=http://proxy.company.com:8080
no-proxy=localhost,127.0.0.1,internal.company.com
```
## Workspace（Monorepo）配置
pnpm Workspace 是 Monorepo 的核心能力，相关配置决定了包之间的链接行为：
```ini
# 允许 workspace 包互相链接
link-workspace-packages=true
# 优先使用 workspace 本地版本而非 registry 版本
prefer-workspace-packages=true
# pnpm add 时自动添加 workspace: 协议前缀
save-workspace-protocol=true
```
`link-workspace-packages=true` 配合 `prefer-workspace-packages=true` 后，workspace 内的包改动能即时反映到依赖方，无需手动 link。
## CI/CD 推荐配置
CI 环境对确定性和速度有严格要求，推荐以下组合：
```ini
# 不修改 lockfile，确保构建可复现
frozen-lockfile=true
# 优先使用本地缓存
prefer-offline=true
# 静默输出减少日志
reporter=silent
# 严格 peer 依赖检查
strict-peer-dependencies=true
```
`frozen-lockfile=true` 是 CI 的关键配置——如果 `pnpm-lock.yaml` 与 `package.json` 不一致，直接报错而非自动更新，防止不可复现的构建。
## Node.js 版本管理
pnpm 内置了 Node.js 版本管理能力，无需 nvm：
```ini
# 指定项目使用的 Node.js 版本
use-node-version=20.11.0
# 强制 engines 字段校验
engine-strict=true
```
国内下载 Node.js 较慢时，配置镜像：
```ini
node-mirror:release=https://npmmirror.com/mirrors/node/
```
## 安全相关
```ini
# 禁止执行 install 脚本（防范供应链攻击）
ignore-scripts=true
# SSL 证书校验（默认 true，不要轻易关闭）
strict-ssl=true
```
`ignore-scripts=true` 能阻断恶意包的 postinstall 脚本执行，但会导致部分依赖（如 esbuild、sharp）安装后需要手动 rebuild。
## 配置优先级
多个 `.npmrc` 同时存在时，优先级从高到低：
1. 命令行参数（`--registry=xxx`）
2. 环境变量（`npm_config_registry`）
3. 项目级 `.npmrc`（项目根目录）
4. 用户级 `~/.npmrc`
5. 全局 `/etc/npmrc`
6. pnpm 内置默认值
项目级配置优先级最高，意味着团队可以通过提交项目 `.npmrc` 到 Git 来统一配置，个人偏好放在 `~/.npmrc` 中。
## 查看与管理配置
```bash
# 查看所有生效配置
pnpm config list
# 查看某项配置
pnpm config get registry
# 设置（写入用户级 .npmrc）
pnpm config set registry https://registry.npmmirror.com/
# 删除
pnpm config delete registry
```
`.npmrc` 文件支持环境变量替换，语法为 `${NAME}` 或带默认值 `${NAME:-fallback}`，适合在 CI 中动态注入认证令牌：
```ini
//registry.npmjs.org/:_authToken=${NPM_TOKEN}
```服务端5月28日 01:00
pnpm-lock.yaml 的作用是什么？如何正确管理锁文件？pnpm-lock.yaml 是 pnpm 生成的锁文件，记录项目所有依赖（含间接依赖）的精确版本，确保在不同环境、不同时间安装得到完全一致的依赖树。
## 为什么需要锁文件
package.json 中声明的版本通常是范围（如 `^4.17.21`），这意味着不同时间执行 `pnpm install` 可能安装不同的补丁版本。锁文件的出现就是为了解决这个问题——它把每次安装的精确版本"拍了一张快照"，后续安装严格按快照执行。
没有锁文件时可能遇到的麻烦：
- 开发者 A 本地跑得好好的，开发者 B 装完依赖却报错——因为某个依赖发布了新的补丁版本
- CI 昨天构建成功，今天同样的代码构建失败——依赖行为变了
- 线上排查问题，无法复现当时的依赖版本
## pnpm-lock.yaml 的结构
```yaml
lockfileVersion: '6.0'
settings:
autoInstallPeers: true
excludeLinksFromLock: false
importers:
.:
dependencies:
lodash:
specifier: ^4.17.21
version: 4.17.21
packages:
/lodash@4.17.21:
resolution: {integrity: sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LbbZUZt0P2vK6s4I6F7McA==}
engines: {node: '>=6'}
dev: false
snapshots:
lodash@4.17.21: {}
```
**四个核心字段：**
1. **lockfileVersion** — 锁文件格式版本，pnpm 8 使用 `6.0`，pnpm 9 使用 `9.0`。版本不匹配时 pnpm 会自动重新解析依赖
2. **importers** — 记录每个 workspace 包的直接依赖，`specifier` 是 package.json 中声明的范围，`version` 是实际锁定的版本
3. **packages** — 所有依赖包的元数据，包含下载地址（resolution）、完整性校验（integrity）、引擎限制（engines）
4. **snapshots** — 依赖树快照，记录包之间的依赖关系
## pnpm 锁文件与 npm/yarn 锁文件的区别
| 特性 | pnpm-lock.yaml | package-lock.json | yarn.lock |
|------|---------------|-------------------|-----------|
| 格式 | YAML | JSON | 自定义格式 |
| 可读性 | 高 | 中 | 低 |
| 依赖存储 | content-addressable store（硬链接） | 扁平化 node_modules | 扁平化 node_modules |
| 是否记录间接依赖 | 是 | 是 | 是 |
| 磁盘占用 | 极低（全局 store 共享 + 硬链接） | 每个 project 独立存储 | 每个 project 独立存储 |
核心差异在于 pnpm 使用 content-addressable store：所有项目共享一个全局 store（默认 `~/.local/share/pnpm/store`），项目中的 node_modules 通过硬链接指向 store，而非复制。这意味着 10 个项目用同一个版本的 lodash，磁盘上只有一份文件。
## 锁文件的正确管理方式
**1. 必须提交到版本控制**
```bash
git add pnpm-lock.yaml
git commit -m "add lockfile"
```
锁文件和 package.json 是一对搭档，缺少锁文件等于放弃了版本一致性保障。
**2. CI 中使用冻结安装**
```bash
pnpm install --frozen-lockfile
```
`--frozen-lockfile` 要求锁文件与 package.json 完全一致，否则安装失败。这能防止 CI 中意外更新依赖导致构建不可复现。
**3. 更新依赖的正确姿势**
```bash
# 更新单个依赖（在版本范围内）
pnpm update lodash
# 更新所有依赖（在版本范围内）
pnpm update
# 更新到最新版本（忽略版本范围）
pnpm update --latest
# 交互式选择更新
pnpm update --interactive --latest
```
永远不要用删除锁文件的方式来更新依赖。
**4. 从 npm/yarn 迁移**
```bash
# 从 package-lock.json 或 yarn.lock 导入依赖信息
pnpm import
# 导入完成后删除旧锁文件
rm package-lock.json yarn.lock
# 生成 pnpm-lock.yaml
pnpm install
```
## 锁文件冲突的正确处理
多人协作时，合并分支经常会遇到 `pnpm-lock.yaml` 冲突。正确的处理流程：
```bash
# 1. 先解决 package.json 的冲突
# 手动编辑 package.json，保留需要的依赖
# 2. 运行 pnpm install 重新解析
pnpm install
# pnpm 会自动合并两个分支的依赖变更，生成新的锁文件
```
**常见错误做法：删除锁文件后重新生成。** 这会导致所有依赖被重新解析，可能引入意料之外的版本变更，而且丢失了之前锁定的版本信息。只有在极端情况下（如锁文件严重损坏）才考虑删除重建。
## Monorepo 中的锁文件
pnpm workspace 中只会有一个 `pnpm-lock.yaml`，放在项目根目录，包含所有 workspace 包的依赖。这意味着：
- 子包之间共享锁文件，依赖版本天然一致
- 修改任意子包的依赖，锁文件都会更新
- CI 只需在根目录执行一次 `pnpm install --frozen-lockfile`
```yaml
# pnpm-workspace.yaml
packages:
- 'apps/*'
- 'packages/*'
```
## pnpm 11+ 的锁文件策略
pnpm 11.1.3 引入了增强的锁文件校验机制，在安装前会重新检查锁文件是否符合当前策略（如 `minimumReleaseAge`、`trustPolicy: no-downgrade`）。这意味着：
- 来自旧环境或 CI 缓存的锁文件可能被拒绝
- 升级 pnpm 版本后，需要重新运行 `pnpm install` 更新锁文件
- `--frozen-lockfile` 配合新策略，安全性更高
## 面试追问方向
- **锁文件和 package.json 的关系是什么？** package.json 声明版本范围，锁文件锁定精确版本。`pnpm install` 优先读取锁文件，只在锁文件与 package.json 不一致时重新解析
- **为什么 pnpm 的锁文件比 npm 的更省磁盘？** pnpm 使用 content-addressable store + 硬链接，全局共享依赖文件，而 npm 在每个项目中复制一份
- **锁文件冲突时为什么不建议删除重建？** 删除重建会导致所有依赖重新解析，可能引入不兼容的版本，丢失已验证的依赖组合
- **`--frozen-lockfile` 和普通 `pnpm install` 有什么区别？** 前者要求锁文件与 package.json 完全一致，否则报错；后者允许在差异时更新锁文件服务端5月28日 00:26
npm 或 Yarn 项目迁移到 pnpm 需要注意哪些问题？## 为什么要迁移到 pnpm？
npm 和 Yarn 采用扁平化的 node_modules 结构，所有依赖都被提升到顶层目录。这带来两个核心问题：
- **幽灵依赖（Phantom Dependencies）**：你可以在代码中引用未在 package.json 中声明的包，因为 npm/Yarn 会把间接依赖也提升到顶层。一旦上游包移除了该间接依赖，你的项目就会突然崩溃。
- **依赖分身（NPM Dups）**：同一个包的不同版本可能被多次安装，浪费磁盘空间，还可能导致类型不一致。
pnpm 通过内容寻址存储 + 符号链接的方案解决了这些问题：全局只存一份包，项目通过符号链接引用，未声明的依赖直接不可访问。
## 迁移前该做哪些准备？
不要上来就删 node_modules，先确认几件事：
1. **确认 Node.js 版本**：pnpm 需要 Node.js 16.14+，建议 18+。
2. **记录当前依赖树**：执行 `npm ls --depth=0 > deps-backup.txt` 或 `yarn list --depth=0 > deps-backup.txt`，留个快照方便后续排查。
3. **确保测试覆盖**：迁移后需要跑一遍完整测试，没有测试的项目建议先补关键路径的测试。
4. **分支操作**：在独立分支上迁移，确认无误后再合入主分支。
## 第一步：安装 pnpm
推荐三种方式，按优先级排序：
**方式一：Corepack（官方推荐）**
```bash
corepack enable
corepack prepare pnpm@latest --activate
```
Corepack 是 Node.js 自带的包管理器管理工具，不需要全局安装 pnpm，避免版本冲突。
**方式二：独立安装脚本**
```bash
curl -fsSL https://get.pnpm.io/install.sh | sh -
```
**方式三：npm 全局安装（不推荐）**
```bash
npm install -g pnpm
```
这种方式可能导致 pnpm 自身的依赖和项目依赖产生冲突，仅在前两种方式不可用时使用。
## 第二步：清理旧产物
```bash
rm -rf node_modules
rm package-lock.json # npm 项目
rm yarn.lock # Yarn 项目
```
如果你用的是 npm shrinkwrap，也要删除 `npm-shrinkwrap.json`。
## 第三步：导入锁文件
```bash
pnpm import
```
这条命令会读取现有的 `package-lock.json` 或 `yarn.lock`，生成 `pnpm-lock.yaml`。导入完成后可以删掉旧锁文件。
如果锁文件有冲突或格式异常，`pnpm import` 可能报错，这时跳过导入直接 `pnpm install` 即可，pnpm 会根据 package.json 重新解析。
## 第四步：安装依赖
```bash
pnpm install
```
首次安装会建立全局 store（默认在 `~/.local/share/pnpm/store`），后续项目会复用已下载的包，速度会明显加快。
## 迁移后一定会遇到的三个问题
### 幽灵依赖报错：Cannot find module
这是迁移后最常见的问题。之前能用的包突然找不到了，原因是这些包从未在 package.json 中声明，只是碰巧被提升到了 node_modules 顶层。
排查方法：
```bash
# 查看哪个包实际提供了这个模块
pnpm why lodash
```
解决方式：显式安装缺失的依赖。
```bash
pnpm add lodash
```
如果缺失的包太多，可以用 `pnpm ls --depth=0` 对比迁移前的 `deps-backup.txt`，逐个补上。
### peer dependencies 报错
pnpm 默认严格检查 peer dependencies，这和 npm 的宽松行为不同。你可能会看到大量 UNMET PEER DEPENDENCY 警告。
**推荐的处理方式（按优先级）：**
1. **安装缺失的 peer 依赖**：直接 `pnpm add react react-dom`，这是最正确的做法。
2. **配置 peerDependencyRules 忽略特定警告**：
```json
{
"pnpm": {
"peerDependencyRules": {
"ignoreMissing": ["webpack", "@babel/core"],
"allowedVersions": {
"react": "18"
}
}
}
}
```
3. **自动安装 peer 依赖**（.npmrc）：
```ini
auto-install-peers=true
```
4. **放宽严格检查**（.npmrc）：
```ini
strict-peer-dependencies=false
```
### 运行时找不到模块
部分包在运行时通过动态 `require()` 加载模块，pnpm 的严格隔离会导致找不到。这时候可以用**针对性提升**而非全量提升：
```ini
# .npmrc - 只提升特定包
hoist-pattern[]=*react*
hoist-pattern[]=*emotion*
```
只有在针对性提升也无法解决时，才考虑使用 `shamefully-hoist=true`，它会创建类似 npm 的扁平结构，但会失去 pnpm 的严格依赖管理优势。
## .npmrc 推荐配置
```ini
# 迁移初期建议的配置
auto-install-peers=true # 自动安装 peer 依赖，减少迁移阻力
strict-peer-dependencies=false # 不因 peer 依赖不兼容而中断安装
shamefully-hoist=false # 保持严格隔离，不要轻易开启
# 如果遇到运行时找不到模块的问题，优先用 hoist-pattern 替代 shamefully-hoist
# hoist-pattern[]=*problematic-package*
```
## package.json 调整
```json
{
"scripts": {
"preinstall": "npx only-allow pnpm"
},
"engines": {
"pnpm": ">=9.0.0"
}
}
```
`preinstall` 脚本会在有人误用 `npm install` 时自动拦截，确保团队统一使用 pnpm。需要先安装 `only-allow`：
```bash
pnpm add -D only-allow
```
## CI/CD 配置更新
**GitHub Actions：**
```yaml
- uses: pnpm/action-setup@v4
with:
version: 9
- run: pnpm install --frozen-lockfile
```
**GitLab CI：**
```yaml
before_script:
- corepack enable
- pnpm install --frozen-lockfile
```
`--frozen-lockfile` 确保 CI 环境不会修改锁文件，和 npm 的 `npm ci` 作用一致。
## Monorepo 迁移
如果你使用 Lerna 或 Yarn Workspaces，迁移到 pnpm workspace 非常简单。
创建 `pnpm-workspace.yaml`：
```yaml
packages:
- 'packages/*'
- 'apps/*'
```
包间引用改用 `workspace:` 协议：
```json
{
"dependencies": {
"@my-org/utils": "workspace:*"
}
}
```
`workspace:*` 表示引用本地 workspace 中的包，发布时 pnpm 会自动替换为实际版本号。
## 迁移检查清单
```bash
# 1. 确认依赖安装完整
pnpm ls --depth=0
# 2. 运行测试
pnpm test
# 3. 构建项目
pnpm build
# 4. 检查 lint
pnpm lint
# 5. 本地启动验证
pnpm dev
```
每一步都通过后再合入主分支。
## 如果迁移失败怎么回滚？
```bash
rm pnpm-lock.yaml .npmrc
rm -rf node_modules
npm install # 或 yarn install
```
别忘了恢复 CI/CD 配置和 package.json 中 pnpm 相关的改动。
## 迁移后你能获得什么？
- **安装速度提升 2-3 倍**：全局 store 复用，跨项目共享已下载的包
- **磁盘空间节省 50-70%**：同一个包全局只存一份，通过硬链接引用
- **杜绝幽灵依赖**：未声明的包直接不可访问，提前暴露潜在风险
- **更严格的依赖管理**：peer dependencies 严格检查，避免版本冲突
- **原生 monorepo 支持**：workspace 协议比 Yarn Workspaces 更简洁服务端5月28日 00:25
什么是幽灵依赖？pnpm 如何解决这个问题？## 什么是幽灵依赖？
幽灵依赖（Phantom Dependency）是指项目代码中引用了 package.json 未显式声明的包，它之所以能正常运行，完全是因为 npm/Yarn 的扁平化 node_modules 机制把间接依赖提升到了顶层。
## 为什么会产生幽灵依赖？
npm v2 之前使用嵌套安装，导致大量重复依赖和路径过长问题。npm v3 及 Yarn 改为扁平化策略：把所有依赖尽量提升到 node_modules 根目录。
```bash
# package.json 只声明了 express
{
"dependencies": {
"express": "^4.18.0"
}
}
# npm/Yarn 扁平化后的目录结构
node_modules/
├── express/ # 直接依赖
├── debug/ # express 的依赖，被提升到顶层
├── ms/ # debug 的依赖，也被提升
├── body-parser/ # express 的依赖，同样被提升
└── ...
```
Node.js 的模块查找算法会从当前目录逐级向上查找 node_modules，所以 `require('debug')` 能直接找到被提升上来的 debug 包，即使你从未声明过它。
## 幽灵依赖有什么危害？
```javascript
// 代码中直接使用了未声明的 debug
const debug = require('debug');
// 能运行 —— 但这只是侥幸
// 风险场景：
// 1. express 某次升级后移除了对 debug 的依赖 → 你的代码直接报错
// 2. 另一位同事 clone 项目后 npm install → 可能安装到不同版本的 debug
// 3. CI 环境与本地依赖树不一致 → 构建时出现诡异失败
// 4. 安全审计工具不会标记未声明的包 → 漏洞无法被追踪
```
核心问题：**依赖关系不完整记录 = 项目可复现性被破坏**。
## pnpm 如何解决幽灵依赖？
pnpm 通过两套机制彻底杜绝幽灵依赖：
### 1. 内容寻址存储 + 硬链接
pnpm 在全局维护一个 `.store` 目录，所有包只存一份。项目中的 node_modules 通过硬链接指向 store，同一台机器上无论多少个项目共享同一版本的包，磁盘上只有一份内容。
### 2. 符号链接隔离结构
pnpm 的 node_modules 结构与传统扁平化截然不同：
```bash
node_modules/
├── .pnpm/
│ └── express@4.18.2/
│ └── node_modules/
│ ├── express/ # express 的实际内容
│ └── debug/ # express 自己能访问的依赖
│ └── node_modules/
│ └── ms/ # debug 的依赖，只对 debug 可见
├── express -> .pnpm/express@4.18.2/node_modules/express
# 注意：顶层只有 express，没有 debug、ms 等间接依赖
```
- **项目根目录的 node_modules** 只有 package.json 中声明的包（通过符号链接指向 .pnpm）
- **每个包自己的 node_modules** 只包含该包直接声明的依赖
```javascript
// pnpm 下尝试访问幽灵依赖
const debug = require('debug');
// Error: Cannot find module 'debug'
// 解决方式：显式声明
// pnpm add debug
```
### shamefully-hoist：过渡方案
pnpm 提供了 `shamefully-hoist=true` 配置，模拟 npm 的扁平化结构。它适用于那些尚未修复幽灵依赖的老项目，但不推荐作为长期方案——它本质上放弃了 pnpm 的隔离优势。
```ini
# .npmrc
shamefully-hoist=true
```
## npm/Yarn vs pnpm 对比
| 特性 | npm/Yarn | pnpm |
|------|----------|------|
| 依赖访问范围 | 可访问所有被提升的包 | 只能访问显式声明的依赖 |
| 依赖隔离 | 弱，扁平化导致间接依赖暴露 | 强，符号链接实现严格隔离 |
| 幽灵依赖 | 常见且难以发现 | 从结构上杜绝 |
| 磁盘占用 | 每个项目独立存储 | 全局 store + 硬链接，多项目共享 |
| 安装速度 | 较慢 | 显著更快（硬链接免去重复下载） |
| 依赖树一致性 | 不同环境可能不同 | 严格一致 |
## 面试追问要点
**Q: 为什么从 npm 迁移到 pnpm 后项目会报错？**
因为项目之前依赖了幽灵依赖。npm 下能侥幸运行，pnpm 的严格隔离直接暴露了这些未声明的依赖。修复方式是逐一 `pnpm add` 把缺失的依赖显式添加到 package.json。
**Q: pnpm 的 .pnpm 目录结构如何保证依赖隔离？**
每个包在 .pnpm 下拥有独立的 node_modules 子树，其中只包含该包自身声明的依赖。Node.js 的模块查找算法在当前包的 node_modules 内就能找到所需依赖，不会向上穿透到其他包的作用域。
**Q: 如果不使用 pnpm，如何检测幽灵依赖？**
可以使用 `npx depcheck` 工具扫描未声明但被使用的包，也可以在 npm 7+ 中开启 `install-strategy=nested` 改用嵌套安装来暴露问题。服务端3月6日 21:35
pnpm 如何使用硬链接和符号链接来节省磁盘空间？pnpm 通过硬链接和符号链接的组合实现高效的磁盘空间利用：
**硬链接（Hard Links）**
硬链接是指向文件系统中同一文件的多个引用。
```bash
# pnpm 的硬链接机制
# 全局 store 位置
~/.pnpm-store/v3/files/00/abc123... # 实际文件
# 项目中的硬链接
project-a/node_modules/.pnpm/lodash@4.17.21/node_modules/lodash.js
project-b/node_modules/.pnpm/lodash@4.17.21/node_modules/lodash.js
# 两者都指向同一个物理文件，不占用额外空间
```
**特点：**
- 多个硬链接共享同一个 inode
- 删除一个链接不影响其他链接
- 修改会反映到所有链接
**符号链接（Symbolic Links/Soft Links）**
符号链接是指向文件路径的特殊文件。
```bash
# pnpm 的符号链接结构
node_modules/lodash -> .pnpm/lodash@4.17.21/node_modules/lodash
# 这是一个指向相对路径的符号链接
```
**特点：**
- 类似于快捷方式
- 可以跨文件系统
- 原文件删除后链接失效
**pnpm 的组合使用：**
```
项目结构：
node_modules/
├── lodash -> .pnpm/lodash@4.17.21/node_modules/lodash [符号链接]
└── .pnpm/
└── lodash@4.17.21/node_modules/
└── lodash.js [硬链接 → 全局 store]
```
**实际效果：**
```javascript
// 查看 inode 验证硬链接
const fs = require('fs');
const stat1 = fs.statSync('project-a/node_modules/.pnpm/lodash@4.17.21/lodash.js');
const stat2 = fs.statSync('project-b/node_modules/.pnpm/lodash@4.17.21/lodash.js');
console.log(stat1.ino === stat2.ino); // true，同一个 inode
```
**空间节省示例：**
```
# npm 方式：10个项目使用 lodash
10 × 1.4MB = 14MB
# pnpm 方式：10个项目使用 lodash
1 × 1.4MB = 1.4MB（节省 90%）
```前端2024年7月17日 10:45
bun比pnpm快吗?## Bun的性能
Bun 是一个全新的 JavaScript 运行时和包管理器，它主要关注性能优化。根据Bun官方的宣传和社区反馈，Bun在安装依赖包时的速度非常快。这主要得益于其使用的是单一的存储文件（而不是node_modules目录结构）和Zig语言编写的本地执行文件，这使得其在文件操作上非常快。
### Bun 与 pnpm 的比较
pnpm 也是一个非常注重性能的包管理器，其主要特点是通过硬链接和符号链接来节省磁盘空间并提高安装速度。pnpm 在处理依赖时采用了不同于npm的策略，这使得它在多个项目使用相同依赖时更加高效。
### 示例比较
假设我们有一个中等复杂度的项目，使用 npm 或 yarn 可能需要30秒才能完成依赖安装，而使用pnpm可能只需要约15秒。根据社区的反馈和一些早期测试，使用Bun可能进一步减少这个时间，可能在10秒左右完成相同任务。
### 总结
总的来说，Bun在性能方面展现出了很大的潜力，特别是在包安装速度方面，可能会比pnpm更快。然而，值得注意的是，Bun作为一个新出现的工具，可能还不如pnpm稳定或者在所有场景下都有优秀的表现。选择哪个包管理器还要根据团队的具体需求和现有的项目结构来决定。
前端2024年7月17日 10:42
pnpm的缺点是什么?pnpm（Performant npm）是一种流行的包管理工具，它以其高效的存储方式和速度而著称。然而，尽管有许多优点，pnpm也存在一些缺点，以下是主要的几点：
1. **兼容性问题**：尽管pnpm致力于与npm兼容，但在一些复杂的项目中，可能会遇到因依赖处理方式不同而导致的兼容性问题。pnpm通过使用软链接和独特的`node_modules`结构来优化存储空间和安装速度，这有时可能会导致与依赖于特定文件结构的工具或脚本不兼容。
2. **社区和生态系统支持**：虽然pnpm的用户基础在增长，但它的社区和生态系统仍然不如npm或Yarn那样成熟和广泛。这意味着对于某些特定的问题或边缘情况，可能找不到现成的解决方案或者外部插件支持。
3. **学习曲线**：对于新用户来说，pnpm引入的一些独特概念（如软链接的`node_modules`结构）可能需要一定的学习和适应。虽然这些特性为pnpm带来了性能上的优势，但也可能让新用户在刚开始时感到困惑。
4. **迁移成本**：对于已经使用npm或Yarn的项目，切换到pnpm可能涉及一定的迁移成本。虽然pnpm提供了工具和指令来简化迁移过程，但在某些大型或复杂的项目中，迁移过程可能会遇到问题，需要时间和资源来解决。
5. **在某些环境下的表现**：根据用户反馈，尽管pnpm在多数情况下表现优异，但在某些特定的系统或配置下，其性能可能不如预期。这可能涉及到pnpm如何在不同的文件系统或操作系统上处理文件链接和缓存。
总的来说，尽管pnpm提供了许多令人吸引的特性，比如高效的空间利用和速度，它仍然有一些缺点需要考虑。对于考虑使用pnpm的团队或个人，了解这些潜在的问题并评估它们是否会影响你的具体场景是非常重要的。前端2024年7月17日 10:39
PNPM 为什么速度这么快？### PNPM 为什么速度这么快？
PNPM（Performant NPM）之所以速度较快，主要归功于它独特的**链接和存储策略**，以及对依赖关系的高效管理。以下是几个关键因素：
#### 1. **硬链接和符号链接的使用**
PNPM 使用硬链接和符号链接来管理节点模块中的文件。当你安装一个包时，PNPM 并不会像 npm 或 yarn 那样复制包的文件到每个项目的 `node_modules` 目录中。相反，它将包的版本存储在一个单独的全局仓库中，并在项目的 `node_modules` 目录中创建到这些文件的链接。
这种方法的优势在于：
- **节省空间**：由于文件不是被复制的，而是被链接的，所以多个项目使用相同版本的包时可以共享这些文件，从而显著减少磁盘空间的使用。
- **加速安装过程**：链接文件比复制文件要快得多，这直接导致了安装过程的加速。
#### 2. **高效的依赖树管理**
PNPM 创建了一个扁平的依赖树，这样做的好处是依赖的处理更为高效。它严格遵循包的依赖版本，确保了依赖树的一致性，避免了不必要的版本冲突和重复。
#### 3. **并发安装**
当执行安装操作时，PNPM 能够并行处理多个依赖包的安装。这利用了现代多核 CPU 的能力，进一步提高了安装过程的速度。
#### 4. **更智能的缓存机制**
PNPM 对下载过的包进行缓存，这意味着当你再次安装相同版本的包时，如果本地已有缓存，PNPM 可以立即使用这些缓存，而无需重新从网络下载，显著提升了安装效率。
#### 实例
例如，在我的一个大型项目中，使用 npm 安装所有依赖可能需要超过 10 分钟，而切换到 PNPM 后，相同的安装过程缩短到了大约 2 分钟。这主要归功于 PNPM 的硬链接文件处理和高效的依赖管理。此外，多个项目共享同一套缓存的依赖，使得新项目的初始化变得极为迅速和高效。
### 结论
总结来说，PNPM 之所以快，是因为它在依赖管理和文件存储方面采用了非常高效且创新的方法。这些方法优化了安装过程，减少了磁盘空间的占用，并利用现代硬件的并行处理能力，有效提升了性能。