版本：11 & 12

其它设置

savePrefix

默认值：'^'
Type: '^', '~', '', '='

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

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

Since v11.19.0, = is also accepted: newly added dependencies are saved with an explicit = operator (=1.2.3), which pins the exact version. pnpm update keeps the = operator when it updates such a pin.

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

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

Added in: v12.0.0-rc.2

Default: { node: auto, deno: auto, bun: auto }
Type: Boolean, Object

Controls which globally installed packages get project-aware shims — global commands that run the version the current project asks for instead of the globally installed one.

The setting is a map from package name to policy. The key is the name of the package that provides the command, not the command itself, so an entry for typescript covers its tsc bin.

globalShims:
  node: auto
  deno: false
  typescript: prompt

The supported policies are:

Value	行为
`auto` (or `true`)	Switch automatically when the candidate is authenticated by a publisher signature; otherwise ask for confirmation once.
`prompt`	Put every candidate through the confirmation gate, including signature-verified ones. Answers are still remembered, so this asks once per project and candidate, not on every run.
`always`	Always switch, never ask. Usable in CI, where a prompt would fall back to the global version.
`false`	Disable the project-aware shim for this package.

Since v12.0.0-rc.6, two commands write entries here for you: pnpm shim add <pkg> records the package it links a shim for, and installing a package manager globally (pnpm add -g yarn) records that package manager so it follows a project's pin. Neither overwrites an entry you set yourself — including false, and including a globalShims: false that turns every shim off.

Layers merge key by key over the built-in defaults, so a single entry can change one package without restating the rest — globalShims: { bun: false } leaves node and deno at auto.

The scalar shorthands replace the whole map instead of merging: globalShims: false disables every project-aware shim, and globalShims: true resets to the defaults.

注意

This setting is only read from locations a project cannot write to: the global configuration file, a pnpm-workspace.yaml in the pnpm home directory itself, and the PNPM_CONFIG_GLOBAL_SHIMS environment variable (a JSON value), applied in that order. A project's own pnpm-workspace.yaml is ignored — otherwise a repository could grant itself the right to run its own binaries in place of your global ones.

Disabling a package, or changing its policy, takes effect on the very next command — the setting is re-read on each dispatch, so no reinstall is needed.

Newly enabling a package is the exception. pnpm decides at install time which bins to write dispatching shims for, so a package that was already installed globally while it was disabled needs to be reinstalled to pick up the change:

pnpm add -g typescript

To bypass dispatch for a single invocation, set PNPM_SHIM_BYPASS=1:

PNPM_SHIM_BYPASS=1 node --version

备注

Project-aware shims are a pnpm v12 feature and are not available in 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 时，直接依赖项将解析为其最低版本。

Only the dependencies declared in package.json count as direct here. A peer dependency that autoInstallPeers adds is not something the project declared, so it is resolved like a subdependency: to the highest version satisfying the peer range, or under time-based, to the highest version within the publish-date cutoff.

registrySupportsTimeField

默认值： false
类型：Boolean

如果你使用的注册表在缩略元数据中返回了 "time" 字段，请将此设置为 true。 Verdaccio supports this from v5.15.1, as do some registry proxies.

Since v11.23.0, this can also be declared per registry, through the supportsTimeField field of a registry declaration. A registry's own declaration wins; this setting is the answer for every registry the project does not describe.

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

添加于：v10.12.1

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

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

catalogPrune

Added in: v11.22.0 (as cleanupUnusedCatalogs since v10.15.0)

默认值： false
类型：Boolean

当设置为 true 时，pnpm 将在安装期间删除未使用的目录条目。

cleanupUnusedCatalogs is the deprecated spelling of this setting and continues to work; when both are set, catalogPrune wins.

savePrefix​

tag​

globalDir​

globalBinDir​

globalShims​

npmrcAuthFile​

stateDir​

cacheDir​

useStderr​

updateNotifier​

preferSymlinkedExecutables​

ignoreCompatibilityDb​

resolutionMode​

registrySupportsTimeField​

extendNodePath​

为什么需要这样做​

何时禁用​

deployAllFiles​

dedupeDirectDeps​

optimisticRepeatInstall​

requiredScripts​

enablePrePostScripts​

scriptShell​

shellEmulator​

catalogMode​

ci​

catalogPrune​