版本：10.x

配置 (pnpm-workspace.yaml)

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

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

依赖解析

overrides

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

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

overrides 字段的示例：

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

你可以通过使用 ">" 分隔包选择器和依赖选择器来指定被覆盖的依赖项所属的包。例如，qar@1>zoo 只会覆盖 qar@1 的 zoo 依赖项，而不会覆盖其他依赖项的 zoo。

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

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

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

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

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

如果你发现某个包的某个依赖项对你的使用来说是不必要的，你可以使用 - 来移除它。例如，如果包 foo@1.0.0 需要一个名为 bar 的大型包用于你不使用的功能，移除它可以减少安装时间：

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

这个功能对于 optionalDependencies 特别有用，因为大多数可选包都可以安全地跳过。

packageExtensions

packageExtensions 字段提供了一种方式来扩展现有包定义的附加信息。例如，如果 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/extensions 数据库。

allowedDeprecatedVersions

此设置允许禁止显示特定包的弃用警告。

示例：

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/*。

supportedArchitectures

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

例如，以下配置告诉系统为 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

当为 true 时，工作空间中的包会被符号链接到 <workspace_root>/node_modules/.pnpm/node_modules 或 <workspace_root>/node_modules，具体取决于其他提升设置（hoistPattern 和 publicHoistPattern）。

hoistPattern

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

告诉 pnpm 哪些包应该被提升到 node_modules/.pnpm/node_modules。默认情况下，所有包都会被提升 - 但是，如果你知道只有某些有缺陷的包有幻影依赖项，你可以使用此选项来专门提升这些幻影依赖项（推荐）。

例如：

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

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

例如：

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

publicHoistPattern

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

与 hoistPattern 不同，publicHoistPattern 会将匹配模式的依赖项提升到根模块目录，而不是隐藏在虚拟存储中。提升到根模块目录意味着应用代码将可以访问幻影依赖项，即使它们不正确地修改了解析策略。

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

例如：

publicHoistPattern:
- "*plugin*"

注意：将 shamefullyHoist 设置为 true 相当于将 publicHoistPattern 设置为 *。

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

例如：

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

shamefullyHoist

默认值：false
类型：Boolean

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

Node-Modules 设置

modulesDir

默认值：node_modules
类型：path

将安装依赖项的目录（而不是 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. 你的项目部署到无服务器托管提供商。一些无服务器提供商（例如 AWS Lambda）不支持符号链接。这个问题的另一个解决方案是在部署前打包你的应用。
3. 如果你想使用 ["bundledDependencies"] 发布你的包。
4. 如果你使用 [--preserve-symlinks] 标志运行 Node.js。
pnp - 没有 node_modules。Plug'n'Play 是 [Yarn Berry 使用的][pnp] 一种创新策略。当使用 pnp 作为链接器时，建议也将 symlink 设置设为 false。

symlink

默认值：true
类型：Boolean

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

enableModulesDir

默认值：true
类型：Boolean

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

virtualStoreDir

默认值：node_modules/.pnpm
类型：path

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

这是一个有用的设置，可以解决 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-or-copy

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

auto - 尝试从存储中克隆包。如果不支持克隆，则从存储中硬链接包。如果克隆和链接都不可能，则回退到复制
hardlink - 从存储中硬链接包
clone-or-copy - 尝试从存储中克隆包。如果不支持克隆，则回退到复制
copy - 从存储中复制包
clone - 克隆（即写时复制或引用链接）包从存储中

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

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

modulesCacheMaxAge

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

模块目录中孤儿包被删除的时间，单位为分钟。 pnpm 在模块目录中保留一个包的缓存。这在切换分支或降级依赖项时可以加快安装速度。

dlxCacheMaxAge

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

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

存储设置

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
类型：path

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

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

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

verifyStoreIntegrity

默认值：true
类型：Boolean

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

useRunningStoreServer

危险

已弃用的功能

默认值：false
类型：Boolean

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

strictStorePkgContentCheck

默认值：true
类型：Boolean

某些注册表允许将完全相同的内容发布到不同的包名称和/或版本下。这会破坏存储中包的有效性检查。为了避免在验证存储中此类包的名称和版本时出现错误，可以将 strictStorePkgContentCheck 设置为 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。它通常与命令行参数 --merge-git-branch-lockfiles 一起使用，或通过设置 mergeGitBranchLockfilesBranchPattern 在 pnpm-workspace.yaml 文件中使用。

mergeGitBranchLockfilesBranchPattern

默认值：null
类型：Array 或 null

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

例如：

mergeGitBranchLockfilesBranchPattern:
- main
- release*

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

peersSuffixMaxLength

默认值：1000
类型：number

添加到锁定文件中依赖项键的对等 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

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

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

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

tokenHelper=/home/ivan/token-generator

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

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

请求设置

ca

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

用于信任与注册表的 SSL 连接的证书颁发机构签名证书。值应为 PEM 格式（即 "Base-64 编码的 X.509 (.CER)"）。例如：

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

设置为 null 仅允许已知的注册机构，或设置为特定的 CA 证书，仅信任该特定签名机构。

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

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

另请参见 strict-ssl 配置。

cafile

默认值：null
类型：path

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

<URL>:cafile

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

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

cert

默认值：null
类型：String

访问注册表时传递的客户端证书。值应为 PEM 格式（即 "Base-64 编码的 X.509 (.CER)"）。例如：

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

这不是证书文件的路径。

<URL>:certfile

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

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

key

默认值：null
类型：String

访问注册表时传递的客户端密钥。值应为 PEM 格式（即 "Base-64 编码的 X.509 (.CER)"）。例如：

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

这不是密钥文件的路径（也没有 keyfile 选项）。

此设置包含敏感信息。请勿将其写入提交到存储库的本地 .npmrc 文件中。

<URL>:keyfile

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

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

gitShallowHosts

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

在获取依赖项时，如果主机在此设置中列出，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

默认值：networkConcurrency x 3
类型：Number

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

noproxy

默认值：null
类型：String

代理不应使用的域名后缀的逗号分隔字符串。

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 请求完成的最长时间。

对等依赖设置

autoInstallPeers

默认值：true
类型：Boolean

当 true 时，自动安装任何缺失的非可选对等依赖项。

版本冲突

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

冲突解决

在发生版本冲突的情况下，你需要自行评估要安装哪个对等依赖项的版本，或更新依赖项以对齐它们的对等依赖要求。

dedupePeerDependents

默认值：true
类型：Boolean

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

例如，假设我们有一个包含两个项目的工作区，并且它们都有 webpack 在它们的依赖项中。webpack 在其可选对等依赖项中有 esbuild，而其中一个项目在其依赖项中有 esbuild。在这种情况下，pnpm 将在 node_modules/.pnpm 目录中链接两个实例的 webpack：一个带有 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 实例。因此，你现在可以使用 dedupePeerDependents 设置在没有冲突的对等依赖项时去重 webpack（详见后文）。在这种情况下，如果我们将 dedupePeerDependents 设置为 true，两个项目将使用相同的 webpack 实例，即带有解析的 esbuild 的那个：

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，因为 webpack 在其对等依赖项中有 react，并且 react 在两个项目的上下文中解析为两个不同的版本。

strictPeerDependencies

默认值：false
类型：Boolean

如果启用，则如果树中缺少或对某个对等依赖项无效，将导致命令失败。

resolvePeersFromWorkspaceRoot

默认值：true
类型：Boolean

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

peerDependencyRules

peerDependencyRules.ignoreMissing

pnpm 将不会打印关于缺失的对等依赖项的警告，这些依赖项在此列表中。

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

peerDependencyRules:
  ignoreMissing:
  - react

也可以使用包名称模式：

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

peerDependencyRules.allowedVersions

未满足的对等依赖警告将不会打印出指定范围的对等依赖项。

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

peerDependencyRules:
  allowedVersions:
    react: "17"

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

也可以仅对特定包的对等依赖项抑制警告。例如，使用以下配置，当 button v2 包的对等依赖项中或任何 card 包的依赖项中包含 react 时，仅允许 react v17：

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

peerDependencyRules.allowAny

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

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

上述设置将抑制与 @babel/ 包或 eslint 相关的对等依赖项版本不匹配的任何警告。

CLI 设置

[no-]color

默认值：auto
类型：auto, always, never

控制输出中的颜色。

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

loglevel

默认值：info
类型：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

类型：path

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

packageManagerStrict

默认值：true
类型：Boolean

如果此设置被禁用，当 package.json 的 packageManager 字段中指定了不同的包管理器时，pnpm 不会失败。从 pnpm v9.2.0 开始，仅检查包名称，因此你仍然可以运行任何版本的 pnpm，而不管在 packageManager 字段中指定的版本。

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

packageManagerStrictVersion

默认值：false
类型：Boolean

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

managePackageManagerVersions

默认值：true
类型：Boolean

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

{
  "packageManager": "pnpm@9.3.0"
}

构建设置

ignoreScripts

默认值：false
类型：Boolean

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

备注

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

ignoreDepScripts

默认值：false
类型：Boolean

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

备注

自 v10 起，pnpm 不会运行依赖项的生命周期脚本，除非它们在 onlyBuiltDependencies 中列出。

childConcurrency

默认值：5
类型：Number

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

sideEffectsCache

默认值：true
类型：Boolean

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

sideEffectsCacheReadonly

默认值：false
类型：Boolean

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

unsafePerm

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

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

nodeOptions

默认值：NULL
类型：String

通过 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

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

neverBuiltDependencies

此字段允许忽略特定依赖项的构建。列出的包的 "preinstall"、"install" 和 "postinstall" 脚本将在安装过程中不会被执行。

neverBuiltDependencies 字段的示例：

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

自 v10.9.0 起新增

默认值：false
类型：Boolean

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

注意

此设置允许所有依赖项（包括传递依赖项）现在和将来都运行安装脚本。即使你当前的依赖关系图看起来是安全的：

将来更新可能会引入新的、不受信任的依赖项。
现有包可能会在以后的版本中添加脚本。
包可能会被劫持或损坏，开始执行恶意代码。

出于最大安全考虑，只有在你完全了解风险并信任你所拉取的整个生态系统时，才启用此选项。建议显式审核和允许构建。

Node.js 设置

useNodeVersion

默认值：undefined
类型：semver

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

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

16.16.0

使用此 pnpm-workspace.yaml 文件：

useNodeVersion: 16.16.0

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

nodeVersion

默认值：由 node -v 返回的值，无前缀 v
类型：semver

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

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

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，而不是从注册表下载。在单一仓库中这非常方便。如果你需要本地包也链接到子依赖项，可以使用 deep 设置。

否则，将从注册表下载和安装包。然而，工作区包仍然可以通过使用 workspace: 范围协议进行链接。

仅当它们的版本满足依赖关系范围时，才会链接包。

injectWorkspacePackages

默认值：false
类型：Boolean

启用所有本地工作区依赖项的硬链接，而不是符号链接。或者，可以通过 dependenciesMeta[].injected 来选择性地启用特定依赖项的硬链接。

syncInjectedDepsAfterScripts

自 v10.5.0 起新增

默认值：undefined
类型：String[]

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

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

preferWorkspacePackages

默认值：false
类型：Boolean

如果启用，本地工作区中的包将优先于注册表中的包，即使注册表中有更新版本的包。

此设置仅在工作区不使用 saveWorkspaceProtocol 时有用。

sharedWorkspaceLockfile

默认值：true
类型：Boolean

如果启用，pnpm 会在工作区的根目录创建一个单一的 pnpm-lock.yaml 文件。这也意味着工作区包的所有依赖项都将在单一的 node_modules 中，并被符号链接到它们的包 node_modules 文件夹中，以便 Node 的模块解析。

此选项的优点：

每个依赖项都是单例
在单一仓库中安装更快
代码审查中的更改更少，因为它们都在一个文件中

备注

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

saveWorkspaceProtocol

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

此设置控制从工作区链接的依赖项如何添加到 package.json 中。

如果 foo@1.0.0 在工作区中，并且你在工作区的另一个项目中运行 pnpm add foo，则 foo 将如何添加到依赖项字段中。savePrefix 设置也会影响规范的创建。

saveWorkspaceProtocol	savePrefix	规范
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 行为。

修补依赖项

patchedDependencies

此字段在你运行 pnpm patch-commit 时自动添加/更新。它使用字典定义依赖项的补丁，其中：

键：包名称，带确切版本、版本范围或仅名称。
值：补丁文件的相对路径。

示例：

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

依赖项可以按版本范围修补。优先顺序如下：

确切版本（最高优先级）
版本范围
仅按名称修补（适用于除非被覆盖的所有版本）

特例：版本范围 * 的行为类似于仅按名称修补，但不忽略补丁失败。

示例：

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 应用于 foo@2.1.0。
patches/foo-2.patch 应用于所有与 ^2.0.0 匹配的 foo 版本，但不包括 2.1.0。
patches/foo-1.patch 应用于所有其他 foo 版本。

避免重叠的版本范围。如果你需要专业化一个子范围，请显式排除它。

示例：

patchedDependencies:
  # 专业化子范围
  "foo@2.2.0-2.8.0": patches/foo.2.2.0-2.8.0.patch
  # 一般补丁，排除上述子范围
  "foo@>=2.0.0 <2.2.0 || >2.8.0": patches/foo.gte2.patch

在大多数情况下，定义确切版本就足以覆盖更广泛的范围。

allowUnusedPatches

自 v10.7.0 起新增（之前称为 allowNonAppliedPatches）

默认值：false
类型：Boolean

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

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

ignorePatchFailures

自 v10.7.0 起新增

默认值：undefined
类型：Boolean, undefined

控制补丁失败的处理方式。

行为：

undefined（默认）：
- 当确切版本或版本范围的补丁失败时出错。
- 忽略仅按名称补丁的失败。
false：对于任何补丁失败都出错。
true：当任何补丁无法应用时，打印警告而不是失败。

审计设置

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，这仅允许补丁升级。

当添加的包具有指定范围时，此设置将被忽略。例如，pnpm add foo@2 将把 foo 的版本设置为 2，而不管 savePrefix 的值。

globalDir

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

指定存储全球包的自定义目录。

globalBinDir

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

允许设置全球安装的包的二进制文件的目标目录。

stateDir

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

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

cacheDir

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

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

useStderr

默认值：false
类型：Boolean

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

updateNotifier

默认值：true
类型：Boolean

设置为 false 以抑制使用较旧版本的 pnpm 时的更新通知。

preferSymlinkedExecutables

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

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

ignoreCompatibilityDb

默认值：false
类型：Boolean

安装时，某些包的依赖项会自动修补。如果你想禁用此功能，请将此配置设置为 false。

补丁来自 Yarn 的 @yarnpkg/extensions 包。

resolutionMode

默认值：highest（在 v8.0.0 到 v8.6.12 中为 lowest-direct）
类型：highest, time-based, lowest-direct

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

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

使用此解析模式时，温暖缓存的安装速度更快。它还减少了子依赖项劫持的可能性，因为子依赖项仅在直接依赖项更新时才会更新。

此解析模式仅适用于 npm 的 full metadata。因此，在某些情况下，它的速度较慢。然而，如果你使用的是 Verdaccio v5.15.1 或更高版本，你可以将 registrySupportsTimeField 设置为 true，它将非常快。

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

registrySupportsTimeField

默认值：false
类型：Boolean

如果你使用的注册表在缩略元数据中返回 "time" 字段，则将此设置为 true。到目前为止，只有来自 v5.15.1 的 Verdaccio 支持这一点。

extendNodePath

默认值：true
类型：Boolean

当 false 时，命令 shim 中不设置 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

依赖解析​

overrides​

packageExtensions​

allowedDeprecatedVersions​

updateConfig​

updateConfig.ignoreDependencies​

supportedArchitectures​

ignoredOptionalDependencies​

依赖项提升设置​

hoist​

hoistWorkspacePackages​

hoistPattern​

publicHoistPattern​

shamefullyHoist​

Node-Modules 设置​

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>:cafile​

cert​

<URL>:certfile​

key​

<URL>:keyfile​

gitShallowHosts​

https-proxy​

http-proxy​

proxy​

local-address​

maxsockets​

noproxy​

strict-ssl​

networkConcurrency​

fetchRetries​

fetchRetryFactor​

fetchRetryMintimeout​

fetchRetryMaxtimeout​

fetchTimeout​

对等依赖设置​

autoInstallPeers​

版本冲突​

冲突解决​

dedupePeerDependents​

strictPeerDependencies​

resolvePeersFromWorkspaceRoot​

peerDependencyRules​

peerDependencyRules.ignoreMissing​

peerDependencyRules.allowedVersions​

peerDependencyRules.allowAny​

CLI 设置​

[no-]color​

loglevel​

useBetaCli​

recursiveInstall​

engineStrict​