skillhub-047-pnpm/references/features-catalogs.md

name, description

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

pnpm Catalogs

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

基本用法

在 pnpm-workspace.yaml 中定义 catalog：

packages:
  - 'packages/*'

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

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

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

命名 Catalog

为不同场景创建多个 catalog：

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：

{
  "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: 引用会被替换为实际版本：

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

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

从 Overrides 迁移

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

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

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

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

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

最佳实践

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

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

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