存储与锁文件设置

Store 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 将复制包而不是硬链接它们，因为硬链接只能发生在同一文件系统上。

If no directory above the project accepts a hard link at all (an agent sandbox that grants write access only to the project, or a container with just the project bind-mounted writable), the store is created at .pnpm-store inside the project. Putting it in the home directory there would either fail on a read-only home or land on another volume, which copies every package instead of hard-linking it (#13525).

important

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

verifyStoreIntegrity#

  • 默认值：true
  • 类型：Boolean

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

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

strictStorePkgContentCheck#

  • 默认值：true
  • 类型：Boolean

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

frozenStore#

添加于：v11.7.0

  • 默认值： false
  • 类型：Boolean

Lets pnpm install run against a package store that lives on a read-only filesystem, for example a Nix store, a read-only bind mount, or an OCI image layer. 启用该功能后，pnpm 会以不可变模式打开存储目录中的 SQLite index.db 文件（从而绕过 WAL/-shm 辅助文件，因为这些文件无法在只读目录下创建），并禁用所有会向存储目录执行写入操作的代码路径。

Ordinary installs can run in parallel and populate the same store on a local filesystem on the same machine. Leave frozenStore disabled for that use case.

With frozenStore enabled, no other process may modify the store during the install. Immutable reads bypass SQLite locking and can report "database disk image is malformed" if another job changes the database. This restriction does not apply to --frozen-lockfile, which still allows writes to the store.

将其与 --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 服务器不兼容，因为它们都会向存储中写入数据。副作用缓存 也不会被写入。

注意

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

Lockfile settings#

锁文件#

  • 默认值：true
  • 类型：Boolean

当设置为 false 时，pnpm 不会读取或生成 pnpm-lock.yaml 文件。

frozenLockfile#

  • 默认值：
    • 对于非 CI 环境：false
    • 对于 CI 环境：如果存在 lock 文件，则为 true
  • 类型：Boolean

When set to true, pnpm fails the installation if the lockfile needs updating or is missing.

In CI environments, this setting defaults to true when a lockfile is present.

preferFrozenLockfile#

  • 默认值：true
  • 类型：Boolean

当设置为 true 并且存在 pnpm-lock.yaml 满足 package.json 中的依赖关系时，执行无头安装。无头安装会跳过所有依赖项解析，因为它不需要修改锁文件。

lockfileIncludeTarballUrl#

  • 默认值： false
  • 类型：Boolean

将包的 tarball 的完整 URL 添加到 pnpm-lock.yaml 中的每个条目。

gitBranchLockfile#

  • 默认值： false
  • 类型：Boolean

When set to true, the generated lockfile name after installation will be named based on the current branch name to completely avoid merge conflicts. 例如，如果当前分支名称为 feature-foo，则 对应的锁文件名称将为 pnpm-lock.feature-foo.yaml 而不是 pnpm-lock.yaml。 It is typically used in conjunction with the command line argument --merge-git-branch-lockfiles or by setting mergeGitBranchLockfilesBranchPattern in the pnpm-workspace.yaml file.

mergeGitBranchLockfilesBranchPattern#

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

This configuration matches the current branch name to determine whether to merge all git branch lockfile files. By default, you need to manually pass the --merge-git-branch-lockfiles command line parameter. This configuration allows this process to be automatically completed.

例如：

pnpm-workspace.yaml
mergeGitBranchLockfilesBranchPattern:
- main
- release*

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

peersSuffixMaxLength#

  • 默认值：1000
  • 类型：number

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