Skip to main content
Version: 10.x

设置 (pnpm-workspace.yaml)

pnpm 从命令行、环境变量、pnpm-workspace.yaml 和 .npmrc 文件获取其配置。

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

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

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

相关的配置文件如下：

🌐 The relevant configuration files are:

  • 每个项目的配置文件：/path/to/my/project/pnpm-workspace.yaml
  • 全局配置文件
note

与授权相关的设置通过 .npmrc 进行处理。

🌐 Authorization-related settings are handled via .npmrc.

配置文件中的值可能包含使用 ${NAME} 语法的环境变量。环境变量也可以指定默认值。使用 ${NAME-fallback} 如果 NAME 未设置，将返回 fallback。${NAME:-fallback} 如果 NAME 未设置或为空字符串，将返回 fallback。

🌐 Values in the configuration files may contain env variables using the ${NAME} syntax. The env variables may also be specified with default values. Using ${NAME-fallback} will return fallback if NAME isn't set. ${NAME:-fallback} will return fallback if NAME isn't set, or is an empty string.

依赖解析​

🌐 Dependency Resolution

overrides​

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

🌐 This field allows you to instruct pnpm to override any dependency in the dependency graph. 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.

覆盖可以定义为对直接依赖规范的引用。
这是通过在依赖名称前加上 $ 来实现的：

🌐 An override may be defined as a reference to a direct dependency's spec. This is achieved by prefixing the name of the dependency with a $:

package.json
{
  "dependencies": {
    "foo": "^1.0.0"
  }
}
pnpm-workspace.yaml
overrides:
  foo: "$foo"

引用的包不需要与被覆盖的包匹配：

🌐 The referenced package does not need to match the overridden one:

pnpm-workspace.yaml
overrides:
  bar: "$foo"

如果你发现使用某个软件包时并不需要它的某个依赖，你可以使用 - 将其移除。例如，如果软件包 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.

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

  • 默认：0
  • 类型：数字（分钟）

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

🌐 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

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.

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)

依赖提升设置​

🌐 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.

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。
  • 默认：真
  • 类型：布尔

当 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.

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

  • 默认：false（在 CI 中总是 false）
  • 类型：布尔
  • 状态：实验性

启用后，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.

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.

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.

锁定文件设置​

🌐 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 minimum (base) timeout for retrying requests.

fetchRetryMaxtimeout​

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

最大回退超时，以确保重试因素不会使请求时间过长。

🌐 The maximum fallback timeout to ensure the retry factor does not make requests too long.

fetchTimeout​

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

等待 HTTP 请求完成的最长时间。

🌐 The maximum amount of time to wait for HTTP requests to complete.

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.

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.

packageManagerStrict​

  • 默认：真
  • 类型：布尔

如果此设置被禁用，当 package.json 的 packageManager 字段中指定了不同的包管理器时，pnpm 不会失败。启用后，只会检查包名（自 pnpm v9.2.0 起），因此无论 packageManager 字段中指定的版本如何，你仍然可以运行任何版本的 pnpm。

🌐 If this setting is disabled, pnpm will not fail if a different package manager is specified in the packageManager field of package.json. When enabled, only the package name is checked (since pnpm v9.2.0), so you can still run any version of pnpm regardless of the version specified in the packageManager field.

或者，你可以通过将 COREPACK_ENABLE_STRICT 环境变量设置为 0 来禁用此设置。

🌐 Alternatively, you can disable this setting by setting the COREPACK_ENABLE_STRICT environment variable to 0.

packageManagerStrictVersion​

  • 默认：假
  • 类型：布尔

启用后，如果 pnpm 的版本与 package.json 的 packageManager 字段中指定的版本不完全匹配，pnpm 将失败。

🌐 When enabled, pnpm will fail if its version doesn't exactly match the version specified in the packageManager field of package.json.

managePackageManagerVersions​

  • 默认：真
  • 类型：布尔

启用后，pnpm 将自动下载并运行 package.json 的 packageManager 字段中指定的 pnpm 版本。这与 Corepack 使用的字段相同。示例：

🌐 When enabled, pnpm will automatically download and run the version of pnpm specified in the packageManager field of package.json. This is the same field used by Corepack. Example:

