跳到主内容
版本：11 & 12

Store & Lockfile Settings

存储设置​

storeDir​

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

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

该存储应始终位于进行安装的同一磁盘上，因此每个磁盘将有一个存储。 如果在使用磁盘中具有主目录，存储目录就会创建在这里。 如果磁盘上没有主目录，那么将在文件系统的根目录中创建该存储。 例如，如果安装发生在挂载在 /mnt 的文件系统上，那么存储将在 /mnt/.pnpm-store 处创建。 Windows 系统上也是如此。

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

important

pnpm 存储旨在仅供相互信任的用户、作业和进程共享。 如果配置了共享的 storeDir，请通过文件系统权限对其进行保护，以防止不受信任的用户向其写入数据。 该存储属于 pnpm 的信任域：其中的包可以通过硬链接方式引用，且存储索引文件（index.db）记录了用于验证缓存文件的哈希值。

verifyStoreIntegrity​

  • 默认值：true
  • 类型：Boolean

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

此设置有助于检测意外的存储损坏。 这并不能使一个可由不受信任用户写入的存储变得安全，因为能够向该存储写入数据的攻击者既可以篡改缓存的软件包内容，也可以篡改用于验证这些内容的元数据。

useRunningStoreServer​

警告

已弃用的功能

  • 默认值： false
  • 类型：Boolean

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

strictStorePkgContentCheck​

  • 默认值：true
  • 类型：Boolean

一些注册源允许以不同的包名或版本，发布完全相同的内容。 这破坏了存储中包的有效性检查。 为了避免在存储中验证此类软件包的名称和版本时出现错误，你可以将 strictStorePkgContentCheck 设置设为 false。

frozenStore​

添加于：v11.7.0

  • 默认值： false
  • 类型：Boolean

允许 pnpm install 在位于只读文件系统（例如 Nix 存储、只读绑定挂载或 OCI 镜像层）上的包存储中运行。 启用该功能后，pnpm 会以不可变模式打开存储目录中的 SQLite index.db 文件（从而绕过 WAL/-shm 辅助文件，因为这些文件无法在只读目录下创建），并禁用所有会向存储目录执行写入操作的代码路径。

将其与 --offline 和 --frozen-lockfile 结合使用，并针对已完全填充的存储进行操作：

pnpm install --frozen-store --offline --frozen-lockfile

该存储必须已包含安装过程所需的一切，包括任何生命周期脚本已获批准（或已应用补丁）的包的构建产物。 Under the global virtual store, those package directories live inside the store, so if a required build is missing the install fails up front with ERR_PNPM_FROZEN_STORE_NEEDS_BUILD — seed the store with those builds first. 如果存储完全缺失内容目录，安装过程会立即失败并报错 ERR_PNPM_FROZEN_STORE_INCOMPLETE，而不会尝试对其进行初始化。

frozenStore 与 --force 以及已配置的 pnpr 服务器不兼容，因为它们都会向存储中写入数据。 The side effects cache is not written either.

注意

以只读模式打开存储需要 Node.js 版本 >=22.15.0、>=23.11.0 或 >=24.0.0。 在较旧的运行时版本上， --frozen-store 会导致 ERR_PNPM_FROZEN_STORE_UNSUPPORTED_NODE。

锁文件设置​

锁文件​

  • 默认值：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 一起使用，或者通过在 .npmrc 文件中设置 mergeGitBranchLockfilesBranchPattern 来使用。

mergeGitBranchLockfilesBranchPattern​

  • 默认值： null
  • 类型：Array 或 null

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

例如：

mergeGitBranchLockfilesBranchPattern:
- main
- release*

你还可以使用 ! 来排除模式。

peersSuffixMaxLength​

  • 默认值：1000
  • 类型：number

添加到锁文件中的依赖项键的 peer ID 后缀的最大长度。 如果后缀较长，则用井号替换。