其它设置

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 添加了一个包并且没有提供特定版本，那么它安装设置中这个标记下的版本。

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 配置。

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
- On macOS and Linux: ~/.local/state/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。

The patches are applied from Yarn's @yarnpkg/extensions package, plus pnpm's own curated entries.

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。
Subdependencies will be resolved from versions that were published no later than one hour after the newest direct dependency. If none of those versions satisfies a subdependency's range, pnpm installs the lowest version that does.

If minimumReleaseAge is also set, pnpm resolves subdependencies against whichever of the two cutoffs is earlier. If no version published before that cutoff satisfies a subdependency's range, pnpm installs the lowest matching version that is older than the minimumReleaseAge cutoff. If every matching version is newer than the minimumReleaseAge cutoff, pnpm falls back to the lowest matching version, and minimumReleaseAgeStrict decides whether pnpm installs it or fails. Only the minimumReleaseAge cutoff decides which versions pnpm reports as too new. A version that is newer than the time-based cutoff but older than the minimumReleaseAge cutoff is installed without a warning or error.

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

此解析模式仅适用于 npm 的完整元数据。因此，在某些场景中，速度较慢。但是，如果你使用 Verdaccio v5.15.1 或更高版本，则可以将 registrySupportsTimeField 设置为 true，速度会非常快。

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

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 等使用）会从当前工作目录而不是从二进制文件自身的位置解析模块。 Since the working directory is the project root, not the package inside the virtual store, the standard node_modules resolution from the CWD won't find the binary's transitive dependencies.

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

The package's own dependencies directory (e.g., .pnpm/pkg@version/node_modules). This allows CWD-based resolution to find the correct versions of the package's sibling dependencies.
The hoisted node_modules directory (e.g., .pnpm/node_modules). This is the directory where hoisted packages are placed when hoistPattern is set. Node.js 无法通过其标准解析算法发现此目录，因此必须通过 NODE_PATH 提供。

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

Since v11.28.0, when a project uses a custom modulesDir, NODE_PATH also includes that directory, so a tool installed there can load CommonJS plugins installed next to it, the way it would from node_modules. When executables are symlinks (with preferSymlinkedExecutables or the hoisted linker), this applies to pnpm run, pnpm exec, pnpm version hooks, and the lifecycle scripts a project runs during install, but not to a symlinked tool started directly from a shell. A path that contains the platform's path-list separator (: or ;) does not get this fallback.

何时禁用#

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

deployAllFiles#

默认值： false
类型：Boolean

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

dedupeDirectDeps#

默认值： false
类型：Boolean

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

optimisticRepeatInstall#

添加于：v10.1.0

默认值：true
类型：Boolean

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

When the check finds that nothing changed, pnpm skips the install, including the projects' own lifecycle scripts, such as prepare. Set this to false to run those scripts on every install.

requiredScripts#

Scripts listed in this array are required in each project selected by pnpm -r run <script name>. Otherwise, the run fails.

pnpm-workspace.yaml

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"

Since v11.26.0, a relative path in pnpm-workspace.yaml resolves from the workspace root, including for scripts that run in a nested package. A bare command name such as bash is still looked up on PATH.

shellEmulator#

默认值： false
类型：Boolean

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

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

package.json

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

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

Since v11.28.1, a configured non-empty scriptShell wins over shellEmulator for pnpm run and lifecycle scripts. The emulator runs only when scriptShell is unset or empty.

注意

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（默认）——不会自动将依赖项添加到目录中。

Since v11.26.0, a specifier that names a location rather than a version is never moved into a catalog: local paths, local tarballs, tarball URLs, and workspace:<path> ranges stay in the package.json that declares them. Such a specifier is resolved relative to its own project, so one catalog entry could not mean the same directory for every project that references it.

ci#