版本：11 & 12

Dependency Resolution Settings

overrides

此字段允许你指示 pnpm 覆盖依赖关系图中的任何依赖项，包括对等依赖项。这对于强制所有软件包使用一个依赖项的单个版本、反向移植一个修复、用分叉替换依赖项或删除未使用的依赖项很有用。

请注意，overrides 字段只能在项目的根目录下设置。

overrides 字段的示例：

overrides:
  "foo": "^1.0.0"
  "quux": "npm:@myorg/quux@^1.0.0"
  "bar@^2.1.0": "3.0.0"
  "qar@1>zoo": "2"

你可以用 ">" 来覆盖某个包下的子依赖的版本，比如 qar@1>zoo 只会覆盖 qar@1 依赖的 zoo 的版本，而不会影响其他依赖。

To keep an overridden version in sync with the version used elsewhere in your workspace, define the version in a catalog and reference it with the catalog: protocol. 这样一来，版本号便统一维护于一处，并同时被你的依赖项和覆盖项引用：

pnpm-workspace.yaml
catalog:
  foo: "^1.0.0"

overrides:
  foo: "catalog:"

你也可以使用 catalog:<name> 引用已命名的目录。 See Catalogs for more details.

如果你发现你使用某个包不需要它的依赖之一，你可以使用 - 来删除它。例如，如果软件包 foo@1.0.0 需要一个名为 bar 的大型软件包来实现你不使用的功能，删除它可以减少安装时间：

overrides:
  "foo@1.0.0>bar": "-"

此功能对于 optionalDependencies 特别有用，其中大多数可选包可以被安全地跳过。

合并覆盖

Added in: v11.13.0

带有空范围的选择器（即 "pkg@"）是一种收敛覆盖（convergence override）。 Unlike a regular override, which rewrites every matching edge unconditionally, a convergence override rewrites a dependency edge only when its version satisfies the range that edge declares:

pnpm-workspace.yaml
overrides:
  "form-data@": 4.0.6

基于上述配置，声明 form-data: "^4.0.5" 的依赖会被锁定在 4.0.6 版本，而声明 ^3.0.0 的依赖则保持其原有的解析结果。这使得兼容的消费者能够统一使用同一个版本——无论是当前版本，还是未来添加的任何依赖版本——而无需强迫依赖图中的其他部分使用不兼容的版本。

规则：

该数值必须是精确的版本。使用版本范围、dist-tag 或 - 移除操作时，会因 ERR_PNPM_INVALID_CONVERGENCE_OVERRIDE 错误而失败。只要 catalog: 引用能解析为确切版本，该引用就是允许的。
仅涉及普通的语义化版本依赖关系。对于声明为 workspace:、catalog:、npm:、dist-tag 或 git/URL 格式的依赖，由于不存在有意义的“满足”关系，它们将保持原样，不予处理。
Convergence overrides cannot be combined with a parent selector: "parent>pkg@" is rejected.
A regular override always wins over a convergence override for the same edge.

When a full resolution finds that every declared range also admits a newer version, pnpm warns that the override is stale and names the version to converge on instead.

注意

Before v11.13.0, an empty range in an override selector was undocumented and behaved like a bare (unscoped) override.

覆盖对等依赖项

覆盖规则也适用于 peerDependencies。该行为取决于覆盖中使用的版本说明符类型：

语义版本范围（例如，^1.0.0）、工作区和目录协议：对等依赖项被覆盖，并且仍然是对等依赖项。
非范围指定符如“link：”或“file：”协议：对等依赖被覆盖并移至“依赖”，因为这些不是有效的对等依赖范围。
移除（-）：完全移除对等依赖项。

例如，要覆盖 react-dom 的 react 对等依赖项：

pnpm-workspace.yaml
overrides:
  "react-dom>react": "18.1.0"

packageExtensions

packageExtension 字段提供了一种用额外信息扩展现有软件包定义的方法。例如，如果 react-redux 本应该在它的 peerDependencies 中包含 react-dom 但它没有，则可以用 packageExtensions 来填补上 react-redux。

packageExtensions:
  react-redux:
    peerDependencies:
      react-dom: "*"

