版本：Next

Settings (pnpm-workspace.yaml)

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

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:

Per-project configuration file: /path/to/my/project/pnpm-workspace.yaml
Global configuration file: ~/.config/pnpm/rc (an INI-formatted list of key = value parameters)

注意

Authorization-related settings are handled by npm's configuration system. So, pnpm config set registry=<value> will actually save the setting to npm's global configuration file.

Values in the configuration files may contain env variables using the ${NAME} syntax. 也可以使用默认值指定环境变量。使用 ${NAME-fallback} 将在未设置 NAME 时返回 fallback。 ${NAME:-fallback} ，会在 NAME 不存在或为空字符串时返回 fallback 。

Dependency Resolution

overrides

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

请注意，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 的版本，而不会影响其他依赖。

一个overide可以被定义为直接依赖项的规则的引用。这通过依赖名称前缀一个 $ 实现:

package.json
{
  "dependencies": {
    "foo": "^1.0.0"
  }
}

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

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

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

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 特别有用，其中大多数可选包可以被安全地跳过。

packageExtensions

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

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

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

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

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

一个更大的例子：

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

提示

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

allowedDeprecatedVersions

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

示例：

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

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

updateConfig

updateConfig.ignoreDependencies

有时您无法更新依赖项。例如，最新版本的依赖项开始使用 ESM，但您的项目尚未采用 ESM。恼人的是，这样的包将始终被 pnpm outdated 命令打印出来，并在运行 pnpm update --latest 时更新。但是，你可以在 ignoreDependencies 字段中列出你不想更新的包：

