Version: 11.x

设置 (pnpm-workspace.yaml)

pnpm 的配置来自命令行、环境变量和 pnpm-workspace.yaml。

🌐 pnpm gets its configuration from the command line, environment variables, and pnpm-workspace.yaml.

只有认证和注册表设置是从 .npmrc 文件中读取的。所有其他设置（如 hoistPattern、nodeLinker、shamefullyHoist 等）必须在 pnpm-workspace.yaml 或全局 ~/.config/pnpm/config.yaml 中配置。

🌐 Only auth and registry settings are read from .npmrc files. All other settings (like hoistPattern, nodeLinker, shamefullyHoist, etc.) must be configured in pnpm-workspace.yaml or the global ~/.config/pnpm/config.yaml.

pnpm config 命令可用于读取和编辑项目及全局配置文件的内容。

🌐 The pnpm config command can be used to read and edit the contents of the project and global configuration files.

依赖解析

🌐 Dependency Resolution

overrides

此字段允许你指示 pnpm 覆盖依赖图中的任何依赖，包括同伴依赖。这对于强制所有包使用依赖的单一版本、回移修复、用分支替换依赖或删除未使用的依赖非常有用。

🌐 This field allows you to instruct pnpm to override any dependency in the dependency graph, including peer dependencies. This is useful for enforcing all your packages to use a single version of a dependency, backporting a fix, replacing a dependency with a fork, or removing an unused dependency.

请注意，覆盖字段只能在项目的根目录中设置。

🌐 Note that the overrides field can only be set at the root of the project.

overrides 字段的一个示例：

🌐 An example of the overrides field:

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 依赖，而不会影响其他任何依赖。

🌐 You may specify the package the overridden dependency belongs to by separating the package selector from the dependency selector with a ">", for example qar@1>zoo will only override the zoo dependency of qar@1, not for any other dependencies.

为了使重写的版本与工作区其他地方使用的版本保持同步，请在catalog中定义该版本，并使用catalog:协议引用它。这样，版本就可以在一个地方维护，并从你的依赖和重写中引用：

🌐 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. This way the version is maintained in a single place and referenced from both your dependencies and your overrides:

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

overrides:
  foo: "catalog:"

你也可以使用 catalog:<name> 引用一个命名目录。有关更多详情，请参阅目录。

🌐 You may also reference a named catalog with catalog:<name>. See Catalogs for more details.

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

🌐 If you find that your use of a certain package doesn't require one of its dependencies, you may use - to remove it. For example, if package foo@1.0.0 requires a large package named bar for a function that you don't use, removing it could reduce install time:

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

这个功能在使用 optionalDependencies 时尤其有用，大多数可选软件包可以安全地跳过。

🌐 This feature is especially useful with optionalDependencies, where most optional packages can be safely skipped.

覆盖同级依赖

🌐 Overriding peer dependencies

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

🌐 Overrides also apply to peerDependencies. The behavior depends on the type of version specifier used in the override:

Semver ranges (e.g., ^1.0.0), workspace, and catalog protocols: the peer dependency is overridden and remains a peer dependency.
Non-range specifiers such as link: or file: protocols: the peer dependency is overridden and moved to dependencies, since these are not valid peer dependency ranges.
Removal (-): the peer dependency is removed entirely.

例如，要覆盖 react-dom 的 react 同行依赖：

🌐 For example, to override the react peer dependency of react-dom:

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

packageExtensions

packageExtensions 字段提供了一种使用附加信息扩展现有包定义的方法。例如，如果 react-redux 的 peerDependencies 中本应包含 react-dom，但实际上没有，可以使用 packageExtensions 修补 react-redux：

🌐 The packageExtensions fields offer a way to extend the existing package definitions with additional information. For example, if react-redux should have react-dom in its peerDependencies but it has not, it is possible to patch react-redux using packageExtensions:

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

packageExtensions 中的键是包名或包名加上语义化版本范围，因此可以只修补某些版本的包：

🌐 The keys in packageExtensions are package names or package names and semver ranges, so it is possible to patch only some versions of a package:

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

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

🌐 The following fields may be extended using packageExtensions: dependencies, optionalDependencies, peerDependencies, and peerDependenciesMeta.

一个更大的例子：

🌐 A bigger example:

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

tip

我们与 Yarn 一起维护一个 packageExtensions 数据库，用于修复生态系统中损坏的软件包。如果你使用 packageExtensions，可以考虑向上游提交 PR，并将你的扩展贡献到 @yarnpkg/extensions 数据库中。

🌐 Together with Yarn, we maintain a database of packageExtensions to patch broken packages in the ecosystem. If you use packageExtensions, consider sending a PR upstream and contributing your extension to the @yarnpkg/extensions database.

allowedDeprecatedVersions

此设置允许静音特定包的弃用警告。

🌐 This setting allows muting deprecation warnings of specific packages.

示例：

🌐 Example:

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

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

🌐 With the above configuration pnpm will not print deprecation warnings about any version of request and about v1 of express.

updateConfig

updateConfig.ignoreDependencies

有时你无法更新依赖。例如，依赖的最新版本开始使用 ESM，但你的项目还没有使用 ESM。令人恼火的是，这样的包在运行 pnpm outdated 命令时总会被列出，并且在运行 pnpm update --latest 时会被更新。然而，你可以在 ignoreDependencies 字段中列出不想升级的包：

🌐 Sometimes you can't update a dependency. For instance, the latest version of the dependency started to use ESM but your project is not yet in ESM. Annoyingly, such a package will be always printed out by the pnpm outdated command and updated, when running pnpm update --latest. However, you may list packages that you don't want to upgrade in the ignoreDependencies field:

updateConfig:
  ignoreDependencies:
  - load-json-file

