跳到主内容
版本：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 的值。

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

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，依赖关系将按以下方式解析：

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

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

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

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

registrySupportsTimeField​

  • 默认值： false
  • 类型：Boolean

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

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 中包含了两种类型的路径：

  1. 软件包自身的依赖目录（例如， .pnpm/pkg@version/node_modules）——这允许基于当前工作目录的解析找到软件包的同级依赖项的正确版本。
  2. 提升的 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（持续集成）环境。

cleanupUnusedCatalogs​

添加于：v10.15.0

  • 默认值： false
  • 类型：Boolean

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