目录

已添加于：v9.5.0

¥Added in: v9.5.0

"目录" 是用于将依赖版本范围定义为可重用常量的 工作区功能。目录中定义的常量稍后可以在 package.json 文件中引用。

¥"Catalogs" are a workspace feature for defining dependency version ranges as reusable constants. Constants defined in catalogs can later be referenced in package.json files.

目录协议 (catalog:)

¥The Catalog Protocol (catalog:)

一旦在 pnpm-workspace.yaml 中定义了目录，

¥Once a catalog is defined in pnpm-workspace.yaml,

pnpm-workspace.yaml

packages:
  - packages/*

# Define a catalog of version ranges.
catalog:
  react: ^18.3.1
  redux: ^5.0.1

可以使用 catalog: 协议代替版本范围本身。

¥The catalog: protocol can be used instead of the version range itself.

packages/example-app/package.json

{
  "name": "@example/app",
  "dependencies": {
    "react": "catalog:",
    "redux": "catalog:"
  }
}

这相当于直接编写版本范围（例如 ^18.3.1）。

¥This is equivalent to writing a version range (e.g. ^18.3.1) directly.

packages/example-app/package.json

{
  "name": "@example/app",
  "dependencies": {
    "react": "^18.3.1",
    "redux": "^5.0.1"
  }
}

你可以在 package.json 的以下字段中使用 catalog: 协议：

¥You may use the catalog: protocol in the next fields of your package.json:

• dependencies

• devDependencies

• peerDependencies

• optionalDependencies

• pnpm.overrides

catalog: 协议允许在冒号后使用可选名称（例如：catalog:name）来指定应使用哪个目录。省略名称时，将使用默认目录。

¥The catalog: protocol allows an optional name after the colon (ex: catalog:name) to specify which catalog should be used. When a name is omitted, the default catalog is used.

根据场景，与直接编写版本范围相比，catalog: 协议提供了一些 advantages，下面将详细介绍。

¥Depending on the scenario, the catalog: protocol offers a few advantages compared to writing version ranges directly that are detailed next.

优点

¥Advantages

在工作区（即 monorepo 或多包存储库）中，许多包通常使用相同的依赖。目录在编写 package.json 文件时减少了重复，并提供了一些好处：

¥In a workspace (i.e. monorepo or multi-package repo) it's common for the same dependency to be used by many packages. Catalogs reduce duplication when authoring package.json files and provide a few benefits in doing so:

• 维护唯一版本 — 通常希望工作区中只有一个版本的依赖。目录使其更易于维护。重复的依赖可能会在运行时发生冲突并导致错误。使用打包器时，重复项也会增加大小。

  ¥Maintain unique versions — It's usually desirable to have only one version of a dependency in a workspace. Catalogs make this easier to maintain. Duplicated dependencies can conflict at runtime and cause bugs. Duplicates also increase size when using a bundler.

• 更容易升级 - 升级依赖时，只需要编辑 pnpm-workspace.yaml 中的目录条目，而不是使用该依赖的所有 package.json 文件。这节省了时间 - 只需要更改一行，而不是很多行。

  ¥Easier upgrades — When upgrading a dependency, only the catalog entry in pnpm-workspace.yaml needs to be edited rather than all package.json files using that dependency. This saves time — only one line needs to be changed instead of many.

• 更少的合并冲突 — 由于在升级依赖时不需要编辑 package.json 文件，因此这些文件中不再发生 git 合并冲突。

  ¥Fewer merge conflicts — Since package.json files do not need to be edited when upgrading a dependency, git merge conflicts no longer happen in these files.

定义目录

¥Defining Catalogs

目录在 pnpm-workspace.yaml 文件中定义。有两种定义目录的方法。

¥Catalogs are defined in the pnpm-workspace.yaml file. There are two ways to define catalogs.

1. 使用（单数）catalog 字段创建名为 default 的目录。

   ¥Using the (singular) catalog field to create a catalog named default.

2. 使用（复数）catalogs 字段创建任意命名的目录。

   ¥Using the (plural) catalogs field to create arbitrarily named catalogs.

提示

如果你有一个现有的工作区，想要使用目录迁移到该工作区，则可以使用以下 codemod：

¥If you have an existing workspace that you want to migrate to using catalogs, you can use the following codemod:

pnpx codemod pnpm/catalog

默认目录

¥Default Catalog

顶层 catalog 字段允许用户定义名为 default 的目录。

¥The top-level catalog field allows users to define a catalog named default.

pnpm-workspace.yaml

catalog:
  react: ^18.2.0
  react-dom: ^18.2.0

可以通过 catalog:default 引用这些版本范围。仅对于默认目录，也可以使用特殊的 catalog: 简写。将 catalog: 视为扩展为 catalog:default 的简写。

¥These version ranges can be referenced through catalog:default. For the default catalog only, a special catalog: shorthand can also be used. Think of catalog: as a shorthand that expands to catalog:default.

命名目录

¥Named Catalogs

可以在 catalogs 键下配置具有任意选择名称的多个目录。

¥Multiple catalogs with arbitrarily chosen names can be configured under the catalogs key.

pnpm-workspace.yaml

catalogs:
  # Can be referenced through "catalog:react17"
  react17:
    react: ^17.0.2
    react-dom: ^17.0.2

  # Can be referenced through "catalog:react18"
  react18:
    react: ^18.2.0
    react-dom: ^18.2.0

可以定义一个默认目录以及多个命名目录。这可能在大型多包存储库中很有用，这些存储库正在逐步迁移到依赖的较新版本。

¥A default catalog can be defined alongside multiple named catalogs. This might be useful in a large multi-package repo that's migrating to a newer version of a dependency piecemeal.

pnpm-workspace.yaml

catalog:
  react: ^16.14.0
  react-dom: ^16.14.0

catalogs:
  # Can be referenced through "catalog:react17"
  react17:
    react: ^17.0.2
    react-dom: ^17.0.2

  # Can be referenced through "catalog:react18"
  react18:
    react: ^18.2.0
    react-dom: ^18.2.0

发布

¥Publishing

运行 pnpm publish 或 pnpm pack 时，将删除 catalog: 协议。这类似于 workspace: 协议，即 发布时也替换。

¥The catalog: protocol is removed when running pnpm publish or pnpm pack. This is similar to the workspace: protocol, which is also replaced on publish.

例如，

¥For example,

packages/example-components/package.json

{
  "name": "@example/components",
  "dependencies": {
    "react": "catalog:react18",
  }
}

发布时将成为以下内容。

¥Will become the following on publish.

packages/example-components/package.json

{
  "name": "@example/components",
  "dependencies": {
    "react": "^18.3.1",
  }
}

catalog: 协议替换过程允许其他工作区或包管理器使用 @example/components 包。

¥The catalog: protocol replacement process allows the @example/components package to be used by other workspaces or package managers.

注意事项

¥Caveats

pnpm update 命令尚不支持目录。

¥The pnpm update command does not yet support catalogs.

要更新 pnpm-workspace.yaml 中定义的依赖，需要手动选择较新的版本范围，直到 pnpm 的未来版本处理此问题。

¥To update dependencies defined in pnpm-workspace.yaml, newer version ranges will need to be chosen manually until a future version of pnpm handles this.