配置

pnpm 设置分为两类：

  • 身份验证和证书设置存储在 INI 文件中。这些文件包含敏感凭据，不应提交到你的仓库。有关详细信息，请参阅身份验证设置。
  • All other settings are stored in YAML files: the project pnpm-workspace.yaml and the global config.yaml. Some settings are project-only and are ignored in the global config.yaml (see Global configuration).

pnpm does not read settings from the pnpm field of package.json. A setting found there is ignored with a warning. Define it in pnpm-workspace.yaml.

本地项目配置#

项目级设置放在 pnpm-workspace.yaml 文件中：

pnpm-workspace.yaml
nodeVersion: "22.22.3"
saveExact: true

全局配置#

全局 YAML 配置文件（config.yaml）位于以下路径之一：

  • 如果设置了 $XDG_CONFIG_HOME 环境变量，则 $XDG_CONFIG_HOME/pnpm/config.yaml
  • On Windows: %LOCALAPPDATA%\pnpm\config\config.yaml
  • 在 macOS 上：~/Library/Preferences/pnpm/config.yaml
  • 在 Linux 上：~/.config/pnpm/config.yaml

Not every setting may be set in the global config.yaml. Settings that apply to the whole machine, such as storeDir, cacheDir, packageImportMethod, minimumReleaseAge, and network settings, may be set there. Settings that define the structure of a project's node_modules or workspace, such as nodeLinker, hoistPattern, publicHoistPattern, shamefullyHoist, or linkWorkspacePackages, are project-only: they have to be set in pnpm-workspace.yaml, so that the project installs the same way on every machine. Registry routes may be set globally, but the server descriptions serverType and supportsTimeField are read only from pnpm-workspace.yaml (see Registries).

pnpm config set --global refuses project-only settings with ERR_PNPM_CONFIG_SET_UNSUPPORTED_YAML_CONFIG_KEY. If they are written to config.yaml by hand, pnpm prints a warning that names them and ignores them.

To share project-only settings across several projects, publish them as a config dependency and add it to each project.

Global registry credentials go in auth.ini in the same directory. See Auth file locations.

环境变量#

名称以 pnpm_config_（或 PNPM_CONFIG_）开头的环境变量将被加载到配置中。这些设置会覆盖 pnpm-workspace.yaml 中的设置，但不会覆盖 CLI 参数。

警告

pnpm does not read npm_config_* environment variables. 请改用 pnpm_config_* 环境变量（例如，pnpm_config_registry 而不是 npm_config_registry）。 The exceptions are:

  • NPM_CONFIG_WORKSPACE_DIR, which sets the workspace directory.
  • npm_config_userconfig, which points to a user .npmrc for auth settings.
  • URL-scoped credentials such as npm_config_//registry.example.com/:_authToken.

例如：

pnpm_config_save_exact=true pnpm add foo

If you need pnpm to work across multiple hard drives or filesystems, read the FAQ.

有关管理配置的更多信息，请参阅 config 命令。