跳至主要內容
版本：11 & 12

其他設定

savePrefix​

  • Default: '^'
  • Type: '^', '~', '', '='

Configure how versions of packages installed to a package.json file get prefixed.

For example, if a package has version 1.2.3, by default its version is set to ^1.2.3 which allows minor upgrades for that package, but after pnpm config set save-prefix='~' it would be set to ~1.2.3 which only allows patch upgrades.

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.

This setting is ignored when the added package has a range specified. For instance, pnpm add foo@2 will set the version of foo in package.json to 2, regardless of the value of savePrefix.

tag​

  • Default: latest
  • Type: String

If you pnpm add a package and you don't provide a specific version, then it will install the package at the version registered under the tag from this setting.

This also sets the tag that is added to the package@version specified by the pnpm tag command if no explicit tag is given.

globalDir​

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

Specify a custom directory to store global packages.

globalBinDir​

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

Allows to set the target directory for the bin files of globally installed packages.

提示

In pnpm v11, globally installed binaries are stored in a bin subdirectory of PNPM_HOME instead of directly in PNPM_HOME. This prevents internal directories like global/ and store/ from polluting shell autocompletion when PNPM_HOME is on PATH. After upgrading, run pnpm setup to update your shell configuration.

npmrcAuthFile​

Added in: v11.0.0

  • Default: ~/.npmrc
  • Type: path

The path to a file containing registry authentication tokens. By default, pnpm reads auth tokens from ~/.npmrc as a fallback for registry authentication. Use this setting to point to a different file instead.

This setting cannot be set in pnpm-workspace.yaml at the project level; set it in the global configuration file, via the --npmrc-auth-file CLI option, or via the PNPM_CONFIG_NPMRC_AUTH_FILE environment variable (the npm-style NPM_CONFIG_USERCONFIG is honored as a fallback). A relative path is resolved against the working directory.

stateDir​

  • 預設值：
    • If the $XDG_STATE_HOME env variable is set, then $XDG_STATE_HOME/pnpm
    • On Windows: ~/AppData/Local/pnpm-state
    • On macOS: ~/.pnpm-state
    • On Linux: ~/.local/state/pnpm
  • Type: path

The directory where pnpm creates the pnpm-state.json file that is currently used only by the update checker.

cacheDir​

  • 預設值：
    • If the $XDG_CACHE_HOME env variable is set, then $XDG_CACHE_HOME/pnpm
    • On Windows: ~/AppData/Local/pnpm-cache
    • On macOS: ~/Library/Caches/pnpm
    • On Linux: ~/.cache/pnpm
  • Type: path

The location of the cache (package metadata, dlx cache, and some install verification results).

Like the store, the cache directory is intended to be shared only between mutually trusted users, jobs, and processes. If you configure or restore a shared cacheDir, protect it with filesystem permissions so untrusted users cannot write to it.

useStderr​

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

When true, all the output is written to stderr.

updateNotifier​

  • Default: true
  • 型別：布林值

Set to false to suppress the update notification when using an older version of pnpm than the latest.

preferSymlinkedExecutables​

  • Default: true, when node-linker is set to hoisted and the system is POSIX
  • 型別：布林值

Create symlinks to executables in node_modules/.bin instead of command shims. This setting is ignored on Windows, where only command shims work.

ignoreCompatibilityDb​

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

During installation the dependencies of some packages are automatically patched. If you want to disable this, set this config to true.

The patches are applied from Yarn's @yarnpkg/extensions package.

resolutionMode​

  • Default: highest (was lowest-direct from v8.0.0 to v8.6.12)
  • Type: highest, time-based, lowest-direct

When resolutionMode is set to time-based, dependencies will be resolved the following way:

  1. Direct dependencies will be resolved to their lowest versions. So if there is foo@^1.1.0 in the dependencies, then 1.1.0 will be installed.
  2. Subdependencies will be resolved from versions that were published before the last direct dependency was published.

With this resolution mode installations with warm cache are faster. It also reduces the chance of subdependency hijacking as subdependencies will be updated only if direct dependencies are updated.