{
  "packageManager": "pnpm@9.3.0"
}

构建设置​

🌐 Build Settings

ignoreScripts​

  • 默认：假
  • 类型：布尔

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

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

note

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

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

ignoreDepScripts​

  • 默认：假
  • 类型：布尔

不要执行已安装包的任何脚本。项目的脚本会被执行。

🌐 Do not execute any scripts of the installed packages. Scripts of the projects are executed.

note

自 v10 起，除非依赖列在 onlyBuiltDependencies 中，否则 pnpm 不会运行其生命周期脚本。

🌐 Since v10, pnpm doesn't run the lifecycle scripts of dependencies unless they are listed in onlyBuiltDependencies.

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:

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

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）脚本执行。此字段取代了 onlyBuiltDependencies 和 ignoredBuiltDependencies（它们也已被此新设置弃用），提供了单一的真实来源。

🌐 A map of package matchers to explicitly allow (true) or disallow (false) script execution. This field replaces onlyBuiltDependencies and ignoredBuiltDependencies (which are also deprecated by this new setting), providing a single source of truth.

allowBuilds:
  esbuild: true
  core-js: false
  nx@21.6.4 || 21.6.5: true

默认行为： 默认情况下，allowBuilds 中未列出的包是禁止的，并会显示警告。如果设置 strictDepBuilds 为 true，则会显示错误信息。

neverBuiltDependencies​

不允许在安装期间执行“preinstall”、“install”和/或“postinstall”脚本的软件包名称列表。

🌐 A list of package names that are NOT allowed to execute "preinstall", "install", and/or "postinstall" scripts during installation.

使用 neverBuiltDependencies 而不使用 onlyBuiltDependencies 时要小心，因为这意味着允许所有其他依赖。

🌐 Be careful when using neverBuiltDependencies without onlyBuiltDependencies because it implies all other dependencies are allowed.

neverBuiltDependencies 字段的一个示例：

🌐 An example of the neverBuiltDependencies field:

neverBuiltDependencies:
- fsevents
- level

onlyBuiltDependencies​

允许在安装期间执行“preinstall”、“install”和/或“postinstall”脚本的包名称列表。只有列在此数组中的包才能运行这些生命周期脚本。如果省略 onlyBuiltDependenciesFile 和 neverBuiltDependencies，此配置选项将默认为阻止所有安装脚本。

🌐 A list of package names that are allowed to execute "preinstall", "install", and/or "postinstall" scripts during installation. Only the packages listed in this array will be able to run those lifecycle scripts. If onlyBuiltDependenciesFile and neverBuiltDependencies are omitted, this configuration option will default to blocking all install scripts.

示例：

🌐 Example:

onlyBuiltDependencies:
- fsevents

新增于：v10.19.0

🌐 Added in: v10.19.0

你可以将许可限制为特定版本（并使用 || 的析取列发布本列表）。当指定版本时，只有这些版本的包可以运行生命周期脚本：

🌐 You may restrict allowances to specific versions (and lists of versions using a disjunction with ||). When versions are specified, only those versions of the package may run lifecycle scripts:

onlyBuiltDependencies:
- nx@21.6.4 || 21.6.5
- esbuild@0.25.1

onlyBuiltDependenciesFile​

此配置选项允许用户指定一个 JSON 文件，该文件列出了在 pnpm 安装过程中允许运行安装脚本的唯一软件包。通过使用此选项，你可以增强安全性，或确保只有特定依赖在安装期间执行脚本。

🌐 This configuration option allows users to specify a JSON file that lists the only packages permitted to run installation scripts during the pnpm install process. By using this, you can enhance security or ensure that only specific dependencies execute scripts during installation.

示例：

🌐 Example:

configDependencies:
  '@pnpm/trusted-deps': 0.1.0+sha512-IERT0uXPBnSZGsCmoSuPzYNWhXWWnKkuc9q78KzLdmDWJhnrmvc7N4qaHJmaNKIusdCH2riO3iE34Osohj6n8w==
onlyBuiltDependenciesFile: node_modules/.pnpm-config/@pnpm/trusted-deps/allow.json