packageExtensions 中的键是包名或包名和 semver 范围，因此可以只修补包的某些版本：

packageExtensions:
  react-redux@1:
    peerDependencies:
      react-dom: "*"

以下字段可以使用 packageExtensions 进行扩展： dependencies、optionalDependencies、peerDependencies 和 peerDependenciesMeta。

一个更大的例子：

packageExtensions:
  express@1:
    optionalDependencies:
      typescript: "2"
  fork-ts-checker-webpack-plugin:
    dependencies:
      "@babel/core": "1"
    peerDependencies:
      eslint: ">= 6"
    peerDependenciesMeta:
      eslint:
        optional: true

提示

我们与 Yarn 一起维护一个 packageExtensions 的数据库，以便修补在生态系统中损坏的包。如果你使用 packageExtensions, 考虑发送一个 PR 上游并将你的扩展贡献给 [@yarnpkg/extension] 数据库。

allowedDeprecatedVersions

此项设置允许忽略特定依赖包的 deprecation 警告。

示例：

allowedDeprecatedVersions:
  express: "1"
  request: "*"

使用上述配置，pnpm 将不会打印 request 任何版本和 express v1 版本的弃用警告。

update

Added in: v11.16.0

Settings in this section tune the pnpm update and pnpm outdated commands.

update.ignoreDeps

有时您无法更新依赖项。例如，最新版本的依赖项开始使用 ESM，但您的项目尚未采用 ESM。恼人的是，这样的包将始终被 pnpm outdated 命令打印出来，并在运行 pnpm update --latest 时更新。 However, you may list packages that you don't want to upgrade in the ignoreDeps field:

update:
  ignoreDeps:
  - load-json-file

