Store & Lockfile Settings

Store Settings

storeDir

• 預設值：
  • If the $PNPM_HOME env variable is set, then $PNPM_HOME/store
  • If the $XDG_DATA_HOME env variable is set, then $XDG_DATA_HOME/pnpm/store
  • On Windows: ~/AppData/Local/pnpm/store
  • On macOS: ~/Library/pnpm/store
  • On Linux: ~/.local/share/pnpm/store
• Type: path

所有套件儲存在磁碟上的位置。

存放區應該一律安裝在相同的磁碟上，因此每個磁碟都將有一個存放區。 如果目前的磁碟上有主目錄，則將在其內部建立儲存區。 如果磁碟上沒有主目錄，則將在檔案系統的根目錄中建立儲存區。 For example, if installation is happening on a filesystem mounted at /mnt, then the store will be created at /mnt/.pnpm-store. Windows 系統也是這樣。

從不同的磁碟設定存放區是可行的，但在那種情況下，pnpm 將不會建立指向套件的永久連結，而是會從存放區複製，因為只有在相同的檔案系統上才可以建立永久連結。

important

The pnpm store is intended to be shared only between mutually trusted users, jobs, and processes. If you configure a shared storeDir, protect it with filesystem permissions so untrusted users cannot write to it. The store is part of pnpm's trust domain: packages may be hard linked from it, and the store index (index.db) records the hashes used to verify cached files.

verifyStoreIntegrity

• Default: true
• 型別：布林值

By default, if a file in the store has been modified, the content of this file is checked before linking it to a project's node_modules. If verifyStoreIntegrity is set to false, files in the content-addressable store will not be checked during installation.

This setting helps detect accidental store corruption. It does not make a store that is writable by untrusted users safe, because an attacker who can write to the store can alter both cached package contents and the metadata used to verify them.

useRunningStoreServer

危險

Deprecated feature

• 預設值：false
• 型別：布林值

Only allows installation with a store server. If no store server is running, installation will fail.

strictStorePkgContentCheck

• Default: true
• 型別：布林值

Some registries allow the exact same content to be published under different package names and/or versions. This breaks the validity checks of packages in the store. To avoid errors when verifying the names and versions of such packages in the store, you may set the strictStorePkgContentCheck setting to false.

frozenStore

Added in: v11.7.0

• 預設值：false
• 型別：布林值

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. When enabled, pnpm opens the store's SQLite index.db in immutable mode (bypassing the WAL/-shm sidecar files that otherwise can't be created on a read-only directory) and suppresses every code path that would write to the store.

Pair it with --offline and --frozen-lockfile against a fully-populated store:

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

The store must already contain everything the install needs, including the build output of any package whose lifecycle scripts are approved (or that has a patch applied). 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. If the store is missing its content directory entirely, the install fails fast with ERR_PNPM_FROZEN_STORE_INCOMPLETE rather than trying to initialize it.

frozenStore is incompatible with --force and with a configured pnpr server, since both write into the store. The side effects cache is not written either.

注意事項

The read-only store open requires Node.js >=22.15.0, >=23.11.0, or >=24.0.0. On older runtimes, --frozen-store fails with ERR_PNPM_FROZEN_STORE_UNSUPPORTED_NODE.

鎖定檔設定

lockfile

• Default: true
• 型別：布林值

When set to false, pnpm won't read or generate a pnpm-lock.yaml file.

preferFrozenLockfile

• Default: true
• 型別：布林值

When set to true and the available pnpm-lock.yaml satisfies the package.json dependencies directive, a headless installation is performed. 無周邊安裝會略過所有的相依性解析，因為它不需要修改鎖定檔。

lockfileIncludeTarballUrl

• 預設值：false
• 型別：布林值

Add the full URL to the package's tarball to every entry in pnpm-lock.yaml.

gitBranchLockfile

• 預設值：false
• 型別：布林值

When set to true, the generated lockfile name after installation will be named based on the current branch name to completely avoid merge conflicts. For example, if the current branch name is feature-foo, the corresponding lockfile name will be pnpm-lock.feature-foo.yaml instead of 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

• Default: null
• Type: Array or 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.

例如：

mergeGitBranchLockfilesBranchPattern:
- main
- release*

You may also exclude patterns using !.

peersSuffixMaxLength

• Default: 1000
• Type: number

Max length of the peer IDs suffix added to dependency keys in the lockfile. If the suffix is longer, it is replaced with a hash.