其它设置

savePrefix#

默认值：'^'
类型：‘^'、'~'、"、'='

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

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

自 v11.19.0 起，= 也被接受：新添加的依赖会以显式的 = 符号保存（=1.2.3），它固定到确切的版本上。 pnpm update 在更新这种固定时会保留 = 符号。

当添加的包具有指定的范围时，将忽略此设置。例如，pnpm add foo@2 将会把 package.json 中的 foo 设置为 2，而忽略 save-prefix 的值。

tag#

默认值：latest
类型：字符串

如果你执行 pnpm add 添加了一个包并且没有提供特定版本，那么它安装设置中这个标记下的版本。

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

globalDir#

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

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

globalBinDir#

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

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

提示

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

globalShims#

添加于：v12.0.0-rc.2

默认值：{ node: auto, deno: auto, bun: auto }
类型：Boolean，Object

决定哪些全局安装的包获得项目感知填充程序 — 也就是运行当前项目所需版本、而非全局安装版本的全局命令。

该设置是一个从包名到策略的映射。键是提供该命令的包名称，而非命令本身，因此为 typescript 设置的条目会覆盖它的 tsc 可执行文件。

globalShims:
  node: auto
  deno: false
  typescript: prompt

支持的策略包括：

值	行为
`auto`（或 `true`）	若候选项已通过发布者签名验证，则自动切换；否则需要确认一次。
`prompt`	所有候选项都要经过确认环节，包括已通过签名验证的候选项。回答会被记住，因此对每个项目与每个候选项只会询问一次，而不会在每次运行时都询问。
`always`	总是切换，从不询问。适用于 CI，因为在那里出现提示会回退到全局版本。
`false`	对该包禁用项目感知填充程序。

自 v12.0.0-rc.6 起，有两个命令会替你写入条目：pnpm shim add <pkg> 记录它为其链接填充程序的包，而全局安装包管理器（pnpm add -g yarn）会记录该包管理器，使其遵循项目的固定版本。二者都不会覆盖你自己设置的条目 — 包括 false，也包括用于关闭所有填充程序的 globalShims: false。

各层会逐键合并到内置默认值之上，因此单个条目就能改变一个包而无需重述其余部分 — globalShims: { bun: false } 会让 node 和 deno 保持 auto。

标量简写不会合并，而是替换整个映射：globalShims: false 会禁用所有项目感知填充程序，globalShims: true 则恢复为默认值。

警告

该设置仅从项目无法写入的位置读取：全局配置文件、pnpm 主目录中的 pnpm-workspace.yaml，以及 PNPM_CONFIG_GLOBAL_SHIMS 环境变量（一个 JSON 值），并按该顺序应用。项目自有的 pnpm-workspace.yaml 会被忽略 — 否则某个仓库就可能让自己有权用其自身的可执行文件替换你的全局可执行文件。

禁用某个包或更改其策略，会在下一条命令立即生效 — 每次调度都会重新读取该设置，因此无需重新安装。

而新启用某个包则属于例外。 pnpm 在安装时决定为哪些可执行文件写入调度填充程序，因此若某个包在被禁用期间就已全局安装，需要重新安装才能应用这一变更：

pnpm add -g typescript

若要在单次调用中绕过调度，请设置 PNPM_SHIM_BYPASS=1：

PNPM_SHIM_BYPASS=1 node --version

注意

项目感知填充程序属于 pnpm v12 的功能，v11 中不可用。

npmrcAuthFile#

添加于：v11.0.0

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

包含注册源身份验证令牌的文件路径。默认情况下，pnpm 从 ~/.npmrc 读取身份验证令牌作为注册源身份验证的备用方案。使用此设置来指向不同的文件。

此设置无法在项目级的 pnpm-workspace.yaml 中配置；请在全局配置文件中，或通过 --npmrc-auth-file 命令行选项，又或是通过 PNPM_CONFIG_NPMRC_AUTH_FILE 环境变量进行设置（系统也会兼容 npm 风格的 NPM_CONFIG_USERCONFIG 作为备选）。相对路径是相对于工作目录进行解析的。

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 缓存以及部分安装验证结果）。