JSON 文件本身应包含一组包名称：

🌐 The JSON file itself should contain an array of package names:

node_modules/.pnpm-config/@pnpm/trusted-deps/allow.json
[
  "@airbnb/node-memwatch",
  "@apollo/protobufjs",
  ...
]

ignoredBuiltDependencies​

新增于：v10.1.0

🌐 Added in: v10.1.0

一份包名称列表，这些包在安装过程中不允许执行“preinstall”、“install”和/或“postinstall”脚本，并且不会警告或请求执行。

🌐 A list of package names that are NOT allowed to execute "preinstall", "install", and/or "postinstall" scripts during installation and will not warn or ask to be executed.

当你因为知道不需要生命周期脚本而想要隐藏警告时，这很有用。

🌐 This is useful when you want to hide the warning because you know the lifecycle scripts are not needed.

示例：

🌐 Example:

ignoredBuiltDependencies:
- fsevents
- sharp

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

useNodeVersion​

  • 默认：未定义
  • 类型：语义化版本

指定项目运行时应使用的确切 Node.js 版本。pnpm 将自动安装指定的 Node.js 版本，并在运行 pnpm run 命令或 pnpm node 命令时使用该版本。

🌐 Specifies which exact Node.js version should be used for the project's runtime. pnpm will automatically install the specified version of Node.js and use it for running pnpm run commands or the pnpm node command.

这可以替代 .nvmrc 和 nvm。替代以下 .nvmrc 文件：

🌐 This may be used instead of .nvmrc and nvm. Instead of the following .nvmrc file:

16.16.0

使用此 pnpm-workspace.yaml 文件：

🌐 Use this pnpm-workspace.yaml file:

useNodeVersion: 16.16.0

此设置仅在位于工作区根目录的 pnpm-workspace.yaml 文件中有效。如果你需要为工作区中的某个项目指定自定义 Node.js，请改用 package.json 的 executionEnv.nodeVersion 字段。

🌐 This setting works only in a pnpm-workspace.yaml file that is in the root of your workspace. If you need to specify a custom Node.js for a project in the workspace, use the executionEnv.nodeVersion field of package.json instead.

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.

node-mirror​

  • 默认：https://nodejs.cn/download/<releaseDir>/
  • 类型：URL

设置用于下载 Node.js 的基础 URL。此设置中的 <releaseDir> 部分可以是 https://nodejs.cn/download 上的任何目录：release、rc、nightly、v8-canary 等。

🌐 Sets the base URL for downloading Node.js. The <releaseDir> portion of this setting can be any directory from https://nodejs.cn/download: release, rc, nightly, v8-canary, etc.

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

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

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

executionEnv.nodeVersion​

指定项目运行时应使用的确切 Node.js 版本。pnpm 将自动安装指定的 Node.js 版本，并在运行 pnpm run 命令或 pnpm node 命令时使用该版本。

🌐 Specifies which exact Node.js version should be used for the project's runtime. pnpm will automatically install the specified version of Node.js and use it for running pnpm run commands or the pnpm node command.

例如：

🌐 For example:

executionEnv:
  nodeVersion: 16.16.0

其他设置​

🌐 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.

tag​

  • 默认：最新
  • 类型：字符串

如果你 pnpm add 一个软件包，并且没有提供特定版本，那么它将安装在此设置下标签所注册的版本的软件包。

🌐 If you pnpm add a package and you don't provide a specific version, then it will install the package at the version registered under the tag from this setting.

如果没有指定明确的标签，这也会设置添加到由 pnpm tag 命令指定的 package@version 的标签。

🌐 This also sets the tag that is added to the package@version specified by the pnpm tag command if no explicit tag is given.

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
    • 在 Windows 上：~/AppData/Local/pnpm
    • 在 macOS 上：~/Library/pnpm
    • 在 Linux 上：~/.local/share/pnpm
  • 类型：路径

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

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

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 and dlx).

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:

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

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

🌐 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​

  • 默认：真
  • 类型：布尔

当 false 时，命令 shims 中未设置 NODE_PATH 环境变量。

🌐 When false, the NODE_PATH environment variable is not set in the 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.