---
name: pnpm-overrides
description: 强制指定依赖（含传递依赖）的版本
---

# pnpm Overrides

Overrides 机制允许你强制指定包的特定版本，包括传递依赖。适用于修复安全漏洞或兼容性问题。

## 基本语法

在 `pnpm-workspace.yaml`（推荐）或 `package.json` 中定义 overrides：

### 在 pnpm-workspace.yaml 中（推荐）

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

overrides:
  # 覆盖某个包的所有版本
  lodash: ^4.17.21
  
  # 覆盖特定版本范围
  "foo@^1.0.0": ^1.2.3
  
  # 覆盖嵌套依赖
  "express>cookie": ^0.6.0
  
  # 替换为不同的包
  "underscore": "npm:lodash@^4.17.21"
```

### 在 package.json 中

```json
{
  "pnpm": {
    "overrides": {
      "lodash": "^4.17.21",
      "foo@^1.0.0": "^1.2.3",
      "bar@^2.0.0>qux": "^1.0.0"
    }
  }
}
```

## Override 模式

### 覆盖所有实例
```yaml
overrides:
  lodash: ^4.17.21
```
强制所有 lodash 安装使用 ^4.17.21。

### 覆盖特定父级版本
```yaml
overrides:
  "foo@^1.0.0": ^1.2.3
```
仅当 foo 请求的版本匹配 ^1.0.0 时才覆盖。

### 覆盖嵌套依赖
```yaml
overrides:
  "express>cookie": ^0.6.0
  "foo@1.x>bar@^2.0.0>qux": ^1.0.0
```
仅在 cookie 作为 express 的依赖时才覆盖。

### 替换为不同的包
```yaml
overrides:
  # 将 underscore 替换为 lodash
  "underscore": "npm:lodash@^4.17.21"
  
  # 使用本地文件
  "some-pkg": "file:./local-pkg"
  
  # 使用 Git
  "some-pkg": "github:user/repo#commit"
```

### 移除某个依赖
```yaml
overrides:
  "unwanted-pkg": "-"
```
`-` 将该包完全移除。

## 常见用例

### 安全修复

强制使用打了补丁的有漏洞包版本：

```yaml
overrides:
  # 修复传递依赖中的 CVE
  "minimist": "^1.2.6"
  "json5": "^2.2.3"
```

### 去重依赖

当安装多个版本时强制使用单一版本：

```yaml
overrides:
  "react": "^18.2.0"
  "react-dom": "^18.2.0"
```

### 修复对等依赖问题

```yaml
overrides:
  "@types/react": "^18.2.0"
```

### 替换已废弃的包

```yaml
overrides:
  "request": "npm:@cypress/request@^3.0.0"
```

## Hooks 替代方案

对于更复杂的场景，可使用 `.pnpmfile.cjs`：

```js
// .pnpmfile.cjs
function readPackage(pkg, context) {
  // 覆盖依赖版本
  if (pkg.dependencies?.lodash) {
    pkg.dependencies.lodash = '^4.17.21'
  }
  
  // 添加缺失的对等依赖
  if (pkg.name === 'some-package') {
    pkg.peerDependencies = {
      ...pkg.peerDependencies,
      react: '*'
    }
  }
  
  return pkg
}

module.exports = {
  hooks: {
    readPackage
  }
}
```

## Overrides 与 Catalogs 对比

| 特性 | Overrides | Catalogs |
|---------|-----------|----------|
| 影响范围 | 所有依赖（含传递依赖） | 仅直接依赖 |
| 使用方式 | 自动生效 | 需显式引用 `catalog:` |
| 目的 | 强制版本、修复问题 | 版本管理 |
| 粒度 | 可定位到特定父级 | 仅包级范围 |

## 调试

检查已解析的版本：

```bash
# 查看已解析的版本
pnpm why lodash

# 列出所有版本
pnpm list lodash --depth=Infinity
```

<!-- 
Source references:
- https://pnpm.io/package_json#pnpmoverrides
- https://pnpm.io/pnpmfile
-->