与存储一样，缓存目录仅供相互信任的用户、作业和进程共享。如果你配置或恢复了共享的 cacheDir，请通过文件系统权限对其进行保护，以防止不受信任的用户向其写入数据。

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

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

这些补丁是从 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 的完整元数据。因此，在某些场景中，速度较慢。但是，如果你使用 Verdaccio v5.15.1 或更高版本，则可以将 registrySupportsTimeField 设置为 true，速度会非常快。

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

在此，只有 package.json 中声明的依赖才被视为直接依赖。由 autoInstallPeers 添加的 peer 依赖并非项目声明的依赖，因此会像子依赖那样解析：解析到满足 peer 范围的最高版本；在 time-based 模式下则解析到发布日期截止范围内最高的版本。

registrySupportsTimeField#

默认值： false
类型：Boolean

如果你使用的注册表在缩略元数据中返回了 "time" 字段，请将此设置为 true。 Verdaccio 从 v5.15.1 起支持此功能，某些注册源代理亦如此。

自 v11.23.0 起，也可以通过注册源声明中的 supportsTimeField 字段按注册源进行声明。注册源自身的声明优先；而项目未描述的所有注册源均以此设置为准。

extendNodePath#

默认值：true
类型：Boolean

当为 true 时，pnpm 会在命令 shims 中设置 NODE_PATH 环境变量（在 node_modules/.bin 中创建的包装脚本）。当 false 时，NODE_PATH 未设置。

为什么需要这样做#

pnpm 的[孤立的 node_modules 布局]意味着包只能访问其声明的依赖关系。但是，当 CLI 工具通过命令 shim 运行时，一些库（特别是 import-local，被 jest、eslint 等使用）会从当前工作目录而不是从二进制文件自身的位置解析模块。因为工作目录是项目根，而不是虚拟存储里面的包 —— 标准的自工作目录的 node_modules 解析并不会找出二进制的传递依赖关系。

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

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

当启用 enableGlobalVirtualStore 时，NODE_PATH 也至关重要。使用全局虚拟存储时，软件包是从项目外部的中央位置进行符号链接的，因此 Node.js 从二进制文件的实际路径向上遍历 node_modules 的标准方法不会到达项目自己的 node_modules 或其提升的依赖项。在这种情况下，NODE_PATH 必须包含项目的根 node_modules，以及在 node_modules/.pnpm/node_modules 的提升目录以确保解析正确。

何时禁用#

如果你确定你的项目中没有一个 CLI 工具从工作目录解析模块，且你没有使用全局虚拟存储，你可以将其设置为 false 。禁用它后，指令垫片会稍微简单一些。

deployAllFiles#

默认值： false
类型：Boolean

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

dedupeDirectDeps#

默认值： false
类型：Boolean

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

optimisticRepeatInstall#

添加于：v10.1.0

默认值：true
类型：Boolean

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

requiredScripts#

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

requiredScripts:
- build

enablePrePostScripts#

默认值：true
类型：Boolean

当 true 时，pnpm 将自动运行任何前/后脚本。因此运行 pnpm foo 将类似于运行 pnpm prefoo pnpm foo pnpm postfoo。

scriptShell#

默认值： null
类型：路径

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

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

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

shellEmulator#

默认值： false
类型：Boolean

当为 true 时，pnpm 将使用 [类 bash shell][bash-like shell] 的 JavaScript 实现来执行脚本。

该选项简化了跨平台运行脚本。例如，默认情况下，下述脚本将在非 POSIX 标准兼容系统下运行失败：

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

但是，如果 shellEmulator 设置为 true，它将适用于所有平台。

注意

Node.js 22 或更高版本支持在没有 pnpm 帮助的情况下运行脚本。对于上面的例子，你可以使用“node --run test”运行“test”脚本。但是，shellEmulator 选项对此没有影响。依赖 POSIX 特性的脚本需要运行 pnpm run 而不是node --run 才能在不兼容 POSIX 的环境中工作。

catalogMode#

添加于：v10.12.1

默认值： manual
类型：manual、strict、prefer

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

strict - 仅允许来自目录的依赖版本。在目录版本范围之外添加依赖关系会导致错误。
prefer - 优先使用目录版本，但如果未找到兼容版本，则会退回到直接依赖项。
manual（默认）——不会自动将依赖项添加到目录中。

ci#