---
name: pnpm-catalogs
description: 工作区的集中化依赖版本管理
---

# pnpm Catalogs

Catalogs 提供了在工作区内集中管理依赖版本的方式。只需定义一次版本，即可在全局使用。

## 基本用法

在 `pnpm-workspace.yaml` 中定义 catalog：

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

catalog:
  react: ^18.2.0
  react-dom: ^18.2.0
  typescript: ~5.3.0
  vite: ^5.0.0
```

在 `package.json` 中使用 `catalog:` 引用：

```json
{
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:"
  },
  "devDependencies": {
    "typescript": "catalog:",
    "vite": "catalog:"
  }
}
```

## 命名 Catalog

为不同场景创建多个 catalog：

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

# 默认 catalog
catalog:
  lodash: ^4.17.21

# 命名 catalogs
catalogs:
  react17:
    react: ^17.0.2
    react-dom: ^17.0.2
  
  react18:
    react: ^18.2.0
    react-dom: ^18.2.0
  
  testing:
    vitest: ^1.0.0
    "@testing-library/react": ^14.0.0
```

引用命名 catalog：

```json
{
  "dependencies": {
    "react": "catalog:react18",
    "react-dom": "catalog:react18"
  },
  "devDependencies": {
    "vitest": "catalog:testing"
  }
}
```

## 优势

1. **单一数据源**：只需在一个地方更新版本
2. **一致性**：所有包使用相同的版本
3. **轻松升级**：修改一次版本，影响整个工作区
4. **类型安全**：pnpm-workspace.yaml 支持 TypeScript

## Catalog 与 Overrides 对比

| 特性 | Catalogs | Overrides |
|---------|----------|-----------|
| 用途 | 为直接依赖定义版本 | 强制指定任意依赖的版本 |
| 范围 | 仅限直接依赖 | 所有依赖（包括传递依赖） |
| 使用方式 | `"pkg": "catalog:"` | 自动应用 |
| 选择加入 | 每个 package.json 显式声明 | 工作区全局生效 |

## 发布时使用 Catalog

发布时，`catalog:` 引用会被替换为实际版本：

```json
// 发布前（源码）
{
  "dependencies": {
    "react": "catalog:"
  }
}

// 发布后（已发布的包）
{
  "dependencies": {
    "react": "^18.2.0"
  }
}
```

## 从 Overrides 迁移

如果你正在使用 overrides 来实现版本一致性：

```yaml
# 之前（使用 overrides）
overrides:
  react: ^18.2.0
  react-dom: ^18.2.0
```

迁移到 catalogs 以获得更清晰的依赖管理：

```yaml
# 之后（使用 catalogs）
catalog:
  react: ^18.2.0
  react-dom: ^18.2.0
```

然后更新 package.json 文件以使用 `catalog:`。

## 最佳实践

1. **使用默认 catalog** 来管理通用共享依赖
2. **使用命名 catalog** 来管理版本变体（例如不同 React 版本）
3. **保持 catalog 精简**——只包含共享依赖
4. **对内部包使用 workspace 协议**

```yaml
catalog:
  # 外部共享依赖
  lodash: ^4.17.21
  zod: ^3.22.0

# 内部包使用 workspace: 协议
# "dependencies": { "@myorg/utils": "workspace:^" }
```

<!-- 
参考来源：
- https://pnpm.io/catalogs
-->