updateConfig: {
  ignoreDependencies:
  - load-json-file

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

支持的架构

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

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

supportedArchitectures:
  os:
  - win32
  cpu:
  - x64

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

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

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

ignoredOptionalDependencies

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

ignoredOptionalDependencies:
- fsevents
- "@esbuild/*"

依赖提升设置

hoist

默认值：true
类型：Boolean

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

hoistWorkspacePackages

默认值：true
类型：Boolean

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。默认情况下，所有包都被提升 — 但是，如果你知道只有某些有缺陷的包具有幻影依赖，你可以使用此选项专门提升幻影依赖（推荐做法）。

例如：

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

你还可以在模式前面添加 ! 来避免提升。

例如：

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

publicHoistPattern

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

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. 提升至根模块目录中意味着应用代码可以访问到幻影依赖，即使它们对解析策略做了不当的修改。

当处理一些不能正确解析依赖关系的有缺陷可插拔工具时，此设置很有用。

例如：

publicHoistPattern:
- "*plugin*"

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

你还可以在模式前面添加 ! 来避免提升。

例如：

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

shamefullyHoist

默认值： false
类型：Boolean

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

Node 模块设置

modulesDir

默认值：node_modules
类型：路径

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

nodeLinker

默认值：isolated
类型：isolated、hoisted、pnp

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

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

symlink

默认值：true
类型：Boolean

当 symlink 设置为 false 时，pnpm 创建一个没有任何符号链接的虚拟存储目录。 It is a useful setting together with nodeLinker=pnp.

enableModulesDir

默认值：true
类型：Boolean

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

virtualStoreDir

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

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

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

或者你可以将虚拟存储设置为 .pnpm 并将其添加到 .gitignore。这将使堆栈跟踪更清晰，因为依赖项的路径将会提高一个目录层级。

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

virtualStoreDirMaxLength

默认值：
- 在 Linux/macOS 上：120
- 在 Windows 上：60
类型：number

设置虚拟存储目录 (node_modules/.pnpm) 中目录名称的最大允许长度。如果你在 Windows 上遇到长路径问题，你可以将其设置为较低的数字。

packageImportMethod

默认值： auto
类型：auto、hardlink、copy、clone、clone-copy

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

auto - 尝试从存储克隆包。如果不支持克隆则从存储硬链接包。如果克隆和链接都不支持，则回退到复制
hardlink - 从存储硬链接包
clone-or-copy - 尝试从存储中克隆包。如果不支持克隆则回退到复制。
copy - 从存储中复制包
clone - 从存储中克隆（也称为 copy-on-write 或参考链接）包

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

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

modulesCacheMaxAge

默认值：10080 （以分钟为单位的 7 天）
类型：number

孤立包应该从模块目录中被删除的时间（以分钟为单位）。 pnpm 在模块目录中保存了一个包的缓存。切换分支或降级依赖项时，这会提高安装速度。

dlxCacheMaxAge

默认值：1440 （以分钟为单位的 1 天）
类型：number

Dlx 缓存过期的时间（以分钟为单位）。执行 dlx 命令后，pnpm 会保留一个缓存，该缓存会省略后续调用同一 dlx 命令的安装步骤。

存储设置

storeDir

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

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

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

可以从不同的磁盘设置同一个存储，但在这种情况下，pnpm 将复制包而不是硬链接它们，因为硬链接只能发生在同一文件系统上。

verifyStoreIntegrity

默认值：true
类型：Boolean

默认情况下，如果存储中的文件已被修改，则在将其链接到项目的 node_modules 之前会检查该文件的内容。 If verifyStoreIntegrity is set to false, files in the content-addressable store will not be checked during installation.

useRunningStoreServer

警告

已弃用的功能

默认值： false
类型：Boolean

只允许使用存储服务器进行安装。如果没有在运行的存储服务器，安装将失败。

strictStorePkgContentCheck

默认值：true
类型：Boolean

一些注册源允许以不同的包名或版本，发布完全相同的内容。这破坏了存储中包的有效性检查。 To avoid errors when verifying the names and versions of such packages in the store, you may set the strictStorePkgContentCheck setting to false.

锁文件设置

lockfile

默认值：true
类型：Boolean

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

preferFrozenLockfile

默认值：true
类型：Boolean

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

lockfileIncludeTarballUrl

默认值： false
类型：Boolean

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

gitBranchLockfile

默认值： false
类型：Boolean

如果设置为 true，那么在安装后生成的锁文件名称将基于当前分支名称命名，以完全避免合并冲突。例如，如果当前分支名称为 feature-foo，则对应的锁文件名称将为 pnpm-lock.feature-foo.yaml 而不是 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

默认值： null
类型：Array 或 null

此配置匹配当前分支名称以确定是否合并所有 git 分支锁文件文件。默认情况下，你需要手动传递 --merge-git-branch-lockfiles 命令行参数。这项配置允许自动完成这个过程。

例如：

mergeGitBranchLockfilesBranchPattern:
- main
- release*

你还可以使用 ! 来排除模式。

peersSuffixMaxLength

默认值：1000
类型：number

添加到锁文件中的依赖项键的 peer ID 后缀的最大长度。如果后缀较长，则用井号替换。

注册源 & 身份验证设置

registry

默认值： .https://registry.npmjs.org/
类型：url

npm 包注册表的基准 URL（包括尾部斜杠）。

<scope>:registry

应用于指定范围的包的 npm 注册源。例如，设置 @babel:registry=https://example.com/packages/npm/ 将在你使用 pnpm add @babel/core 或任何 @babel 范围的包时，该包将强制从 https://example.com/packages/npm 而不是默认注册源中获取。

<URL>:_authToken

访问指定注册源时要使用的身份验证承载令牌。示例：

//registry.npmjs.org/:_authToken=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

您还可以使用环境变量。示例：

//registry.npmjs.org/:_authToken=${NPM_TOKEN}

或者，你可以在完全不更改 .npmrc 下直接使用环境变量：

npm_config_//registry.npmjs.org/:_authToken=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

<URL>:tokenHelper

令牌助手是输出身份验证令牌的可执行文件。这可以在 authToken 不是常量值而是定期刷新的情况中使用，其中脚本或其他工具可以使用现有的刷新令牌来获取新的访问令牌。

助手路径的配置必须是绝对路径，并且没有参数。为了安全起见，只允许在用户 .npmrc 中设置该值。否则，项目可以在项目的本地 .npmrc 中放置一个值并运行任意可执行文件。

为默认注册表设置令牌助手：

tokenHelper=/home/ivan/token-generator

为指定的注册表设置令牌助手：

//registry.corp.com:tokenHelper=/home/ivan/token-generator

请求设置

ca

默认值：npm CA 证书
类型：String，Array 或 null

可信的用于注册源 SSL 链接的 CA 签名证书。值应采用 PEM 格式（也称 “Base-64 encoded X.509 (.CER)”）。示例：

ca="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"

设置为 null 时仅允许已知注册商，若指定 CA 证书将只信任指定的证书颁发机构。

通过指定一个证书数组，可以信任多个 CA：

ca[]="..."
ca[]="..."

更多信息可见 strict-ssl 设置

cafile

默认值： null
类型：路径

包含一个或多个 CA 证书的文件路径。类似于 ca 设置，但允许多个CA，此外， CA 信息将存储在一个文件中，而不是通过 CLI 指定。

<URL>:CA文件

定义访问指定注册源时使用的证书颁发机构文件的路径。示例：

//registry.npmjs.org/:cafile=ca-cert.pem

cert

默认值： null
类型：字符串

访问注册源时传递的客户端证书。值应为 PEM 格式（也称 "Base-64 encoded X.509 (.CER)"）。示例：

cert="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"

这不是证书文件的路径。

<URL>:证书文件

定义访问指定注册源时使用的证书文件的路径。示例：

//registry.npmjs.org/:certfile=server-cert.pem

key

默认值： null
类型：字符串

访问注册源时要传递的客户端密钥。值应为 PEM 格式（也称 "Base-64 encoded X.509 (.CER)"）。示例：

key="-----BEGIN PRIVATE KEY-----\nXXXX\nXXXX\n-----END PRIVATE KEY-----"

它不是密钥文件的路径(也没有 keyfile 选项)。

此设置包含敏感信息。不要将其写入本地会提交到仓库的 .npmrc 文件。

<URL>:密钥文件

定义访问指定注册源时使用的客户端密钥文件的路径。示例：

//registry.npmjs.org/:keyfile=server-key.pem

gitShallowHosts

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

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

https-proxy

默认值： null
类型：url

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

如果您的代理 URL 包含用户名和密码，请确保对它们进行 URL 编码。例如：

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

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

http-proxy

proxy

默认值： null
类型：url

用于传出 http 请求的代理。如果设置了 HTTP_PROXY 或 http_proxy 环境变量，则底层请求库将遵循代理设置。

local-address

默认值：undefined
类型：IP 地址

连接到 npm 源时要使用的本地接口 IP 地址。

maxsockets

Default: networkConcurrency x 3
类型：Number

每个注册源（由协议/主机/端口号组合而成）允许的最大连接数。

noproxy

默认值： null
类型：字符串

一个由逗号分割的域名字符串，表示不应该被使用的代理

strict-ssl

默认值：true
类型：Boolean

通过 HTTPS 向源发出请求时是否进行 SSL 密钥验证。

另请参阅 ca 配置项。

networkConcurrency

默认值：16
类型：Number

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

fetchRetries

默认值：2
类型：Number

pnpm 无法从注册源中获取时的重试次数。

fetchRetryFactor

默认值：10
类型：Number

重试回退的指数因子。

fetchRetryMintimeout

默认值：10000（10 秒）
类型：Number

重试请求的最小（基本）超时。

fetchRetryMaxtimeout

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

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

fetchTimeout

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

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

Peer Dependency 设置

autoInstallPeers

默认值：true
类型：Boolean

当值为 true 时，将自动安装任何缺少的非可选对等依赖。

版本冲突

如果来自不同软件包的对等依赖项的需求版本存在冲突，那么 pnpm 将不会自动安装任何版本的冲突的对等依赖项。相反，会输出一条警告信息。比如，如果一个依赖项需要 react@^16.0.0，而另一个需要 react@^17.0.0，则会产生冲突，自动安装将不会进行。

解决冲突

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

dedupePeerDependents

默认值：true
类型：Boolean

当此设置为 true 时，对等依赖在对等解析后会被做去重处理。

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

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 实例。 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

什么是对等依赖冲突？我们指的对等依赖冲突是如下场景：

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 去重，因为 react 在 webpack 的对等依赖内，而在两个项目上下文环境中，react 版本不同。

strictPeerDependencies

默认值： false
类型：Boolean

如果启用了此选项，那么在依赖树中存在缺失或无效的对等依赖关系时，命令将执行失败。

resolvePeersFromWorkspaceRoot

默认值：true
类型：Boolean

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

peerDependencyRules

peerDependencyRules.ignoreMissing

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

例如，使用以下配置，如果依赖项需要 react 但 react 未被安装，pnpm 不会打印相应警告。

peerDependencyRules:
  ignoreMissing:
  - react

包名也可以使用模式匹配

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

peerDependencyRules.allowedVersions

对于指定版本范围的 peerDependency，将不会打印未满足版本范围的警告。

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

peerDependencyRules:
  allowedVersions:
    react: "17"

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

这还可以用来抑制指定包的对等依赖项引发的警告。例如，以下配置下 react v17 仅在其位于 button v2 包的对等依赖项中或任何 card 包的依赖项中时才被允许：

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

peerDependencyRules.allowAny

allowAny 是一个匹配包名的数组，任何匹配该模式的对等依赖将可被解析为任意版本，无论 peerDependencies 指定的范围如何。例如：

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

上述设置将禁用任何与 @babel/ 或 eslint 有关的对等依赖版本不匹配的警告。

命令行设置

[no-]color

默认值： auto
类型：auto、tcp、ipc

设置输出的颜色.

auto - 当标准输出是终端或 TTY 时，输出会带有颜色。
always - 忽略终端和 pipe 之间的区别。你很少需要这个选项；在大多数情况下，如果您想在重定向的输出中使用颜色代码，你可以将 --color 标志传递给 pnpm 命令以强制它输出颜色。大多数情况下只需要默认设置。
never - 关闭颜色. 这是 --no-color 使用的设置。

loglevel

默认值： auto
类型：debug、info、warn、error

将显示等于或高于给定级别的任何日志。你可以改为传递 --silent 来关闭所有输出日志。

useBetaCli

默认值： false
类型：Boolean

启用 CLI 测试版功能的实验性选项。这意味着你使用的 CLI 功能可能会有一些不兼容的更改或潜在错误的更改。

recursiveInstall

默认值：true
类型：Boolean

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

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

engineStrict

默认值： false
类型：Boolean

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

但无论该属性设置成什么值，如果项目（不是依赖项）在其 engines 字段中指定了不兼容的版本，则安装将始终失败。

npmPath

类型：路径

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

packageManagerStrict

默认值：true
类型：Boolean

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

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

packageManagerStrictVersion

默认值： false
类型：Boolean

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

managePackageManagerVersions

默认值：true
类型：Boolean

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

{
  "packageManager": "pnpm@9.3.0"
}

构建设置

ignoreScripts

默认值： false
类型：Boolean

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

注意

该标记不会阻止 .pnpmfile.cjs 的执行

ignoreDepScripts

默认值： false
类型：Boolean

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

注意

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

childConcurrency

默认值：5
类型：Number

为并行构建 node_modules 分配的最大子进程数。

sideEffectsCache

默认值：true
类型：Boolean

使用并缓存 (pre/post)install 钩子的结果。

sideEffectsCacheReadonly

默认值： false
类型：Boolean

仅在副作用缓存存在时使用，不要为新包创建它。

unsafePerm

默认值：如果以 root 身份运行，则为 false，否则为 true
类型：Boolean

设置为 true 以便在运行包脚本时启用 UID/GID 切换。如果显式设置为 false，则以非 root 用户身份安装将失败。

nodeOptions

默认值： NULL
类型：字符串

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

verifyDepsBeforeRun

默认值： false
类型：install、warn、error、prompt、false

此设置允许在运行脚本之前检查依赖项的状态。检查运行于 pnpm run 和 pnpm exec 命令。支持以下属性值:

install — 如果 node_modules 不是最新的，则自动运行安装。
warn - 如果 node_modules 不是最新的，则打印警告。
prompt - 如果 node_modules 不是最新的，则提示用户提供权限。
error - 如果 node_modules 不是最新的，则会引发错误。
false——禁用依赖性检查。

strictDepBuilds

添加于：v10.3.0

默认值： false
类型：Boolean

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

neverBuiltDependencies

此字段允许忽略特定依赖项的构建。安装期间不会执行所列包的 “preinstall”、“install” 和 “postinstall” 脚本。

An example of the neverBuiltDependencies field:

neverBuiltDependencies:
- fsevents
- level

onlyBuiltDependencies

允许在安装期间执行安装的包名列表。只有此数组中列出的包才能够运行安装脚本。如果未设置 onlyBuiltDependenciesFile 和 neverBuiltDependencies ，则此配置选项将默认阻止所有安装脚本。

示例：

onlyBuiltDependencies:
- fsevents

onlyBuiltDependenciesFile

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

示例：

configDependencies:
  "@my-org/policy": 1.0.0+sha512-30iZtAPgz+LTIYoeivqYo853f02jBYSd5uGnGpkFV0M3xOt9aN73erkgYAmZU43x4VfqcnLxW9Kpg3R5LC4YYw==
onlyBuiltDependenciesFile: node_modules/.pnpm-config/@my-org/policy/onlyBuiltDependencies.json

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

node_modules/@my-org/policy/onlyBuiltDependencies.json
[
  "fsevents"
]

ignoredBuiltDependencies

添加于：v10.1.0

安装期间不应构建的软件包名称列表。

示例：

ignoredBuiltDependencies:
- fsevents

dangerouslyAllowAllBuilds

Added in: v10.9.0

默认值： false
类型：Boolean

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

警告

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:

Future updates may introduce new, untrusted dependencies.
Existing packages may add scripts in later versions.
Packages can be hijacked or compromised and begin executing malicious code.

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 设置

useNodeVersion

默认值：undefined
类型：semver

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

这可以用来代替 .nvmrc 和 nvm。而不是以下 .nvmrc 文件：

16.16.0

Use this pnpm-workspace.yaml file:

useNodeVersion: 16.16.0

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 版本

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 的新依赖项。

node-mirror

默认值： https://nodejs.org/download/<releaseDir>/
类型：URL

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

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

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 命令。

示例：

executionEnv:
  nodeVersion: 16.16.0

工作空间设置

linkWorkspacePackages

默认值： false
类型：true、false、deep

启用该选项后，本地可用的软件包将被链接到 node_modules 中而不是从注册源下载。这在 monorepo 中非常方便。如果你需要本地包也链接到子依赖项，可以使用 deep 设置。

否则，将从注册源下载并安装软件包。然而，工作空间包仍然可以通过使用 workspace: 范围协议进行链接。

仅当软件包的版本满足依赖范围时，才会链接。

injectWorkspacePackages

默认值： false
类型：Boolean

启用所有本地工作区依赖项的硬链接，而不是符号链接它们。或者，可以使用 dependencyMeta[].injected 来实现，这允许有选择地为特定依赖项启用硬链接。

syncInjectedDepsAfterScripts

添加于：v10.5.0

默认值：undefined
类型：String[]

注入的工作区依赖项是硬链接的集合，当文件的源发生变化时，它们不会添加或删除文件。这会导致需要构建的包出现问题（例如在 TypeScript 项目中）。

此设置是脚本名称的列表。当这些脚本中的任何一个在工作区包中执行时，内部注入的依赖项 node_modules 也将同步。

preferWorkspacePackages

默认值： false
类型：Boolean

若启用了该选项，位于工作区的本地包将优先于注册表中的包，即使注册表中有存在更新的包。

This setting is only useful if the workspace doesn't use saveWorkspaceProtocol.

sharedWorkspaceLockfile

默认值：true
类型：Boolean

如果启用此选项，pnpm 会在工作空间的根目录中创建一个唯一的 pnpm-lock.yaml 文件。这也意味着工作区包的所有依赖项将位于单个“node_modules”中（并符号链接到它们的包“node_modules” 文件夹以进行 Node 的模块解析）。

此选项的好处：

每个依赖都是一个单例
在 monorepo 中的安装更快
代码更改都在一个文件中、代码审查减少

注意

尽管所有依赖项都将硬链接到根 node_modules 中，但软件包只能访问 package.json 中声明的，因此 pnpm 的严格性得以保留。这是前面提到的符号链接的结果。

saveWorkspaceProtocol

默认值：rolling
类型：true、false、rolling

这个设置控制从工作空间中链接的 dependencies 如何添加至 package.json。

如果 foo@1.0.0 在工作空间中，在工作空间的另一个项目中运行 pnpm add foo，则 foo 会被按如下方式添加到依赖项字段。 The savePrefix setting also influences how the spec is created.

saveWorkspaceProtocol	savePrefix	spec
false	`''`	`1.0.0`
false	`'~'`	`~1.0.0`
false	`'^'`	`^1.0.0`
true	`''`	`workspace:1.0.0`
true	`'~'`	`workspace:~1.0.0`
true	`'^'`	`workspace:^1.0.0`
rolling	`''`	`workspace:*`
rolling	`'~'`	`workspace:~`
rolling	`'^'`	`workspace:^`

includeWorkspaceRoot

默认值： false
类型：Boolean

在工作区中递归执行命令时，也在根工作区项目上执行它们。

ignoreWorkspaceCycles

默认值： false
类型：Boolean

当设置为 true 时，不会打印工作区循环警告。

disallowWorkspaceCycles

默认值： false
类型：Boolean

当设置为 true 时，如果工作区存在循环，安装将失败。

部署设置

forceLegacyDeploy

默认值： false
类型：Boolean

默认情况下， pnpm deploy 将尝试从共享锁文件创建专用锁文件以进行部署。如果此设置设为 true，则将使用旧的 deploy 行为。

Patching Dependencies

patchedDependencies

此字段会在你运行 pnpm patch-commit 时自动添加/更新。 It defines patches for dependencies using a dictionary where:

Keys: Package names with an exact version, a version range, or just the name.
Values: Relative paths to patch files.

示例：

patchedDependencies:
  express@4.18.1: patches/express@4.18.1.patch

Dependencies can be patched by version range. The priority order is:

Exact versions (highest priority)
Version ranges
Name-only patches (applies to all versions unless overridden)

A special case: the version range * behaves like a name-only patch but does not ignore patch failures.

Exampe:

patchedDependencies:
  foo: patches/foo-1.patch
  foo@^2.0.0: patches/foo-2.patch
  foo@2.1.0: patches/foo-3.patch

patches/foo-3.patch is applied to foo@2.1.0.
patches/foo-2.patch applies to all foo versions matching ^2.0.0, except 2.1.0.
patches/foo-1.patch applies to all other foo versions.

Avoid overlapping version ranges. If you need to specialize a sub-range, explicitly exclude it from the broader range.

示例：

patchedDependencies:
  # Specialized sub-range
  "foo@2.2.0-2.8.0": patches/foo.2.2.0-2.8.0.patch
  # General patch, excluding the sub-range above
  "foo@>=2.0.0 <2.2.0 || >2.8.0": patches/foo.gte2.patch

In most cases, defining an exact version is enough to override a broader range.

allowUnusedPatches

Added in: v10.7.0 (Previously named allowNonAppliedPatches)

默认值： false
类型：Boolean

当设置为 true 时，如果 patchedDependencies 字段中的某些补丁未被应用，安装不会失败。

patchedDependencies:
  express@4.18.1: patches/express@4.18.1.patch
allowUnusedPatches: true

ignorePatchFailures

Added in: v10.7.0

默认值：undefined
Type: Boolean, undefined

Controls how patch failures are handled.

Behaviour:

undefined (default):
- Errors out when a patch with an exact version or version range fails.
- Ignores failures from name-only patches.
false: Errors out for any patch failure.
true: Prints a warning instead of failing when any patch cannot be applied.

Audit Settings

auditConfig

auditConfig.ignoreCves

pnpm audit 命令将忽略的 CVE ID 列表。

auditConfig:
  ignoreCves:
    CVE-2022-36313

auditConfig.ignoreGhsas

pnpm audit 命令将忽略的 GHSA 代码列表。

auditConfig:
  ignoreGhsas:
    GHSA-42xw-2xvc-qx8m
    GHSA-4w2v-q235-vp99
    GHSA-cph5-m8f7-6c5x
    GHSA-vh95-rmgr-6w4m

其它设置

savePrefix

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

配置软件包在 package.json 文件中的版本前缀。

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

当添加的包具有指定的范围时，将忽略此设置。 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/store
- 在 Windows 上：~/AppData/Local/pnpm/store
- 在 macOS 上：~/Library/pnpm/global
- 在 Linux 上：~/.local/share/pnpm/global
类型：路径

指定储存全局依赖的目录。

globalBinDir

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

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

stateDir

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

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

cacheDir

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

缓存的位置（软件包元数据和 dlx）。

useStderr

默认值： false
类型：Boolean

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

updateNotifier

默认值：true
类型：Boolean

设置为 false 以便在使用较旧版本的 pnpm 时关闭更新通知。

preferSymlinkedExecutables

默认值：当 node-linker 设置为 hoisted 且系统为 POSIX 时为 true
类型：Boolean

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

ignoreCompatibilityDb

默认值： false
类型：Boolean

在安装过程中，某些包的依赖关系会被自动打补丁。如果你想禁用此功能，请将此配置设置为 false。

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

resolutionMode

默认值: highest (从 v8.0.0 到 v8.6.12 是 lowest-direct)
类型：highest、time-based、lowest-direct

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

直接依赖项将解析为最低版本。因此，如果依赖项中有 foo@^1.1.0 ，则将安装 1.1.0。
子依赖项将被解析的版本，是解析到最后一个直接依赖项发布的版本。

使用此解析模式的安装，具有热高速缓存的速度更快。它还减少了子依赖项劫持的机会，因为只有更新直接依赖项，子依赖项才会更新。

此解析模式仅适用于 npm 的完整元数据。因此，在某些场景中，速度较慢。 However, if you use Verdaccio v5.15.1 or newer, you may set the registrySupportsTimeField setting to true, and it will be really fast.

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

registrySupportsTimeField

默认值： false
类型：Boolean

如果你使用的注册表在缩略元数据中返回了 "time" 字段，请将此设置为 true。目前，只有 v5.15.1 版本以上的 Verdaccio 支持这一功能。

extendNodePath

默认值：true
类型：Boolean

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

deployAllFiles

默认值： false
类型：Boolean

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

dedupeDirectDeps

默认值： false
类型：Boolean

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

dedupeInjectedDeps

默认值：true
类型：Boolean

启用此设置后，注入的依赖项将尽可能从工作区进行符号链接。如果依赖项和注入的依赖项引用相同的对等依赖项，则无需将注入的依赖项物理复制到依赖项的 node_modules 中，符号链接就足够了。

optimisticRepeatInstall

添加于：v10.1.0

默认值：true
类型：Boolean

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

requiredScripts

工作区的每个项目，都必须含有此数组中的所有脚本。否则， pnpm -r run <script name> 将失败。

requiredScripts:
- build

Dependency Resolution​

overrides​

packageExtensions​

allowedDeprecatedVersions​

updateConfig​

updateConfig.ignoreDependencies​

支持的架构​

ignoredOptionalDependencies​

依赖提升设置​

hoist​

hoistWorkspacePackages​

hoistPattern​

publicHoistPattern​

shamefullyHoist​

Node 模块设置​

modulesDir​

nodeLinker​

symlink​

enableModulesDir​

virtualStoreDir​

virtualStoreDirMaxLength​

packageImportMethod​

modulesCacheMaxAge​

dlxCacheMaxAge​

存储设置​

storeDir​

verifyStoreIntegrity​

useRunningStoreServer​

strictStorePkgContentCheck​

锁文件设置​

lockfile​

preferFrozenLockfile​

lockfileIncludeTarballUrl​

gitBranchLockfile​

mergeGitBranchLockfilesBranchPattern​

peersSuffixMaxLength​

注册源 & 身份验证设置​

registry​

<scope>:registry​

<URL>:_authToken​

<URL>:tokenHelper​

请求设置​

ca​

cafile​

<URL>:CA文件​

cert​

<URL>:证书文件​

key​

<URL>:密钥文件​

gitShallowHosts​

https-proxy​

http-proxy​

proxy​

local-address​

maxsockets​

noproxy​

strict-ssl​

networkConcurrency​

fetchRetries​

fetchRetryFactor​

fetchRetryMintimeout​

fetchRetryMaxtimeout​

fetchTimeout​

Peer Dependency 设置​

autoInstallPeers​

版本冲突​

解决冲突​

dedupePeerDependents​

strictPeerDependencies​

resolvePeersFromWorkspaceRoot​

peerDependencyRules​

peerDependencyRules.ignoreMissing​

peerDependencyRules.allowedVersions​

peerDependencyRules.allowAny​

命令行设置​

[no-]color​

loglevel​

useBetaCli​

recursiveInstall​

engineStrict​