模式匹配也是支持的，因此你可以忽略在特定范围内的任何包： @babel/*。

update.changeset

Added in: v11.16.0

默认值： false
类型：Boolean

When true, pnpm update writes a change intent after updating workspace manifests, declaring a patch bump for every workspace package whose dependencies or optionalDependencies were changed by the update and a major bump when its peerDependencies changed. Same as passing --changeset; pass --no-changeset to override the setting for a single run.

update.githubActions

Added in: v11.16.0

默认值： false
类型：Boolean

When true, pnpm update and pnpm outdated also check the GitHub Actions referenced by the repository's workflow files. Same as passing --include-github-actions. See Updating GitHub Actions.

update.githubActionsServer

Added in: v11.17.0

Default: the GITHUB_SERVER_URL environment variable, falling back to https://github.com
类型：URL

The base URL of the GitHub server that hosts the repositories of the GitHub Actions referenced by the workflow files (for example, a GitHub Enterprise Server). The URL must use the https:// or http:// protocol. Only use http:// for a trusted server on a trusted network: the refs used to pin actions to commit hashes are fetched over this URL, and unencrypted traffic can be tampered with.

提示

Before v11.16.0, update.ignoreDeps was named updateConfig.ignoreDependencies. The deprecated updateConfig setting keeps working until the next major version; when both are set, the update section takes precedence and a warning is printed.

支持的架构

你可以指定要安装的可选依赖项的架构，即使它们与运行安装的系统的架构不匹配。

例如，以下配置指示安装 Windows x64 的可选依赖项：

supportedArchitectures:
  os:
  - win32
  cpu:
  - x64

而此配置将为 Windows、macOS 以及当前正在运行安装的系统架构安装可选依赖项。它包括 x64 和 arm64 CPU 的工件：

supportedArchitectures:
  os:
  - win32
  - darwin
  - current
  cpu:
  - x64
  - arm64

另外， supportedArchitectures 还支持指定系统的 libc。

ignoredOptionalDependencies

如果可选依赖项的名称包含在此数组中，则会跳过它。例如：

ignoredOptionalDependencies:
- fsevents
- "@esbuild/*"

minimumReleaseAge

添加于：v10.16.0

默认值：1440（自 v11 版本起），0（v11 版本之前）
类型：number (分钟)

为了降低安装受损软件包的风险，你可以延迟安装新发布的版本。大多数情况下，恶意发布会在一小时内被发现并从注册源中删除。

minimumReleaseAge 设置定义了版本发布后 pnpm 安装之前必须经过的最少分钟数。这适用于所有依赖项，包括传递依赖项。

例如，以下设置确保只能安装至少一天前发布的软件包：

minimumReleaseAge: 1440

minimumReleaseAgeExclude

添加于：v10.16.0

默认值：undefined
类型：string[]

如果你设置了 minimumReleaseAge，但需要某些依赖项始终立即安装最新版本，则可以在 minimumReleaseAgeExclude 列出它们。排除由 软件包名称 起作用，适用于该软件包的所有版本。

示例：

minimumReleaseAge: 1440
minimumReleaseAgeExclude:
- webpack
- react

在这种情况下，所有依赖项必须至少存在一天，除了 webpack 和 react，它们在发布时立即安装。

添加于: v10.17.0

你也可以使用模式。例如，允许你组织中的所有包：

minimumReleaseAge: 1440
minimumReleaseAgeExclude:
- '@myorg/*'

添加于：v10.19.0

你也可以排除特定版本（或使用 || 的特定版本列表）。这允许固定对到期时间规则的例外：

minimumReleaseAge: 1440
minimumReleaseAgeExclude:
- nx@21.6.5
- webpack@4.47.0 || 5.102.1

minimumReleaseAgeIgnoreMissingTime

添加于：v11.0.0

默认值：true
类型：Boolean

当 true 时，pnpm 会跳过对注册源元数据中不包含 time 字段的软件包的 minimumReleaseAge 检查（一些私有注册源和镜像会省略它）。设置为 false 则在这种情况下解析失败，而不是安装软件包。

minimumReleaseAgeIgnoreMissingTime: false

minimumReleaseAgeStrict

添加于：v11.0.0

默认值：如果minimumReleaseAge 被明确配置则true ，否则为 false
类型：Boolean

控制当依赖项在请求的范围内没有满足 minimumReleaseAge 约束的版本时 pnpm 的行为。当为 false 时，pnpm 会回退到不满足 minimumReleaseAge 约束的版本，以便安装仍然可以成功。当为 true 时，pnpm 解析失败。

默认值取决于你是否自行配置了 minimumReleaseAge：如果你显式地设置了它（通过 pnpm-workspace.yaml、CLI 或环境变量），则默认情况下会启用严格模式，因此该设置会被强制执行。内置默认值 minimumReleaseAge（1440 分钟）并非严格限制，而是向后兼容。

minimumReleaseAgeStrict: true

trustPolicy

添加于：v10.21.0

默认: off
类型：no-downgrade | off

当设置为 no-downgrade 时，如果软件包的信任级别与以前的版本相比有所下降，pnpm 将失败。例如，如果一个软件包之前是由受信任的发布者发布的，但现在只有来源信息而没有信任证明，则安装将会失败。这有助于防止安装可能已被入侵的版本。信任检查仅基于发布日期，而非语义版本控制。如果先前发布的版本具有更强的可信度证据，则无法安装该软件包。从 v10.24.0 开始，在评估非预发布版本安装的信任证据时，预发布版本将被忽略，因此受信任的预发布版本不能阻止缺少信任证据的稳定版本。

trustPolicyExclude

添加于: v10.22.0

默认值：[]
类型：string[]

一份应排除在信任策略检查之外的包选择器列表。这样，即使特定的软件包或版本不满足 trustPolicy 要求，你也可以安装它们。

例如：

trustPolicy: no-downgrade
trustPolicyExclude:
  - 'chokidar@4.0.3'
  - 'webpack@4.47.0 || 5.102.1'
  - '@babel/core@7.28.5'

trustPolicyIgnoreAfter

添加于：v10.27.0

默认值：undefined
类型：number (分钟)

允许忽略发布时间超过指定分钟数的软件包的信任策略检查。这在启用严格的信任策略时非常有用，因为它允许安装旧版本的软件包（可能缺少带有签名或来源的发布流程），而无需手动排除，假设它们由于年代久远而安全。

trustLockfile

添加于：v11.3.0

默认值： false
类型：Boolean

为 true 时，pnpm install 会跳过供应链验证步骤；该步骤通常会对已加载的 lockfile 中的每一项重新应用 minimumReleaseAge 和 trustPolicy 规则。安装过程将锁文件视为已受信任。

适用于锁文件实际上属于“可信基”一部分的环境——例如闭源项目，其中每一次提交都来自受信任的作者。 “受污染”的锁文件（即贡献者在比 CI 强制执行的策略更宽松的条件下生成的锁文件）可能会漏检，因此，只要外部协作者能够编辑该锁文件，就应将此项设置为 false。

在大型工作区中，验证阶段会在安装期间将各包的注册源元数据保留在内存中；禁用该阶段可降低内存占用，但会牺牲供应链检查功能。对于大多数采用默认 frozenLockfile CI 工作流的项目，无需设置此项。

blockExoticSubdeps

添加于：v10.26.0

默认值：true
类型：Boolean

设置为“true”时，只有直接依赖项（在根目录 package.json 中列出的依赖项）才能使用特殊来源（例如 git 仓库或直接 tarball URL）。所有传递依赖项都必须从受信任的来源解析，例如配置的注册表、本地文件路径、工作区链接或受信任的 GitHub 存储库（node、bun、deno）。

此设置有助于保护依赖项供应链，防止传递依赖项从不受信任的位置引入代码。

异域资源包括：

Git 仓库（git+ssh://...）
直接链接到 tar 包（https://.../package.tgz）

registries

添加于：v11.0.0

默认值：undefined
类型：** Record <string, string>**

在 pnpm-workspace.yaml 中配置作用域包的注册源。 default 键设置主注册源（相当于 .npmrc 中的 registry 设置）。作用域键为特定包作用域配置注册表。

registries:
  default: https://registry.npmjs.org/
  "@my-org": https://private.example.com/
  "@internal": https://nexus.corp.com/

Since v11.11.0, this setting may also be defined in the global configuration file (config.yaml), which is useful for registries that should apply to every project on the machine rather than to a single repository.

namedRegistries

添加于：v11.1.0

默认值：undefined
类型：** Record <string, string>**

定义命名的注册源别名，在安装包时可以用作前缀，以 vlt 的命名注册源别名的风格。例如，使用以下配置：

pnpm-workspace.yaml
namedRegistries:
  gh: https://npm.pkg.github.example.com/
  work: https://npm.work.example.com/

pnpm add work:@corp/lib@^2.0.0 将 @corp/lib@^2.0.0 解析为 https://npm.work.example.com/。

gh: 别名是内置的，默认情况下指向 GitHub Packages npm 注册源 (https://npm.pkg.github.com/)。在 GitHub Enterprise Server 的 namedRegistries 下覆盖此设置。

身份验证信息来自现有的每个 URL 的 .npmrc 条目（例如 //npm.pkg.github.com/:_authToken=...），因此不需要单独的身份验证机制。

Since v11.11.0, this setting may also be defined in the global configuration file (config.yaml), so an alias like work: can be shared across every project on the machine.

overrides​

合并覆盖​

覆盖对等依赖项​

packageExtensions​

allowedDeprecatedVersions​

update​

update.ignoreDeps​

update.changeset​

update.githubActions​

update.githubActionsServer​

支持的架构​

ignoredOptionalDependencies​

minimumReleaseAge​

minimumReleaseAgeExclude​

minimumReleaseAgeIgnoreMissingTime​

minimumReleaseAgeStrict​

trustPolicy​

trustPolicyExclude​

trustPolicyIgnoreAfter​

trustLockfile​

blockExoticSubdeps​

registries​

namedRegistries​

overrides

合并覆盖

覆盖对等依赖项

packageExtensions

allowedDeprecatedVersions

update

update.ignoreDeps

update.changeset

update.githubActions

update.githubActionsServer

支持的架构

ignoredOptionalDependencies

minimumReleaseAge

minimumReleaseAgeExclude

minimumReleaseAgeIgnoreMissingTime

minimumReleaseAgeStrict

trustPolicy

trustPolicyExclude

trustPolicyIgnoreAfter

trustLockfile

blockExoticSubdeps

registries

namedRegistries