This resolution mode works only with npm's full metadata. So it is slower in some scenarios. However, if you use Verdaccio v5.15.1 or newer, you may set the registrySupportsTimeField setting to true, and it will be really fast.

When resolutionMode is set to lowest-direct, direct dependencies will be resolved to their lowest versions.

registrySupportsTimeField​

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

Set this to true if the registry that you are using returns the "time" field in the abbreviated metadata. As of now, only Verdaccio from v5.15.1 supports this.

extendNodePath​

  • Default: true
  • 型別：布林值

When true, pnpm sets the NODE_PATH environment variable in command shims (the wrapper scripts created in node_modules/.bin). When false, NODE_PATH is not set.

Why this is needed​

pnpm's isolated node_modules layout means that a package can only access its own declared dependencies. However, when a CLI tool runs via a command shim, some libraries (notably import-local, used by jest, eslint, and others) resolve modules from the current working directory rather than from the binary's own location. 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.

To bridge this gap, pnpm includes two types of paths in NODE_PATH:

  1. 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.
  2. 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 cannot discover this directory through its standard resolution algorithm, so it must be provided via NODE_PATH.

NODE_PATH is also essential when enableGlobalVirtualStore is enabled. With a global virtual store, packages are symlinked from a central location outside the project, so Node.js's standard upward node_modules traversal from the binary's real path won't reach the project's own node_modules or its hoisted dependencies. In this case, NODE_PATH must include both the project's root node_modules and the hoisted directory at node_modules/.pnpm/node_modules to ensure correct resolution.

When to disable​

You may set this to false if you are certain that none of the CLI tools in your project resolve modules from the working directory and you are not using a global virtual store. Disabling it produces slightly simpler command shims.

deployAllFiles​

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

When deploying a package or installing a local package, all files of the package are copied. By default, if the package has a "files" field in the package.json, then only the listed files and directories are copied.

dedupeDirectDeps​

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

When set to true, dependencies that are already symlinked to the root node_modules directory of the workspace will not be symlinked to subproject node_modules directories.

optimisticRepeatInstall​

Added in: v10.1.0

  • Default: true
  • 型別：布林值

When enabled, a fast check will be performed before proceeding to installation. This way a repeat install or an install on a project with everything up-to-date becomes a lot faster.

requiredScripts​

Scripts listed in this array will be required in each project of the workspace. Otherwise, pnpm -r run <script name> will fail.

requiredScripts:
- build

enablePrePostScripts​

  • Default: true
  • 型別：布林值

When true, pnpm will run any pre/post scripts automatically. So running pnpm foo will be like running pnpm prefoo && pnpm foo && pnpm postfoo.

scriptShell​

  • Default: null
  • Type: path

The shell to use for scripts run with the pnpm run command.

例如，要在 Windows 上強制使用 Git Bash:

pnpm config set scriptShell "C:\Program Files\git\bin\bash.exe"

shellEmulator​

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

When true, pnpm will use a JavaScript implementation of a bash-like shell to execute scripts.

This option simplifies cross-platform scripting. For instance, by default, the next script will fail on non-POSIX-compliant systems:

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

But if the shellEmulator setting is set to true, it will work on all platforms.

注意事項

Node.js 22 or higher supports running scripts without pnpm's assistance. For the example above, you can run the test script with node --run test. However, the shellEmulator option has no effect on this. Scripts that depend on POSIX features are required to be run pnpm run instead of node --run to work in non-POSIX-compliant environments.

catalogMode​

Added in: v10.12.1

  • Default: manual
  • Type: manual, strict, prefer

Controls if and how dependencies are added to the default catalog, when running pnpm add. There are three modes:

  • strict - only allows dependency versions from the catalog. Adding a dependency outside the catalog's version range will cause an error.
  • prefer - prefers catalog versions, but will fall back to direct dependencies if no compatible version is found.
  • manual (default) - does not automatically add dependencies to the catalog.

ci​

Added in: v10.12.1

  • Default: true (when the environment is detected as CI)
  • 型別：布林值

This setting explicitly tells pnpm whether the current environment is a CI (Continuous Integration) environment.

cleanupUnusedCatalogs​

新增於 v10.15.0

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

When set to true, pnpm will remove unused catalog entries during installation.