模式也受支持，因此你可以忽略来自某个范围的任何包：@babel/*。

🌐 Patterns are also supported, so you may ignore any packages from a scope: @babel/*.

supportedArchitectures

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

🌐 You can specify architectures for which you'd like to install optional dependencies, even if they don't match the architecture of the system running the install.

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

🌐 For example, the following configuration tells to install optional dependencies for Windows x64:

supportedArchitectures:
  os:
  - win32
  cpu:
  - x64

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

🌐 Whereas this configuration will install optional dependencies for Windows, macOS, and the architecture of the system currently running the install. It includes artifacts for both x64 and arm64 CPUs:

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

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

🌐 Additionally, supportedArchitectures also supports specifying the libc of the system.

ignoredOptionalDependencies

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

🌐 If an optional dependency has its name included in this array, it will be skipped. For example:

ignoredOptionalDependencies:
- fsevents
- "@esbuild/*"

minimumReleaseAge

新增于：v10.16.0

🌐 Added in: v10.16.0

默认：1440（自v11起），0（v11之前）
类型：数字（分钟）

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

🌐 To reduce the risk of installing compromised packages, you can delay the installation of newly published versions. In most cases, malicious releases are discovered and removed from the registry within an hour.

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

例如，以下设置可确保仅安装至少一天前发布的包：

🌐 For example, the following setting ensures that only packages released at least one day ago can be installed:

minimumReleaseAge: 1440

minimumReleaseAgeExclude

新增于：v10.16.0

🌐 Added in: v10.16.0

默认：未定义
类型：string[]

如果你设置了 minimumReleaseAge，但需要某些依赖始终立即安装最新版本，可以将它们列在 minimumReleaseAgeExclude 下。排除是按照包名进行的，并适用于该包的所有版本。

🌐 If you set minimumReleaseAge but need certain dependencies to always install the newest version immediately, you can list them under minimumReleaseAgeExclude. The exclusion works by package name and applies to all versions of that package.

示例：

🌐 Example:

minimumReleaseAge: 1440
minimumReleaseAgeExclude:
- webpack
- react

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

🌐 In this case, all dependencies must be at least a day old, except webpack and react, which are installed immediately upon release.

新增于：v10.17.0

🌐 Added in: v10.17.0

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

🌐 You may also use patterns. For instance, allow all packages from your org:

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

新增于：v10.19.0

🌐 Added in: v10.19.0

你还可以免除特定版本（或使用 || 的析取列出特定版本）。这允许将例外固定到成熟时间规则上：

🌐 You may also exempt specific versions (or a list of specific versions using a disjunction with ||). This allows pinning exceptions to mature-time rules:

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

minimumReleaseAgeIgnoreMissingTime

新增于：v11.0.0

🌐 Added in: v11.0.0

默认：真
类型：布尔

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

🌐 When true, pnpm skips the minimumReleaseAge check for a package whose registry metadata does not include the time field (some private registries and mirrors omit it). Set to false to fail resolution in that case instead of installing the package.

minimumReleaseAgeIgnoreMissingTime: false

minimumReleaseAgeStrict

新增于：v11.0.0

🌐 Added in: v11.0.0

默认：如果显式配置了 minimumReleaseAge 则为 true，否则为 false
类型：布尔

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

🌐 Controls how pnpm behaves when no version of a dependency satisfies the minimumReleaseAge constraint within the requested range. When false, pnpm falls back to a version that doesn't meet the minimumReleaseAge constraint so installation can still succeed. When true, pnpm fails resolution instead.

默认值取决于你是否自己配置了 minimumReleaseAge：如果你显式设置了它（通过 pnpm-workspace.yaml、CLI 或环境变量），严格模式默认开启，因此该设置会被强制执行。minimumReleaseAge（1440 分钟）的内置默认值则是非严格的，以兼容旧版本。

🌐 The default depends on whether you configured minimumReleaseAge yourself: if you set it explicitly (via pnpm-workspace.yaml, the CLI, or environment variables), strict mode is on by default so the setting is enforced. The built-in default of minimumReleaseAge (1440 minutes) is non-strict for backward compatibility.

minimumReleaseAgeStrict: true

trustPolicy

新增于：v10.21.0

🌐 Added in: v10.21.0

默认：关闭
类型：不降级 | 关闭

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

🌐 When set to no-downgrade, pnpm will fail if a package's trust level has decreased compared to previous releases. For example, if a package was previously published by a trusted publisher but now only has provenance or no trust evidence, installation will fail. This helps prevent installing potentially compromised versions. Trust checks are based solely on publish date, not semver. A package cannot be installed if any earlier-published version had stronger trust evidence. Starting in v10.24.0, prerelease versions are ignored when evaluating trust evidence for a non-prerelease install, so a trusted prerelease cannot block a stable release that lacks trust evidence.

trustPolicyExclude

新增于：v10.22.0

🌐 Added in: v10.22.0

默认: []
类型：string[]

应该从信任策略检查中排除的包选择器列表。这允许你安装特定的包或版本，即使它们不满足 trustPolicy 要求。

🌐 A list of package selectors that should be excluded from the trust policy check. This allows you to install specific packages or versions even if they don't satisfy the trustPolicy requirement.

例如：

🌐 For example:

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

trustPolicyIgnoreAfter

新增于：v10.27.0

🌐 Added in: v10.27.0

默认：未定义
类型：数字（分钟）

允许忽略对指定时间之前发布的包的信任策略检查。当启用严格的信任策略时，这非常有用，因为它允许安装较旧版本的包（这些包可能没有使用签名或来源发布的流程），而无需手动排除，前提是考虑到其发布时间，它们被认为是安全的。

🌐 Allows ignoring the trust policy check for packages published more than the specified number of minutes ago. This is useful when enabling strict trust policies, as it allows older versions of packages (which may lack a process for publishing with signatures or provenance) to be installed without manual exclusion, assuming they are safe due to their age.

trustLockfile

新增于：v11.3.0

🌐 Added in: v11.3.0

默认：假
类型：布尔

当 true 时，pnpm install 会跳过供应链验证步骤，该步骤会将 minimumReleaseAge 和 trustPolicy 重新应用到加载的锁文件中的每一条目。安装过程会将锁文件视为已被信任。

🌐 When true, pnpm install skips the supply-chain verification pass that re-applies minimumReleaseAge and trustPolicy to every entry in the loaded lockfile. The install treats the lockfile as already trusted.

在锁文件实际上是受信任基础的一部分的环境中非常有用——例如每个提交都来自受信任作者的闭源项目。被污染的锁文件（即贡献者在比CI执行的策略更宽松的情况下创建的锁文件）可能会漏过检查，因此当外部合作者可以编辑锁文件时，请保留此 false。

🌐 Useful in environments where the lockfile is effectively part of the trusted base — closed-source projects where every commit comes from a trusted author. A poisoned lockfile (one a contributor authored under a weaker policy than CI enforces) can slip through, so leave this false whenever outside collaborators can edit the lockfile.

在大型工作区中，验证过程会在安装期间将每个包的注册表元数据保存在内存中；禁用它可以降低内存使用，但会牺牲供应链检查。大多数使用默认 frozenLockfile CI 工作流的项目不需要设置这个。

🌐 On large workspaces the verification pass holds per-package registry metadata in memory for the duration of the install; disabling it cuts memory usage at the cost of the supply-chain check. Most projects with the default frozenLockfile CI workflow do not need to set this.

blockExoticSubdeps

新增于：v10.26.0

🌐 Added in: v10.26.0

默认：真
类型：布尔

当设置为 true 时，只有直接依赖（即列在你根 package.json 中的依赖）可以使用特殊来源（例如 git 仓库或直接的 tarball URL）。所有传递依赖必须从可信来源解析，例如已配置的注册表、本地文件路径、工作区链接或受信任的 GitHub 仓库（node、bun、deno）。

🌐 When set to true, only direct dependencies (those listed in your root package.json) may use exotic sources (like git repositories or direct tarball URLs). All transitive dependencies must be resolved from a trusted source, such as the configured registry, local file paths, workspace links, or trusted GitHub repositories (node, bun, deno).

此设置通过阻止传递依赖从不受信任的位置拉取代码来帮助保护依赖供应链。

🌐 This setting helps secure the dependency supply chain by preventing transitive dependencies from pulling in code from untrusted locations.

特殊的来源包括：

🌐 Exotic sources include:

Git 仓库 (git+ssh://...)
指向 tar 包的直接 URL 链接 (https://.../package.tgz)

registries

新增于：v11.0.0

🌐 Added in: v11.0.0

默认：未定义
Type: Record<string, string>

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

🌐 Configure registries for scoped packages in pnpm-workspace.yaml. The default key sets the main registry (equivalent to the registry .npmrc setting). Scoped keys configure registries for specific package scopes.

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

namedRegistries

新增于：v11.1.0

🌐 Added in: v11.1.0

默认：未定义
Type: Record<string, string>

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

🌐 Defines named registry aliases that can be used as a prefix when installing packages, in the style of vlt's named-registry aliases. For example, with the following configuration:

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 下重写它。

🌐 The gh: alias is built in and points at the GitHub Packages npm registry (https://npm.pkg.github.com/) by default. Override it under namedRegistries for GitHub Enterprise Server.

身份验证是从现有的每个 URL 的 .npmrc 条目（例如 //npm.pkg.github.com/:_authToken=...）中获取的，因此不需要单独的认证机制。

🌐 Authentication is picked up from the existing per-URL .npmrc entries (e.g. //npm.pkg.github.com/:_authToken=...), so no separate auth mechanism is required.

依赖提升设置

🌐 Dependency Hoisting Settings

hoist

默认：真
类型：布尔

当 true 时，所有依赖都会提升到 node_modules/.pnpm/node_modules。这使得未列出的依赖对 node_modules 内的所有包都可访问。

🌐 When true, all dependencies are hoisted to node_modules/.pnpm/node_modules. This makes unlisted dependencies accessible to all packages inside node_modules.

hoistWorkspacePackages

默认：真
类型：布尔

当 true 时，工作区中的包会根据其他提升设置（hoistPattern 和 publicHoistPattern）被符号链接到 <workspace_root>/node_modules/.pnpm/node_modules 或 <workspace_root>/node_modules。

🌐 When true, packages from the workspaces are symlinked to either <workspace_root>/node_modules/.pnpm/node_modules or to <workspace_root>/node_modules depending on other hoisting settings (hoistPattern and publicHoistPattern).

hoistPattern

默认：['*']
类型：string[]

告诉 pnpm 哪些包应该被提升到 node_modules/.pnpm/node_modules。默认情况下，所有包都会被提升——但是，如果你知道只有一些有问题的包有虚拟依赖，你可以使用这个选项仅提升这些虚拟依赖（推荐）。

🌐 Tells pnpm which packages should be hoisted to node_modules/.pnpm/node_modules. By default, all packages are hoisted - however, if you know that only some flawed packages have phantom dependencies, you can use this option to exclusively hoist the phantom dependencies (recommended).

例如：

🌐 For instance:

hoistPattern:
- "*eslint*"
- "*babel*"

你也可以使用 ! 来排除提升的模式。

🌐 You may also exclude patterns from hoisting using !.

例如：

🌐 For instance:

hoistPattern:
- "*types*"
- "!@types/react"

publicHoistPattern

默认: []
类型：string[]

与将依赖提升到虚拟存储内隐藏模块目录的 hoistPattern 不同，publicHoistPattern 会将匹配模式的依赖提升到根模块目录。提升到根模块目录意味着即使应用代码错误地修改了解决策略，也可以访问虚拟依赖。

🌐 Unlike hoistPattern, which hoists dependencies to a hidden modules directory inside the virtual store, publicHoistPattern hoists dependencies matching the pattern to the root modules directory. Hoisting to the root modules directory means that application code will have access to phantom dependencies, even if they modify the resolution strategy improperly.

当处理一些无法正确解析依赖的有缺陷的插件化工具时，此设置非常有用。

🌐 This setting is useful when dealing with some flawed pluggable tools that don't resolve dependencies properly.

例如：

🌐 For instance:

publicHoistPattern:
- "*plugin*"

注意：将 shamefullyHoist 设置为 true 与将 publicHoistPattern 设置为 * 是相同的。

🌐 Note: Setting shamefullyHoist to true is the same as setting publicHoistPattern to *.

你也可以使用 ! 来排除提升的模式。

🌐 You may also exclude patterns from hoisting using !.

例如：

🌐 For instance:

publicHoistPattern:
- "*types*"
- "!@types/react"

shamefullyHoist

默认：假
类型：布尔

默认情况下，pnpm 会创建一个半严格的 node_modules，意味着依赖可以访问未声明的依赖，但 node_modules 之外的模块则不能访问。使用这种布局时，生态系统中的大多数包都能正常工作。然而，如果某些工具只有在提升的依赖在 node_modules 根目录时才能工作，你可以将其设置为 true 来为你提升它们。

🌐 By default, pnpm creates a semistrict node_modules, meaning dependencies have access to undeclared dependencies but modules outside of node_modules do not. With this layout, most of the packages in the ecosystem work with no issues. However, if some tooling only works when the hoisted dependencies are in the root of node_modules, you can set this to true to hoist them for you.

hoistingLimits

新增于：v11.5.0

🌐 Added in: v11.5.0

默认：无
类型：无、工作区、依赖

控制在使用 nodeLinker: hoisted 时依赖提升的程度。此设置与 Yarn 的 nmHoistingLimits 相对应。

🌐 Controls how far dependencies are hoisted when using nodeLinker: hoisted. This setting mirrors Yarn's nmHoistingLimits.

无 - 尽可能升起（默认）。
工作区 - 仅提升到每个工作区包的范围，防止依赖被提升到依赖它们的工作区包之上。
dependencies - 仅提升到每个工作区包的直接依赖，防止传递依赖被提升到工作区包的 node_modules 中。

Node 模块设置

🌐 Node-Modules Settings

modulesDir

默认: node_modules
类型：路径

将安装依赖的目录（而不是 node_modules）。

🌐 The directory in which dependencies will be installed (instead of node_modules).

nodeLinker

默认：隔离
类型：独立、提升、PNP

定义应使用什么链接器来安装 Node 包。

🌐 Defines what linker should be used for installing Node packages.

隔离 - 依赖从 node_modules/.pnpm 的虚拟存储中以符号链接方式引用。
提升 - 创建一个没有符号链接的平铺 node_modules。与 npm 或 Yarn Classic 创建的 node_modules 相同。当使用此设置时，Yarn 的一个库会被用于提升。使用此设置的合理原因包括：
1. 你的工具链不太适合符号链接。React Native 项目很可能只有在使用提升的 node_modules 时才能工作。
2. 你的项目已部署到无服务器托管提供商。一些无服务器提供商（例如，AWS Lambda）不支持符号链接。解决此问题的另一种方法是在部署之前打包你的应用。
3. 如果你想使用 "bundledDependencies" 发布你的包。
4. 如果你使用 --preserve-symlinks 标志运行 Node.js。
pnp - 没有 node_modules。Plug'n'Play 是 Node 的一种创新策略，它是由 Yarn Berry 使用。建议在使用 pnp 作为链接器时，也将 symlink 设置为 false。

nodeExperimentalPackageMap

新增于：v11.8.0

🌐 Added in: v11.8.0

默认：假
类型：布尔

当 true 时，pnpm 通过将 Node 的 --experimental-package-map 选项添加到 NODE_OPTIONS，将生成的 node_modules/.package-map.json 注入到 pnpm 管理的 Node.js 脚本环境中。

🌐 When true, pnpm injects the generated node_modules/.package-map.json into pnpm-managed Node.js script environments by adding Node's --experimental-package-map option to NODE_OPTIONS.

包映射在隔离安装和提升安装期间生成。此设置仅控制 pnpm 是否将生成的映射传递给脚本。

🌐 The package map is generated during isolated and hoisted installs. This setting only controls whether pnpm passes the generated map to scripts.

CLI 和环境配置使用短横线命名法 node-experimental-package-map。

🌐 CLI and environment configuration use the kebab-case name node-experimental-package-map.

nodeExperimentalPackageMap: true

nodePackageMapType

新增于：v11.8.0

🌐 Added in: v11.8.0

默认：标准
类型：标准、宽松

控制 node_modules/.package-map.json 的生成方式。

🌐 Controls how node_modules/.package-map.json is generated.

标准 - 只有声明的依赖可以通过包映射获得。
loose - 还映射通过已安装的 node_modules 布局可访问的包，这可以允许未声明的提升依赖得以解析。

CLI 和环境配置使用短横线命名法 node-package-map-type。

🌐 CLI and environment configuration use the kebab-case name node-package-map-type.

nodePackageMapType: loose

symlink

默认：真
类型：布尔

当 symlink 设置为 false 时，pnpm 会创建一个没有任何符号链接的虚拟存储目录。这个设置与 nodeLinker=pnp 一起使用非常有用。

🌐 When symlink is set to false, pnpm creates a virtual store directory without any symlinks. It is a useful setting together with nodeLinker=pnp.

enableModulesDir

默认：真
类型：布尔

当 false 时，pnpm 不会向模块目录 (node_modules) 写入任何文件。这在模块目录使用用户空间文件系统 (FUSE) 挂载时非常有用。有一个实验性的 CLI 允许你使用 FUSE 挂载模块目录：@pnpm/mount-modules。

🌐 When false, pnpm will not write any files to the modules directory (node_modules). This is useful for when the modules directory is mounted with filesystem in userspace (FUSE). There is an experimental CLI that allows you to mount a modules directory with FUSE: @pnpm/mount-modules.

virtualStoreDir

默认: node_modules/.pnpm
类型：路径

包含指向存储链接的目录。项目的所有直接和间接依赖都链接到此目录中。

🌐 The directory with links to the store. All direct and indirect dependencies of the project are linked into this directory.

这是一个有用的设置，可以解决 Windows 上的长路径问题。如果你有一些路径非常长的依赖，你可以在驱动器的根目录中选择一个虚拟存储（例如 C:\my-project-store）。

🌐 This is a useful setting that can solve issues with long paths on Windows. If you have some dependencies with very long paths, you can select a virtual store in the root of your drive (for instance C:\my-project-store).

或者你可以将虚拟存储设置为 .pnpm 并将其添加到 .gitignore。这样可以让堆栈跟踪更清晰，因为依赖路径会在上一级目录。

🌐 Or you can set the virtual store to .pnpm and add it to .gitignore. This will make stacktraces cleaner as paths to dependencies will be one directory higher.

**注意：**虚拟存储不能在多个项目之间共享。每个项目都应该有自己的虚拟存储（工作区中根目录共享的情况除外）。

virtualStoreDirMaxLength

默认：
- 在 Linux/macOS 上：120
- 在 Windows 上：60
类型：数字

设置虚拟存储目录（node_modules/.pnpm）内目录名称的最大允许长度。如果在 Windows 上遇到路径过长的问题，可以将其设置为较小的数值。

🌐 Sets the maximum allowed length of directory names inside the virtual store directory (node_modules/.pnpm). You may set this to a lower number if you encounter long path issues on Windows.

virtualStoreOnly

新增于：v11.0.0

🌐 Added in: v11.0.0

默认：假
类型：布尔

当设置为 true 时，pnpm 会填充虚拟存储，而不创建导入器符号链接、提升、bin 链接或运行生命周期脚本。这在预填充存储（例如，在 Nix 构建中）而不创建不必要的项目级工件时非常有用。pnpm fetch 在内部使用此模式。

🌐 When set to true, pnpm populates the virtual store without creating importer symlinks, hoisting, bin links, or running lifecycle scripts. This is useful for pre-populating a store (e.g., in Nix builds) without creating unnecessary project-level artifacts. pnpm fetch uses this mode internally.

packageImportMethod

默认：自动
类型：自动、硬链接、复制、克隆、克隆或复制

控制从存储导入包的方式（如果你想禁用 node_modules 内的符号链接，则需要更改 nodeLinker 设置，而不是这个设置）。

🌐 Controls the way packages are imported from the store (if you want to disable symlinks inside node_modules, then you need to change the nodeLinker setting, not this one).

自动 - 尝试从存储中克隆软件包。如果不支持克隆，则从存储中创建软件包的硬链接。如果克隆和链接都不可能，则退回到复制
hardlink - 从存储生成硬连接的包
克隆或复制 - 尝试从存储克隆包。如果不支持克隆，则改为复制
复制 - 从存储复制包
克隆 - 从存储克隆（又称写时复制或引用链接）软件包

克隆是向 node_modules 写入包的最佳方式。它是最快且最安全的方式。当使用克隆时，你可以编辑 node_modules 中的文件，这些修改不会影响中央的内容可寻址存储。

🌐 Cloning is the best way to write packages to node_modules. It is the fastest way and safest way. When cloning is used, you may edit files in your node_modules and they will not be modified in the central content-addressable store.

不幸的是，并非所有文件系统都支持克隆。我们建议使用写时复制（CoW）文件系统（例如在 Linux 上使用 Btrfs 而不是 Ext4），以获得最佳的 pnpm 使用体验。

🌐 Unfortunately, not all file systems support cloning. We recommend using a copy-on-write (CoW) file system (for instance, Btrfs instead of Ext4 on Linux) for the best experience with pnpm.

modulesCacheMaxAge

默认值：10080（7天，单位为分钟）
类型：数字

在模块目录中孤立包应被移除的分钟数。pnpm 会在模块目录中保留包的缓存。这在切换分支或降级依赖时可以提升安装速度。

🌐 The time in minutes after which orphan packages from the modules directory should be removed. pnpm keeps a cache of packages in the modules directory. This boosts installation speed when switching branches or downgrading dependencies.

dlxCacheMaxAge

默认值：1440（1天的分钟数）
类型：数字

dlx 缓存过期的分钟数。在执行 dlx 命令后，pnpm 会保留一个缓存，对于后续对同一 dlx 命令的调用，会跳过安装步骤。

🌐 The time in minutes after which dlx cache expires. After executing a dlx command, pnpm keeps a cache that omits the installation step for subsequent calls to the same dlx command.

enableGlobalVirtualStore

新增于：v10.12.1

🌐 Added in: v10.12.1

默认：假
类型：布尔

note

在 pnpm v11 中，全局安装（pnpm add -g）和 pnpm dlx 默认使用全局虚拟存储。

🌐 In pnpm v11, global installs (pnpm add -g) and pnpm dlx use the global virtual store by default.

启用后，node_modules 仅包含指向中央虚拟存储的符号链接，而不是指向 node_modules/.pnpm 的链接。默认情况下，该中央存储位于 <store-path>/links（使用 pnpm store path 查找 <store-path>）。

🌐 When enabled, node_modules contains only symlinks to a central virtual store, rather than to node_modules/.pnpm. By default, this central store is located at <store-path>/links (use pnpm store path to find <store-path>).

在中央虚拟存储中，每个软件包都会被硬链接到一个目录中，该目录的名称是其依赖图的哈希值。因此，系统上的所有项目都可以从磁盘上的这个共享位置为它们的依赖创建符号链接。这种方法在概念上类似于 [NixOS 管理软件包] 的方式，使用依赖图哈希来创建隔离且可共享的 Nix 存储软件包目录。

🌐 In the central virtual store, each package is hard linked into a directory whose name is the hash of its dependency graph. As a result, all projects on the system can symlink their dependencies from this shared location on disk. This approach is conceptually similar to how NixOS manages packages, using dependency graph hashes to create isolated and shareable package directories in the Nix store.

这不应与全局内容可寻址存储混淆。实际的包文件仍然是从内容可寻址存储中进行硬链接的——但它们不是直接链接到 node_modules/.pnpm，而是链接到全局虚拟存储中。

当有热缓存可用时，使用全局虚拟存储可以显著加快安装速度。然而，在持续集成（CI）环境中（通常没有缓存），它可能会减慢安装速度。如果 pnpm 检测到自己在 CI 环境中运行，此设置会自动被禁用。

🌐 Using a global virtual store can significantly speed up installations when a warm cache is available. However, in CI environments (where caches are typically absent), it may slow down installation. If pnpm detects that it is running in CI, this setting is automatically disabled.

important

在使用全局虚拟存储支持提升的依赖时，pnpm 依赖于 NODE_PATH 环境变量。这允许 Node.js 从提升的 node_modules 目录解析包。然而，这个解决方法在 ESM 模块中不起作用，因为在使用 ESM 时，Node.js 不再遵循 NODE_PATH。

🌐 To support hoisted dependencies when using a global virtual store, pnpm relies on the NODE_PATH environment variable. This allows Node.js to resolve packages from the hoisted node_modules directory. However, this workaround does not work with ESM modules, because Node.js no longer respects NODE_PATH when using ESM.

如果你的依赖是 ESM 并且它们导入了 未在自身 package.json 中声明的 包（这被认为是不好的做法），你很可能会遇到解析错误。有两种方法可以解决这个问题：

🌐 If your dependencies are ESM and they import packages not declared in their own package.json (which is considered bad practice), you’ll likely run into resolution errors. There are two ways to fix this:

使用 packageExtensions 明确添加缺失的依赖。
将 @pnpm/plugin-esm-node-path 配置依赖添加到你的项目中。该插件注册了一个自定义的 ESM 加载器，从而恢复 ESM 对 NODE_PATH 的支持，使提升的依赖能够被正确解析。

存储设置

🌐 Store Settings

storeDir

默认：
- 如果设置了 $PNPM_HOME 环境变量，那么 $PNPM_HOME/store
- 如果设置了 $XDG_DATA_HOME 环境变量，那么路径就是 $XDG_DATA_HOME/pnpm/store
- 在 Windows 上：~/AppData/Local/pnpm/store
- 在 macOS 上：~/Library/pnpm/store
- 在 Linux 上：~/.local/share/pnpm/store
类型：路径

所有包在磁盘上的保存位置。

🌐 The location where all the packages are saved on the disk.

存储应该始终位于安装进行的同一磁盘上，因此每个磁盘上只会有一个存储。如果当前磁盘上有主目录，则存储会创建在其中。如果磁盘上没有主目录，则存储会创建在文件系统的根目录下。例如，如果安装发生在挂载在 /mnt 的文件系统上，那么存储将创建在 /mnt/.pnpm-store。Windows 系统也是如此。

🌐 The store should be always on the same disk on which installation is happening, so there will be one store per disk. If there is a home directory on the current disk, then the store is created inside it. If there is no home on the disk, then the store is created at the root of the filesystem. For example, if installation is happening on a filesystem mounted at /mnt, then the store will be created at /mnt/.pnpm-store. The same goes for Windows systems.

可以将存储设置到不同的磁盘，但在这种情况下，pnpm 会从存储中复制包，而不是使用硬链接，因为硬链接仅在同一文件系统上可用。

🌐 It is possible to set a store from a different disk but in that case pnpm will copy packages from the store instead of hard-linking them, as hard links are only possible on the same filesystem.

important

pnpm 存储仅供相互信任的用户、作业和进程共享。如果你配置了共享的 storeDir，请使用文件系统权限保护它，以防不受信任的用户写入。存储是 pnpm 的信任域的一部分：包可能会从中创建硬链接，存储索引（index.db）记录用于验证缓存文件的哈希值。

🌐 The pnpm store is intended to be shared only between mutually trusted users, jobs, and processes. If you configure a shared storeDir, protect it with filesystem permissions so untrusted users cannot write to it. The store is part of pnpm's trust domain: packages may be hard linked from it, and the store index (index.db) records the hashes used to verify cached files.

verifyStoreIntegrity

默认：真
类型：布尔

默认情况下，如果存储中的文件已被修改，会在将其链接到项目的 node_modules 之前检查该文件的内容。如果 verifyStoreIntegrity 设置为 false，在安装过程中将不会检查内容寻址存储中的文件。

🌐 By default, if a file in the store has been modified, the content of this file is checked before linking it to a project's node_modules. If verifyStoreIntegrity is set to false, files in the content-addressable store will not be checked during installation.

此设置有助于检测意外的存储损坏。它并不能使不受信任用户可写的存储变得安全，因为能够写入存储的攻击者可以更改缓存的包内容以及用于验证它们的元数据。

🌐 This setting helps detect accidental store corruption. It does not make a store that is writable by untrusted users safe, because an attacker who can write to the store can alter both cached package contents and the metadata used to verify them.

useRunningStoreServer

danger

已弃用的功能

🌐 Deprecated feature

默认：假
类型：布尔

仅允许通过存储服务器安装。如果没有正在运行的存储服务器，安装将失败。

🌐 Only allows installation with a store server. If no store server is running, installation will fail.

strictStorePkgContentCheck

默认：真
类型：布尔

有些注册表允许相同的内容以不同的包名和/或版本发布。这会破坏存储中包的有效性检查。为了在验证存储中此类包的名称和版本时避免错误，你可以将 strictStorePkgContentCheck 设置为 false。

🌐 Some registries allow the exact same content to be published under different package names and/or versions. This breaks the validity checks of packages in the store. To avoid errors when verifying the names and versions of such packages in the store, you may set the strictStorePkgContentCheck setting to false.

frozenStore

新增于：v11.7.0

🌐 Added in: v11.7.0

默认：假
类型：布尔

让 pnpm install 在只读文件系统上的软件包存储中运行——例如 Nix 存储、只读绑定挂载或 OCI 镜像层。启用后，pnpm 会以不可变模式打开存储的 SQLite index.db（绕过在只读目录上无法创建的 WAL/-shm 附属文件），并抑制所有会写入存储的代码路径。

🌐 Lets pnpm install run against a package store that lives on a read-only filesystem — for example a Nix store, a read-only bind mount, or an OCI image layer. When enabled, pnpm opens the store's SQLite index.db in immutable mode (bypassing the WAL/-shm sidecar files that otherwise can't be created on a read-only directory) and suppresses every code path that would write to the store.

将其与 --offline 和 --frozen-lockfile 配对，以应对一个库存充足的商店：

🌐 Pair it with --offline and --frozen-lockfile against a fully-populated store:

pnpm install --frozen-store --offline --frozen-lockfile

商店必须已经包含安装所需的一切内容，包括任何生命周期脚本被批准（或已应用补丁）的软件包的构建输出。在全局虚拟商店下，这些软件包目录位于商店内部，因此如果缺少所需的构建，安装会立即因 ERR_PNPM_FROZEN_STORE_NEEDS_BUILD 失败——请先用这些构建填充商店。如果商店完全缺少其内容目录，安装会快速因 ERR_PNPM_FROZEN_STORE_INCOMPLETE 失败，而不会尝试初始化它。

🌐 The store must already contain everything the install needs, including the build output of any package whose lifecycle scripts are approved (or that has a patch applied). Under the global virtual store, those package directories live inside the store, so if a required build is missing the install fails up front with ERR_PNPM_FROZEN_STORE_NEEDS_BUILD — seed the store with those builds first. If the store is missing its content directory entirely, the install fails fast with ERR_PNPM_FROZEN_STORE_INCOMPLETE rather than trying to initialize it.

frozenStore 与 --force 以及配置的 pnpr 服务器不兼容，因为它们都会写入存储。副作用缓存也不会被写入。

note

只读存储打开需要 Node.js >=22.15.0、>=23.11.0 或 >=24.0.0。在较旧的运行时中，--frozen-store 会导致 ERR_PNPM_FROZEN_STORE_UNSUPPORTED_NODE 失败。

🌐 The read-only store open requires Node.js >=22.15.0, >=23.11.0, or >=24.0.0. On older runtimes, --frozen-store fails with ERR_PNPM_FROZEN_STORE_UNSUPPORTED_NODE.

网络设置

🌐 Network Settings

httpsProxy

默认：空
类型：网址

用于传出 HTTPS 请求的代理。如果设置了 HTTPS_PROXY、https_proxy、HTTP_PROXY 或 http_proxy 环境变量，将使用它们的值。

🌐 A proxy to use for outgoing HTTPS requests. If the HTTPS_PROXY, https_proxy, HTTP_PROXY or http_proxy environment variables are set, their values will be used instead.

如果你的代理URL包含用户名和密码，务必对它们进行网址编码。例如：

🌐 If your proxy URL contains a username and password, make sure to URL-encode them. For instance:

httpsProxy: "https://use%21r:pas%2As@my.proxy:1234/foo"

不要对用户名和密码之间的冒号（:）进行编码。

🌐 Do not encode the colon (:) between the username and password.

httpProxy

默认：空
类型：网址

用于外发 HTTP 请求的代理。如果设置了 HTTP_PROXY 或 http_proxy 环境变量，请求库将遵循这些代理设置。

🌐 A proxy to use for outgoing HTTP requests. If the HTTP_PROXY or http_proxy environment variables are set, proxy settings will be honored by the underlying request library.

noProxy

默认：空
类型：字符串

不应使用代理的以逗号分隔的域扩展字符串。

🌐 A comma-separated string of domain extensions that a proxy should not be used for.

localAddress

默认：未定义
类型：IP地址

在连接到 npm 注册表时要使用的本地接口的 IP 地址。

🌐 The IP address of the local interface to use when making connections to the npm registry.

maxsockets

默认值：networkConcurrency x 3
类型：数字

每个源使用的最大连接数（协议/主机/端口组合）。

🌐 The maximum number of connections to use per origin (protocol/host/port combination).

strictSsl

默认：真
类型：布尔

在通过 HTTPS 向注册表发出请求时是否进行 SSL 密钥验证。

🌐 Whether or not to do SSL key validation when making requests to the registry via HTTPS.

锁定文件设置

🌐 Lockfile Settings

lockfile

默认：真
类型：布尔

当设置为 false 时，pnpm 不会读取或生成 pnpm-lock.yaml 文件。

🌐 When set to false, pnpm won't read or generate a pnpm-lock.yaml file.

preferFrozenLockfile

默认：真
类型：布尔

当设置为 true 且可用的 pnpm-lock.yaml 满足 package.json 依赖指令时，会执行无头安装。无头安装会跳过所有依赖解析，因为它不需要修改锁文件。

🌐 When set to true and the available pnpm-lock.yaml satisfies the package.json dependencies directive, a headless installation is performed. A headless installation skips all dependency resolution as it does not need to modify the lockfile.

lockfileIncludeTarballUrl

默认：假
类型：布尔

将软件包 tarball 的完整 URL 添加到 pnpm-lock.yaml 中的每个条目。

🌐 Add the full URL to the package's tarball to every entry in pnpm-lock.yaml.

gitBranchLockfile

默认：假
类型：布尔

当设置为 true 时，安装后生成的锁文件名称将基于当前分支名称命名，以完全避免合并冲突。例如，如果当前分支名称为 feature-foo，则对应的锁文件名称将是 pnpm-lock.feature-foo.yaml，而不是 pnpm-lock.yaml。它通常与命令行参数 --merge-git-branch-lockfiles 一起使用，或通过在 pnpm-workspace.yaml 文件中设置 mergeGitBranchLockfilesBranchPattern 来使用。

🌐 When set to true, the generated lockfile name after installation will be named based on the current branch name to completely avoid merge conflicts. For example, if the current branch name is feature-foo, the corresponding lockfile name will be pnpm-lock.feature-foo.yaml instead of pnpm-lock.yaml. It is typically used in conjunction with the command line argument --merge-git-branch-lockfiles or by setting mergeGitBranchLockfilesBranchPattern in the pnpm-workspace.yaml file.

mergeGitBranchLockfilesBranchPattern

默认：空
类型：数组或空

此配置会匹配当前分支名称，以确定是否合并所有 git 分支锁定文件。默认情况下，你需要手动传递 --merge-git-branch-lockfiles 命令行参数。使用此配置可以自动补齐此过程。

🌐 This configuration matches the current branch name to determine whether to merge all git branch lockfile files. By default, you need to manually pass the --merge-git-branch-lockfiles command line parameter. This configuration allows this process to be automatically completed.

例如：

🌐 For instance:

mergeGitBranchLockfilesBranchPattern:
- main
- release*

你也可以使用 ! 排除模式。

🌐 You may also exclude patterns using !.

peersSuffixMaxLength

默认值：1000
类型：数字

锁文件中添加到依赖键的对等 ID 后缀的最大长度。如果后缀太长，它将被替换为哈希值。

🌐 Max length of the peer IDs suffix added to dependency keys in the lockfile. If the suffix is longer, it is replaced with a hash.

请求设置

🌐 Request Settings

gitShallowHosts

默认：['github.com', 'gist.github.com', 'gitlab.com', 'bitbucket.com', 'bitbucket.org']
类型：string[]

当获取 Git 存储库的依赖时，如果主机在此设置中列出，pnpm 将使用浅克隆仅获取所需的提交，而不是所有历史记录。

🌐 When fetching dependencies that are Git repositories, if the host is listed in this setting, pnpm will use shallow cloning to fetch only the needed commit, not all the history.

networkConcurrency

默认：自动（工作线程 × 3，限制在 16-64 之间）
类型：数字

控制同时处理的 HTTP(S) 请求的最大数量。

🌐 Controls the maximum number of HTTP(S) requests to process simultaneously.

从 v10.24.0 开始，pnpm 会根据工作线程数量自动选择 16 到 64 之间的值（networkConcurrency = clamp(workers × 3, 16, 64)）。可以显式设置此值以覆盖自动缩放。

🌐 As of v10.24.0, pnpm automatically selects a value between 16 and 64 based on the number of workers (networkConcurrency = clamp(workers × 3, 16, 64)). Set this value explicitly to override the automatic scaling.

fetchRetries

默认：2
类型：数字

如果 pnpm 无法从注册表获取，则重试多少次。

🌐 How many times to retry if pnpm fails to fetch from the registry.

fetchRetryFactor

默认：10
类型：数字

重试退避的指数因子。

🌐 The exponential factor for retry backoff.

fetchRetryMintimeout

默认值：10000（10秒）
类型：数字

重试指数退避的下限（以毫秒为单位）。

🌐 The lower bound (in milliseconds) of the retry exponential backoff.

fetchRetryMaxtimeout

默认值：60000（1分钟）
类型：数字

重试指数退避的上限（以毫秒为单位）。

🌐 The upper bound (in milliseconds) of the retry exponential backoff.

fetchTimeout

默认值：60000（1分钟）
类型：数字

等待 HTTP 请求连接和完成的最长时间。这个时间应该足够通过合理的连接下载最大的软件包。

🌐 The maximum amount of time to wait for HTTP requests to connect and complete. This time should be enough to download the largest package over a reasonable connection.

fetchWarnTimeoutMs

新增于：v10.18.0

🌐 Added in: v10.18.0

默认：10000 毫秒（10 秒）
类型：数字

如果向注册表发送元数据请求所用时间超过指定阈值（以毫秒为单位），则会显示警告消息。

🌐 A warning message is displayed if a metadata request to the registry takes longer than the specified threshold (in milliseconds).

fetchMinSpeedKiBps

新增于：v10.18.0

🌐 Added in: v10.18.0

默认：50 KiB/s
类型：数字

如果从注册表下载 tarball 的速度低于指定阈值（以 KiB/s 为单位），则会显示警告消息。

🌐 A warning message is displayed if the download speed of a tarball from the registry falls below the specified threshold (in KiB/s).

对等依赖设置

🌐 Peer Dependency Settings

autoInstallPeers

默认：真
类型：布尔

当 true 时，任何缺失的非可选同伴依赖会被自动安装。

🌐 When true, any missing non-optional peer dependencies are automatically installed.

版本冲突

🌐 Version Conflicts

如果来自不同包的同级依赖存在版本冲突要求，pnpm 不会自动安装任何版本的冲突同级依赖。相反，会打印一条警告。例如，如果一个依赖需要 react@^16.0.0，而另一个依赖需要 react@^17.0.0，这些要求就会发生冲突，并且不会自动安装。

🌐 If there are conflicting version requirements for a peer dependency from different packages, pnpm will not install any version of the conflicting peer dependency automatically. Instead, a warning is printed. For example, if one dependency requires react@^16.0.0 and another requires react@^17.0.0, these requirements conflict, and no automatic installation will occur.

解决冲突

🌐 Conflict Resolution

如果出现版本冲突，你需要评估自己安装哪个版本的对等依赖，或更新依赖以符合其对等依赖要求。

🌐 In case of a version conflict, you'll need to evaluate which version of the peer dependency to install yourself, or update the dependencies to align their peer dependency requirements.

dedupePeerDependents

默认：真
类型：布尔

当此设置为 true 时，带有对等依赖的包将在对等依赖解析后进行去重。

🌐 When this setting is set to true, packages with peer dependencies will be deduplicated after peers resolution.

例如，假设我们有一个包含两个项目的工作区，并且它们的依赖中都包含 webpack。webpack 的可选同伴依赖中包含 esbuild，并且其中一个项目的依赖中包含 esbuild。在这种情况下，pnpm 会将两个 webpack 的实例链接到 node_modules/.pnpm 目录：一个包含 esbuild，另一个不包含:

🌐 For instance, let's say we have a workspace with two projects and both of them have webpack in their dependencies. webpack has esbuild in its optional peer dependencies, and one of the projects has esbuild in its dependencies. In this case, pnpm will link two instances of webpack to the node_modules/.pnpm directory: one with esbuild and another one without it:

node_modules
  .pnpm
    webpack@1.0.0_esbuild@1.0.0
    webpack@1.0.0
project1
  node_modules
    webpack -> ../../node_modules/.pnpm/webpack@1.0.0/node_modules/webpack
project2
  node_modules
    webpack -> ../../node_modules/.pnpm/webpack@1.0.0_esbuild@1.0.0/node_modules/webpack
    esbuild

这是有道理的，因为 webpack 在两个项目中都被使用，其中一个项目没有 esbuild，所以两个项目无法共享同一个 webpack 实例。然而，这并不是大多数开发者所期望的，尤其是在提升了的 node_modules 中，本应只有一个 webpack 实例。因此，你现在可以使用 dedupePeerDependents 设置来对 webpack 进行去重，只要它没有冲突的同级依赖（解释在末尾）。在这种情况下，如果我们将 dedupePeerDependents 设置为 true，两个项目将使用同一个 webpack 实例，也就是已经解析了 esbuild 的那个实例：

🌐 This makes sense because webpack is used in two projects, and one of the projects doesn't have esbuild, so the two projects cannot share the same instance of webpack. However, this is not what most developers expect, especially since in a hoisted node_modules, there would only be one instance of webpack. Therefore, you may now use the dedupePeerDependents setting to deduplicate webpack when it has no conflicting peer dependencies (explanation at the end). In this case, if we set dedupePeerDependents to true, both projects will use the same webpack instance, which is the one that has esbuild resolved:

node_modules
  .pnpm
    webpack@1.0.0_esbuild@1.0.0
project1
  node_modules
    webpack -> ../../node_modules/.pnpm/webpack@1.0.0_esbuild@1.0.0/node_modules/webpack
project2
  node_modules
    webpack -> ../../node_modules/.pnpm/webpack@1.0.0_esbuild@1.0.0/node_modules/webpack
    esbuild

什么是冲突的 Peer 依赖？ 所谓冲突的 Peer 依赖，是指如下情况：

node_modules
  .pnpm
    webpack@1.0.0_react@16.0.0_esbuild@1.0.0
    webpack@1.0.0_react@17.0.0
project1
  node_modules
    webpack -> ../../node_modules/.pnpm/webpack@1.0.0/node_modules/webpack
    react (v17)
project2
  node_modules
    webpack -> ../../node_modules/.pnpm/webpack@1.0.0_esbuild@1.0.0/node_modules/webpack
    esbuild
    react (v16)

在这种情况下，我们无法将 webpack 去重，因为 webpack 的对等依赖中包含 react，并且在两个项目的上下文中，react 是从两个不同版本解析的。

🌐 In this case, we cannot dedupe webpack as webpack has react in its peer dependencies and react is resolved from two different versions in the context of the two projects.

dedupePeers

新增于：v10.33.0

🌐 Added in: v10.33.0

默认：假
类型：布尔

启用后，对等依赖后缀将使用仅版本标识符（name@version）而不是完整的依赖路径，从而消除像 (foo@1.0.0(bar@2.0.0)) 这样的嵌套后缀。这极大地减少了在拥有许多递归对等依赖的项目中包实例的数量。

🌐 When enabled, peer dependency suffixes use version-only identifiers (name@version) instead of full dep paths, eliminating nested suffixes like (foo@1.0.0(bar@2.0.0)). This dramatically reduces the number of package instances in projects with many recursive peer dependencies.

这与dedupePeerDependents不同，后者会去重在不同工作区项目中具有相同 peer 依赖的包。dedupePeers 则简化了 peer 依赖后缀格式本身。

🌐 This is different from dedupePeerDependents, which deduplicates packages that have the same peer dependencies across different workspace projects. dedupePeers simplifies the peer dependency suffix format itself.

strictPeerDependencies

默认：假
类型：布尔

如果启用此选项，当依赖树中存在缺失或无效的对等依赖时，命令将会失败。

🌐 If this is enabled, commands will fail if there is a missing or invalid peer dependency in the tree.

resolvePeersFromWorkspaceRoot

默认：真
类型：布尔

启用后，根工作区项目的依赖将用于解析工作区中任何项目的对等依赖。这是一个有用的功能，因为你可以仅在工作区根目录中安装对等依赖，并且可以确保工作区中的所有项目使用相同版本的对等依赖。

🌐 When enabled, dependencies of the root workspace project are used to resolve peer dependencies of any projects in the workspace. It is a useful feature as you can install your peer dependencies only in the root of the workspace, and you can be sure that all projects in the workspace use the same versions of the peer dependencies.

peerDependencyRules

peerDependencyRules.ignoreMissing

pnpm 不会打印有关此列表中缺少对等依赖的警告。

🌐 pnpm will not print warnings about missing peer dependencies from this list.

例如，使用以下配置时，如果某个依赖需要 react 但未安装 react，pnpm 将不会打印警告：

🌐 For instance, with the following configuration, pnpm will not print warnings if a dependency needs react but react is not installed:

peerDependencyRules:
  ignoreMissing:
  - react

还可以使用包名称模式：

🌐 Package name patterns may also be used:

peerDependencyRules:
  ignoreMissing:
  - "@babel/*"
  - "@eslint/*"

peerDependencyRules.allowedVersions

对于指定范围的对等依赖，不会打印未满足的对等依赖警告。

🌐 Unmet peer dependency warnings will not be printed for peer dependencies of the specified range.

例如，如果你有一些依赖需要 react@16，但你知道它们在 react@17 上也能正常工作，那么你可以使用以下配置：

🌐 For instance, if you have some dependencies that need react@16 but you know that they work fine with react@17, then you may use the following configuration:

peerDependencyRules:
  allowedVersions:
    react: "17"

这将告诉 pnpm，任何在其 peer 依赖中包含 react 的依赖都应该允许安装 react v17。

🌐 This will tell pnpm that any dependency that has react in its peer dependencies should allow react v17 to be installed.

也可以仅针对特定包的同级依赖抑制警告。例如，通过以下配置，只有当 react v17 出现在 button v2 包的同级依赖中或出现在任何 card 包的依赖中时，才允许使用它:

🌐 It is also possible to suppress the warnings only for peer dependencies of specific packages. For instance, with the following configuration react v17 will be only allowed when it is in the peer dependencies of the button v2 package or in the dependencies of any card package:

peerDependencyRules:
  allowedVersions:
    "button@2>react": "17",
    "card>react": "17"

peerDependencyRules.allowAny

allowAny 是一个包名模式数组，任何与该模式匹配的 peer 依赖都将从任何版本解析，而不管 peerDependencies 中指定的版本范围。例如：

peerDependencyRules:
  allowAny:
  - "@babel/*"
  - "eslint"

上述设置将静音与 @babel/ 或 eslint 包相关的任何关于同伴依赖版本不匹配的警告。

🌐 The above setting will mute any warnings about peer dependency version mismatches related to @babel/ packages or eslint.

CLI 设置

🌐 CLI Settings

[no-]color

默认：自动
类型：自动、总是、从不

控制输出中的颜色。

🌐 Controls colors in the output.

auto - 当标准输出是终端或TTY时，输出使用颜色。
always - 忽略终端和管道之间的差异。你很少会需要这个；在大多数情况下，如果你希望在重定向输出中使用颜色代码，你可以向 pnpm 命令传递 --color 标志来强制使用颜色代码。默认设置几乎总是你想要的。
never - 关闭颜色。这是 --no-color 使用的设置。

loglevel

默认：信息
类型：调试、信息、警告、错误

任何等于或高于指定级别的日志都会显示。你也可以传入 --silent 来关闭所有输出日志。

🌐 Any logs at or higher than the given level will be shown. You can instead pass --silent to turn off all output logs.

useBetaCli

默认：假
类型：布尔

实验性选项，可启用 CLI 的测试功能。这意味着 CLI 的某些功能可能会发生变化，这些变化可能是破坏性的，或者可能存在漏洞。

🌐 Experimental option that enables beta features of the CLI. This means that you may get some changes to the CLI functionality that are breaking changes, or potentially bugs.

recursiveInstall

默认：真
类型：布尔

如果启用此选项，pnpm install 的主要行为将变为 pnpm install -r，这意味着安装将对所有工作区或子目录包执行。

🌐 If this is enabled, the primary behaviour of pnpm install becomes that of pnpm install -r, meaning the install is performed on all workspace or subdirectory packages.

否则，pnpm install 将只在当前目录中构建该软件包。

🌐 Else, pnpm install will exclusively build the package in the current directory.

engineStrict

默认：假
类型：布尔

如果启用此选项，pnpm 将不会安装任何声称与当前 Node 版本不兼容的包。

🌐 If this is enabled, pnpm will not install any package that claims to not be compatible with the current Node version.

无论此配置如何，如果一个项目（而非依赖）在其 engines 字段中指定了不兼容的版本，安装总会失败。

🌐 Regardless of this configuration, installation will always fail if a project (not a dependency) specifies an incompatible version in its engines field.

npmPath

类型：路径

pnpm 用于某些操作（例如发布）的 npm 二进制文件的位置。

🌐 The location of the npm binary that pnpm uses for some actions, like publishing.

pmOnFail

新增于：v11.0.0

🌐 Added in: v11.0.0

默认：下载
类型：下载、错误、警告、忽略

当正在运行的 pnpm 版本与声明的版本不匹配时，覆盖 packageManager 字段和 devEngines.packageManager 的 onFail 行为。

🌐 Overrides the onFail behavior of both the packageManager field and devEngines.packageManager when the running pnpm version does not match the declared one.

download — 下载并运行声明的 pnpm 版本（这是默认选项，并且与之前的 managePackageManagerVersions: true 行为一致）。
error — 命令失败（相当于以前的 packageManagerStrictVersion: true）。
warn — 打印警告但继续（等同于之前的 packageManagerStrict: false 或 COREPACK_ENABLE_STRICT=0）。
ignore — 完全跳过检查（等同于之前的 managePackageManagerVersions: false）。当版本管理由外部工具处理时非常有用，例如 asdf、mise 或 Volta。

可以通过 CLI 标志、环境变量或 pnpm-workspace.yaml 设置：

🌐 Can be set via CLI flag, environment variable, or pnpm-workspace.yaml:

pnpm install --pm-on-fail=ignore
pnpm_config_pm_on_fail=ignore pnpm install

pnpm-workspace.yaml
pmOnFail: ignore

此设置替代已移除的 managePackageManagerVersions、packageManagerStrict 和 packageManagerStrictVersion 设置，以及 COREPACK_ENABLE_STRICT 环境变量。

🌐 This setting replaces the removed managePackageManagerVersions, packageManagerStrict, and packageManagerStrictVersion settings, as well as the COREPACK_ENABLE_STRICT environment variable.

迁移：

🌐 Migration:

已移除的设置	替换为
`managePackageManagerVersions: true`	`pmOnFail: download`（默认）
`managePackageManagerVersions: false`	`pmOnFail: ignore`
`packageManagerStrict: false`	`pmOnFail: warn`
`packageManagerStrictVersion: true`	`pmOnFail: error`
`COREPACK_ENABLE_STRICT=0`	`pmOnFail: warn`

另请参见 pnpm with，了解如何在不更改此设置的情况下运行特定版本的 pnpm。

🌐 See also pnpm with for running pnpm at a specific version without changing this setting.

ignoreWorkspaceRootCheck

默认：假
类型：布尔

如果启用此功能，从项目根目录运行 pnpm install/pnpm add 时，当未提供 -w/--ignore-workspace-root-check 时将不再报错。

🌐 If this is enabled, running pnpm install/pnpm add from the project's root folder will no longer error when -w/--ignore-workspace-root-check is not provided.

构建设置

🌐 Build Settings

ignoreScripts

默认：假
类型：布尔

不要执行项目 package.json 及其依赖中定义的任何脚本。

🌐 Do not execute any scripts defined in the project package.json and its dependencies.

note

此标志不会阻止执行 .pnpmfile.mjs

🌐 This flag does not prevent the execution of .pnpmfile.mjs

childConcurrency

默认：5
类型：数字

同时分配用于构建 node_modules 的子进程的最大数量。

🌐 The maximum number of child processes to allocate simultaneously to build node_modules.

sideEffectsCache

默认：真
类型：布尔

使用并缓存（前/后）安装钩子的结果。

🌐 Use and cache the results of (pre/post)install hooks.

当安装前/后脚本修改了包的内容（例如构建输出）时，pnpm 会将修改后的包保存到全局存储中。在同一台机器上的后续安装中，pnpm 会重用这个缓存的、预构建的版本，从而显著加快安装速度。

🌐 When a pre/post install script modify the contents of a package (e.g. build output), pnpm saves the modified package in the global store. On future installs on the same machine, pnpm reuses this cached, prebuilt version—making installs significantly faster.

note

在以下情况下，你可能需要禁用此设置：

🌐 You may want to disable this setting if:

安装脚本会修改包目录之外的文件（pnpm 无法跟踪或缓存这些更改）。
这些脚本会执行与构建软件包无关的副作用。

sideEffectsCacheReadonly

默认：假
类型：布尔

仅使用副作用缓存（如果存在），不要为新包创建它。

🌐 Only use the side effects cache if present, do not create it for new packages.

unsafePerm

默认：false 如果以 root 用户运行，否则 true
类型：布尔

设置为 true 可在运行软件包脚本时启用 UID/GID 切换。如果明确设置为 false，则以非 root 用户安装将失败。

🌐 Set to true to enable UID/GID switching when running package scripts. If set explicitly to false, then installing as a non-root user will fail.

nodeOptions

默认：空
类型：字符串

通过 NODE_OPTIONS 环境变量传递给 Node.js 的选项。这不会影响 pnpm 本身的执行方式，但会影响生命周期脚本的调用方式。

🌐 Options to pass through to Node.js via the NODE_OPTIONS environment variable. This does not impact how pnpm itself is executed but it does impact how lifecycle scripts are called.

要保留现有的 NODE_OPTIONS，你可以在配置中使用 ${NODE_OPTIONS} 引用现有的环境变量：

🌐 To preserve existing NODE_OPTIONS you can reference the existing environment variable using ${NODE_OPTIONS} in your configuration:

nodeOptions: "${NODE_OPTIONS:- } --experimental-vm-modules"

verifyDepsBeforeRun

默认：安装
类型：安装、警告、错误、提示、错误

此设置允许在运行脚本之前检查依赖的状态。检查将在 pnpm run 和 pnpm exec 命令上运行。支持以下值：

🌐 This setting allows the checking of the state of dependencies before running scripts. The check runs on pnpm run and pnpm exec commands. The following values are supported:

install - Automatically runs install if node_modules is not up to date.
warn - Prints a warning if node_modules is not up to date.
prompt - Prompts the user for permission to run install if node_modules is not up to date.
error - Throws an error if node_modules is not up to date.
false - Disables dependency checks.

strictDepBuilds

新增于：v10.3.0

🌐 Added in: v10.3.0

默认：真
类型：布尔

当启用 strictDepBuilds 时，如果有任何依赖存在未审核的构建脚本（即 postinstall 脚本），安装将以非零退出代码退出。

🌐 When strictDepBuilds is enabled, the installation will exit with a non-zero exit code if any dependencies have unreviewed build scripts (aka postinstall scripts).

allowBuilds

新增于：v10.26.0

🌐 Added in: v10.26.0

一个包匹配器的映射，用于明确允许（true）或禁止（false）脚本执行。

🌐 A map of package matchers to explicitly allow (true) or disallow (false) script execution.

allowBuilds:
  esbuild: true
  core-js: false
  # nx versions with build scripts not listed below will
  # fail by default with ERR_PNPM_IGNORED_BUILDS
  nx@21.6.4 || 21.6.5: true
  nx@21.6.0: false

默认行为： 未在 allowBuilds 中列出的软件包默认情况下不被允许，并被视为未经审核。默认情况下，将打印错误信息（strictDepBuilds 默认为 true）。如果 strictDepBuilds 设置为 false，则会打印警告信息。

在安装过程中，尚未在 allowBuilds 中列出的具有被忽略构建的依赖会自动以占位符值添加到 pnpm-workspace.yaml，因此你可以手动将它们设置为 true 或 false。pnpm add 和 pnpm approve-builds 上的 --allow-build 标志同样会将其条目写入此处。

🌐 During install, dependencies with ignored builds that are not yet listed in allowBuilds are automatically added to pnpm-workspace.yaml with a placeholder value, so you can manually set them to true or false. The --allow-build flag on pnpm add and pnpm approve-builds writes its entries here as well.

从旧设置迁移

要自动迁移这些设置，请按照《从 v10 迁移到 v11》指南运行 pnpx codemod run pnpm-v10-to-v11。

🌐 To migrate these settings automatically, run pnpx codemod run pnpm-v10-to-v11 from the Migrating from v10 to v11 guide.

在 v11 中，以下设置已被移除，并由 allowBuilds 替代：onlyBuiltDependencies、onlyBuiltDependenciesFile、neverBuiltDependencies、ignoredBuiltDependencies 和 ignoreDepScripts。

🌐 The following settings have been removed in v11 and replaced by allowBuilds: onlyBuiltDependencies, onlyBuiltDependenciesFile, neverBuiltDependencies, ignoredBuiltDependencies, and ignoreDepScripts.

之前：

🌐 Before:

onlyBuiltDependencies:
  - electron
neverBuiltDependencies:
  - core-js
ignoredBuiltDependencies:
  - esbuild

之后：

🌐 After:

allowBuilds:
  electron: true
  core-js: false
  esbuild: false

dangerouslyAllowAllBuilds

新增于：v10.9.0

🌐 Added in: v10.9.0

默认：假
类型：布尔

如果设置为 true，所有依赖的构建脚本（例如 preinstall、install、postinstall）将自动运行，无需批准。

🌐 If set to true, all build scripts (e.g. preinstall, install, postinstall) from dependencies will run automatically, without requiring approval.

warning

此设置允许所有依赖——包括传递依赖——运行安装脚本，无论是现在还是未来。即使你当前的依赖图看起来很安全：

🌐 This setting allows all dependencies—including transitive ones—to run install scripts, both now and in the future. Even if your current dependency graph appears safe:

未来的更新可能会引入新的、不受信任的依赖。
现有包可能会在更高版本中添加脚本。
软件包可能被劫持或入侵，并开始执行恶意代码。

为了最大程度的安全，只有在你完全了解风险并信任你所使用的整个生态系统时才启用此功能。建议明确审查并允许构建。

🌐 For maximum safety, only enable this if you’re fully aware of the risks and trust the entire ecosystem you’re pulling from. It’s recommended to review and allow builds explicitly.

Node.js 设置

🌐 Node.js Settings

nodeVersion

默认值：node -v 返回的值，不含 v 前缀
类型：精确的 semver 版本（不是范围）

检查软件包的 engines 设置时要使用的 Node.js 版本。

🌐 The Node.js version to use when checking a package's engines setting.

如果你想防止项目的贡献者添加不兼容的新依赖，可以在项目根目录的 pnpm-workspace.yaml 文件中使用 nodeVersion 和 engineStrict:

🌐 If you want to prevent contributors of your project from adding new incompatible dependencies, use nodeVersion and engineStrict in a pnpm-workspace.yaml file at the root of the project:

nodeVersion: 12.22.0
engineStrict: true

这样，即使有人使用 Node.js v16，他们也无法安装不支持 Node.js v12.22.0 的新依赖。

🌐 This way, even if someone is using Node.js v16, they will not be able to install a new dependency that doesn't support Node.js v12.22.0.

runtimeOnFail

新增于：v11.0.0

🌐 Added in: v11.0.0

默认：未定义
类型：下载、错误、警告、忽略

覆盖根项目 package.json 中 devEngines.runtime（以及 engines.runtime）的 onFail 字段。当你希望本地行为与清单中写的不同时，这很有用——例如，即使清单设置了 onFail: "warn"，也强制 pnpm 下载声明的运行时：

🌐 Overrides the onFail field of devEngines.runtime (and engines.runtime) in the root project's package.json. This is useful when you want a different local behavior than what is written in the manifest — for instance, forcing pnpm to download the declared runtime even when the manifest sets onFail: "warn":

pnpm-workspace.yaml
runtimeOnFail: download

nodeDownloadMirrors

新增于：v11.0.0

🌐 Added in: v11.0.0

默认：未定义
Type: Record<string, string>

在 pnpm-workspace.yaml 中配置自定义 Node.js 下载镜像。键是发布通道（release、rc、nightly、v8-canary 等），值是基础 URL。

🌐 Configure custom Node.js download mirrors in pnpm-workspace.yaml. The keys are release channels (release, rc, nightly, v8-canary, etc.) and the values are base URLs.

以下是如何配置 pnpm 从中国的镜像下载 Node.js 的方法：

🌐 Here is how pnpm may be configured to download Node.js from a mirror in China:

nodeDownloadMirrors:
  release: https://npmmirror.com/mirrors/node/
  rc: https://npmmirror.com/mirrors/node-rc/
  nightly: https://npmmirror.com/mirrors/node-nightly/

其他设置

🌐 Other Settings

savePrefix

默认: '^'
类型：'^'、'~'、''

配置安装到 package.json 文件的包版本如何添加前缀。

🌐 Configure how versions of packages installed to a package.json file get prefixed.

例如，如果一个软件包的版本为 1.2.3，默认情况下其版本设置为 ^1.2.3，这允许对该软件包进行次要升级，但在 pnpm config set save-prefix='~' 之后，它将被设置为 ~1.2.3，这只允许补丁升级。

🌐 For example, if a package has version 1.2.3, by default its version is set to ^1.2.3 which allows minor upgrades for that package, but after pnpm config set save-prefix='~' it would be set to ~1.2.3 which only allows patch upgrades.

当添加的软件包指定了范围时，此设置将被忽略。例如，pnpm add foo@2 会将 package.json 中 foo 的版本设置为 2，而不管 savePrefix 的值是多少。

🌐 This setting is ignored when the added package has a range specified. For instance, pnpm add foo@2 will set the version of foo in package.json to 2, regardless of the value of savePrefix.

globalDir

默认：
- 如果设置了 $XDG_DATA_HOME 环境变量，那么路径就是 $XDG_DATA_HOME/pnpm/global
- 在 Windows 上：~/AppData/Local/pnpm/global
- 在 macOS 上：~/Library/pnpm/global
- 在 Linux 上：~/.local/share/pnpm/global
类型：路径

指定自定义目录来存储全局包。

🌐 Specify a custom directory to store global packages.

globalBinDir

默认：
- 如果设置了 $XDG_DATA_HOME 环境变量，则为 $XDG_DATA_HOME/pnpm/bin
- 在 Windows 上：~/AppData/Local/pnpm/bin
- 在 macOS 上：~/Library/pnpm/bin
- 在 Linux 上：~/.local/share/pnpm/bin
类型：路径

允许设置全局安装包的 bin 文件的目标目录。

🌐 Allows to set the target directory for the bin files of globally installed packages.

tip

在 pnpm v11 中，全局安装的二进制文件存储在 PNPM_HOME 的 bin 子目录中，而不是直接存放在 PNPM_HOME 中。这可以防止像 global/ 和 store/ 这样的内部目录在 PNPM_HOME 在 PATH 时污染 shell 自动补全。升级后，运行 pnpm setup 来更新你的 shell 配置。

🌐 In pnpm v11, globally installed binaries are stored in a bin subdirectory of PNPM_HOME instead of directly in PNPM_HOME. This prevents internal directories like global/ and store/ from polluting shell autocompletion when PNPM_HOME is on PATH. After upgrading, run pnpm setup to update your shell configuration.

npmrcAuthFile

新增于：v11.0.0

🌐 Added in: v11.0.0

默认：~/.npmrc
类型：路径

包含注册表认证令牌的文件路径。默认情况下，pnpm 会从 ~/.npmrc 读取认证令牌，作为注册表认证的备用使用。使用此设置可以指向其他文件。

🌐 The path to a file containing registry authentication tokens. By default, pnpm reads auth tokens from ~/.npmrc as a fallback for registry authentication. Use this setting to point to a different file instead.

此设置无法在项目级别的 pnpm-workspace.yaml 中设置；请在全局配置文件中、通过 --npmrc-auth-file CLI 选项或通过 PNPM_CONFIG_NPMRC_AUTH_FILE 环境变量进行设置（作为回退，将遵循 npm 风格的 NPM_CONFIG_USERCONFIG）。相对路径是相对于工作目录解析的。

🌐 This setting cannot be set in pnpm-workspace.yaml at the project level; set it in the global configuration file, via the --npmrc-auth-file CLI option, or via the PNPM_CONFIG_NPMRC_AUTH_FILE environment variable (the npm-style NPM_CONFIG_USERCONFIG is honored as a fallback). A relative path is resolved against the working directory.

stateDir

默认：
- 如果设置了 $XDG_STATE_HOME 环境变量，那么就是 $XDG_STATE_HOME/pnpm
- 在 Windows 上：~/AppData/Local/pnpm-state
- 在 macOS 上：~/.pnpm-state
- 在 Linux 上：~/.local/state/pnpm
类型：路径

pnpm 创建 pnpm-state.json 文件的目录，目前该文件仅由更新检查器使用。

🌐 The directory where pnpm creates the pnpm-state.json file that is currently used only by the update checker.

cacheDir

默认：
- 如果设置了 $XDG_CACHE_HOME 环境变量，则为 $XDG_CACHE_HOME/pnpm
- 在 Windows 上：~/AppData/Local/pnpm-cache
- 在 macOS 上：~/Library/Caches/pnpm
- 在 Linux 上：~/.cache/pnpm
类型：路径

缓存的位置（包元数据、dlx 缓存以及一些安装验证结果）。

🌐 The location of the cache (package metadata, dlx cache, and some install verification results).

像存储一样，缓存目录也旨在仅在相互信任的用户、作业和进程之间共享。如果你配置或恢复共享的 cacheDir，请使用文件系统权限进行保护，以防不受信任的用户写入其中。

🌐 Like the store, the cache directory is intended to be shared only between mutually trusted users, jobs, and processes. If you configure or restore a shared cacheDir, protect it with filesystem permissions so untrusted users cannot write to it.

useStderr

默认：假
类型：布尔

当 true 时，所有输出都写入 stderr。

🌐 When true, all the output is written to stderr.

updateNotifier

默认：真
类型：布尔

设置为 false 可在使用比最新版本旧的 pnpm 时抑制更新通知。

🌐 Set to false to suppress the update notification when using an older version of pnpm than the latest.

preferSymlinkedExecutables

默认：true，当 node-linker 设置为 hoisted 且系统为 POSIX 时
类型：布尔

创建指向 node_modules/.bin 中可执行文件的符号链接，而不是命令 shim。此设置在 Windows 上会被忽略，因为只有命令 shim 可用。

🌐 Create symlinks to executables in node_modules/.bin instead of command shims. This setting is ignored on Windows, where only command shims work.

ignoreCompatibilityDb

默认：假
类型：布尔

在安装过程中，某些软件包的依赖会被自动修补。如果你想禁用此功能，请将此配置设置为 true。

🌐 During installation the dependencies of some packages are automatically patched. If you want to disable this, set this config to true.

这些补丁是从 Yarn 的 @yarnpkg/extensions 包中应用的。

🌐 The patches are applied from Yarn's @yarnpkg/extensions package.

resolutionMode

默认：最高（在 v8.0.0 到 v8.6.12 版本中为 最低-直接）
类型：最高、基于时间、最低直接

当 resolutionMode 设置为 time-based 时，依赖将按照以下方式解析：

🌐 When resolutionMode is set to time-based, dependencies will be resolved the following way:

直接依赖将被解析为其最低版本。因此，如果依赖中有 foo@^1.1.0，那么将安装 1.1.0。
将从最后一个直接依赖发布之前发布的版本解析子依赖。

使用此解析模式，在有热缓存的情况下安装速度更快。它还减少了子依赖劫持的可能性，因为只有在直接依赖更新时，子依赖才会被更新。

🌐 With this resolution mode installations with warm cache are faster. It also reduces the chance of subdependency hijacking as subdependencies will be updated only if direct dependencies are updated.

这种解析模式仅适用于 npm 的 [完整元数据]。因此，在某些情况下它会比较慢。不过，如果你使用的是 Verdaccio v5.15.1 或更高版本，你可以将 registrySupportsTimeField 设置为 true，这样速度就会非常快。

🌐 This resolution mode works only with npm's full metadata. So it is slower in some scenarios. However, if you use Verdaccio v5.15.1 or newer, you may set the registrySupportsTimeField setting to true, and it will be really fast.

当 resolutionMode 设置为 lowest-direct 时，直接依赖将解析为它们的最低版本。

🌐 When resolutionMode is set to lowest-direct, direct dependencies will be resolved to their lowest versions.

registrySupportsTimeField

默认：假
类型：布尔

如果你使用的注册表在简化的元数据中返回“time”字段，请将此设置为 true。截至目前，只有 v5.15.1 及以上版本的 Verdaccio 支持此功能。

🌐 Set this to true if the registry that you are using returns the "time" field in the abbreviated metadata. As of now, only Verdaccio from v5.15.1 supports this.

extendNodePath

默认：真
类型：布尔

当 true 时，pnpm 会在命令 Shim（在 node_modules/.bin 中创建的封装脚本）中设置 NODE_PATH 环境变量。当 false 时，NODE_PATH 不会被设置。

🌐 When true, pnpm sets the NODE_PATH environment variable in command shims (the wrapper scripts created in node_modules/.bin). When false, NODE_PATH is not set.

为什么需要这个

🌐 Why this is needed

pnpm 的 [隔离 node_modules 布局] 意味着一个包只能访问它自己声明的依赖。然而，当 CLI 工具通过命令 shim 运行时，一些库（特别是 import-local，被 jest、eslint 等使用）会从 当前工作目录 解析模块，而不是从二进制文件自身的位置。由于工作目录是项目根目录——而不是虚拟存储中的包——因此从 CWD 使用标准 node_modules 解析无法找到二进制文件的传递依赖。

🌐 pnpm's isolated node_modules layout means that a package can only access its own declared dependencies. However, when a CLI tool runs via a command shim, some libraries (notably import-local, used by jest, eslint, and others) resolve modules from the current working directory rather than from the binary's own location. Since the working directory is the project root — not the package inside the virtual store — the standard node_modules resolution from the CWD won't find the binary's transitive dependencies.

为了弥合这一差距，pnpm 在 NODE_PATH 中包含两种类型的路径：

🌐 To bridge this gap, pnpm includes two types of paths in NODE_PATH:

包自身的依赖目录（例如 .pnpm/pkg@version/node_modules）——这允许基于当前工作目录 (CWD) 的解析找到包的同级依赖的正确版本。
被提升的 node_modules 目录（例如，.pnpm/node_modules）——当设置 hoistPattern 时，这是放置被提升包的目录。Node.js 无法通过其标准解析算法发现该目录，因此必须通过 NODE_PATH 提供。

NODE_PATH 在启用 enableGlobalVirtualStore 时也是必不可少的。
有了全局虚拟存储，包会从项目外部的中央位置建立符号链接，所以 Node.js 从二进制真实路径向上进行的标准 node_modules 遍历无法访问项目自身的 node_modules 或其提升的依赖。在这种情况下，NODE_PATH 必须同时包含项目根目录的 node_modules 和 node_modules/.pnpm/node_modules 的提升目录，以确保正确解析。

何时禁用

🌐 When to disable

如果你确定项目中的任何 CLI 工具都不会从工作目录解析模块，并且你没有使用全局虚拟存储，则可以将其设置为 false。禁用它会生成稍微简单的命令封装器。

🌐 You may set this to false if you are certain that none of the CLI tools in your project resolve modules from the working directory and you are not using a global virtual store. Disabling it produces slightly simpler command shims.

deployAllFiles

默认：假
类型：布尔

在部署软件包或安装本地软件包时，软件包的所有文件都会被复制。默认情况下，如果软件包的 package.json 中有 "files" 字段，则只会复制列出的文件和目录。

🌐 When deploying a package or installing a local package, all files of the package are copied. By default, if the package has a "files" field in the package.json, then only the listed files and directories are copied.

dedupeDirectDeps

默认：假
类型：布尔

当设置为 true 时，已经符号链接到工作区根目录 node_modules 的依赖将不会被符号链接到子项目 node_modules 目录。

🌐 When set to true, dependencies that are already symlinked to the root node_modules directory of the workspace will not be symlinked to subproject node_modules directories.

optimisticRepeatInstall

新增于：v10.1.0

🌐 Added in: v10.1.0

默认：真
类型：布尔

启用后，在继续安装之前将执行快速检查。这样，重复安装或在所有内容都已更新的项目上安装会更快。

🌐 When enabled, a fast check will be performed before proceeding to installation. This way a repeat install or an install on a project with everything up-to-date becomes a lot faster.

requiredScripts

列在此数组中的脚本将在工作区的每个项目中被要求使用。否则，pnpm -r run <script name> 将会失败。

🌐 Scripts listed in this array will be required in each project of the workspace. Otherwise, pnpm -r run <script name> will fail.

requiredScripts:
- build

enablePrePostScripts

默认：真
类型：布尔

当 true 时，pnpm 会自动运行任何前置/后置脚本。因此运行 pnpm foo 就像运行 pnpm prefoo && pnpm foo && pnpm postfoo 一样。

🌐 When true, pnpm will run any pre/post scripts automatically. So running pnpm foo will be like running pnpm prefoo && pnpm foo && pnpm postfoo.

scriptShell

默认：空
类型：路径

用于运行 pnpm run 命令脚本的 shell。

🌐 The shell to use for scripts run with the pnpm run command.

例如，要在 Windows 上强制使用 Git Bash：

🌐 For instance, to force usage of Git Bash on Windows:

pnpm config set scriptShell "C:\\Program Files\\git\\bin\\bash.exe"

shellEmulator

默认：假
类型：布尔

当 true 时，pnpm 将使用一个基于 JavaScript 的 [类 bash shell] 来执行脚本。

🌐 When true, pnpm will use a JavaScript implementation of a bash-like shell to execute scripts.

此选项简化了跨平台脚本编写。例如，默认情况下，以下脚本将在不符合 POSIX 的系统上失败：

🌐 This option simplifies cross-platform scripting. For instance, by default, the next script will fail on non-POSIX-compliant systems:

"scripts": {
  "test": "NODE_ENV=test node test.js"
}

但是如果将 shellEmulator 设置为 true，它将在所有平台上运行。

🌐 But if the shellEmulator setting is set to true, it will work on all platforms.

note

Node.js 22 或更高版本支持在无需 pnpm 协助的情况下运行脚本。对于上面的示例，你可以使用 node --run test 运行 test 脚本。然而，shellEmulator 选项对此没有影响。依赖 POSIX 功能的脚本需要通过 pnpm run 而不是 node --run 来运行，以便在非 POSIX 兼容的环境中正常工作。

🌐 Node.js 22 or higher supports running scripts without pnpm's assistance. For the example above, you can run the test script with node --run test. However, the shellEmulator option has no effect on this. Scripts that depend on POSIX features are required to be run pnpm run instead of node --run to work in non-POSIX-compliant environments.

catalogMode

新增于：v10.12.1

🌐 Added in: v10.12.1

默认：手动
类型：手动、严格、偏好

控制在运行 pnpm add 时是否以及如何将依赖添加到默认目录。有三种模式：

🌐 Controls if and how dependencies are added to the default catalog, when running pnpm add. There are three modes:

strict - only allows dependency versions from the catalog. Adding a dependency outside the catalog's version range will cause an error.
prefer - prefers catalog versions, but will fall back to direct dependencies if no compatible version is found.
manual (default) - does not automatically add dependencies to the catalog.

ci

新增于：v10.12.1

🌐 Added in: v10.12.1

默认值：true（当环境被检测为 CI 时）
类型：布尔

此设置明确告知 pnpm 当前环境是否为 CI（持续集成）环境。

🌐 This setting explicitly tells pnpm whether the current environment is a CI (Continuous Integration) environment.

cleanupUnusedCatalogs

新增于：v10.15.0

🌐 Added in: v10.15.0

默认：假
类型：布尔

当设置为 true 时，pnpm 会在安装过程中移除未使用的目录条目。

🌐 When set to true, pnpm will remove unused catalog entries during installation.

依赖解析​

overrides​

覆盖同级依赖​

packageExtensions​

allowedDeprecatedVersions​

updateConfig​

updateConfig.ignoreDependencies​

supportedArchitectures​

ignoredOptionalDependencies​

minimumReleaseAge​

minimumReleaseAgeExclude​

minimumReleaseAgeIgnoreMissingTime​

minimumReleaseAgeStrict​

trustPolicy​

trustPolicyExclude​

trustPolicyIgnoreAfter​

trustLockfile​

blockExoticSubdeps​

registries​

namedRegistries​

依赖提升设置​

hoist​

hoistWorkspacePackages​

hoistPattern​

publicHoistPattern​

shamefullyHoist​

hoistingLimits​

Node 模块设置​

modulesDir​

nodeLinker​

nodeExperimentalPackageMap​

nodePackageMapType​

symlink​

enableModulesDir​

virtualStoreDir​

virtualStoreDirMaxLength​

virtualStoreOnly​

packageImportMethod​

modulesCacheMaxAge​

dlxCacheMaxAge​

enableGlobalVirtualStore​

存储设置​

storeDir​

verifyStoreIntegrity​

useRunningStoreServer​

strictStorePkgContentCheck​

frozenStore​

网络设置​

httpsProxy​

httpProxy​

noProxy​

localAddress​

maxsockets​

strictSsl​

锁定文件设置​

lockfile​

preferFrozenLockfile​

lockfileIncludeTarballUrl​

gitBranchLockfile​

mergeGitBranchLockfilesBranchPattern​

peersSuffixMaxLength​

请求设置​

gitShallowHosts​

networkConcurrency​

fetchRetries​

fetchRetryFactor​

fetchRetryMintimeout​

fetchRetryMaxtimeout​

fetchTimeout​

fetchWarnTimeoutMs​

fetchMinSpeedKiBps​

对等依赖设置​

autoInstallPeers​

版本冲突​

解决冲突​

dedupePeerDependents​

dedupePeers​

strictPeerDependencies​

resolvePeersFromWorkspaceRoot​

peerDependencyRules​

依赖解析

overrides

覆盖同级依赖

packageExtensions

allowedDeprecatedVersions

updateConfig

updateConfig.ignoreDependencies

supportedArchitectures

ignoredOptionalDependencies

minimumReleaseAge

minimumReleaseAgeExclude

minimumReleaseAgeIgnoreMissingTime

minimumReleaseAgeStrict

trustPolicy

trustPolicyExclude

trustPolicyIgnoreAfter

trustLockfile

blockExoticSubdeps

registries

namedRegistries

依赖提升设置

hoist

hoistWorkspacePackages

hoistPattern

publicHoistPattern

shamefullyHoist

hoistingLimits

Node 模块设置

modulesDir

nodeLinker

nodeExperimentalPackageMap

nodePackageMapType

symlink

enableModulesDir

virtualStoreDir

virtualStoreDirMaxLength

virtualStoreOnly

packageImportMethod

modulesCacheMaxAge

dlxCacheMaxAge

enableGlobalVirtualStore

存储设置

storeDir

verifyStoreIntegrity

useRunningStoreServer

strictStorePkgContentCheck

frozenStore

网络设置

httpsProxy

httpProxy

noProxy

localAddress

maxsockets

strictSsl

锁定文件设置

lockfile

preferFrozenLockfile

lockfileIncludeTarballUrl

gitBranchLockfile

mergeGitBranchLockfilesBranchPattern

peersSuffixMaxLength

请求设置

gitShallowHosts

networkConcurrency

fetchRetries

fetchRetryFactor

fetchRetryMintimeout

fetchRetryMaxtimeout

fetchTimeout

fetchWarnTimeoutMs

fetchMinSpeedKiBps

对等依赖设置

autoInstallPeers

版本冲突

解决冲突

dedupePeerDependents

dedupePeers

strictPeerDependencies

resolvePeersFromWorkspaceRoot

peerDependencyRules