Settings (pnpm-workspace.yaml)
pnpm gets its configuration from the command line, environment variables, pnpm-workspace.yaml
, and
.npmrc
files.
The pnpm config
command can be used to read and edit the contents of the project and global configuration files.
The relevant configuration files are:
- Per-project configuration file:
/path/to/my/project/pnpm-workspace.yaml
- Global configuration file:
~/.config/pnpm/rc
(an INI-formatted list ofkey = value
parameters)
Authorization-related settings are handled by npm's configuration system. So, pnpm config set registry=<value>
will actually save the setting to npm's global configuration file.
Values in the configuration files may contain env variables using the ${NAME}
syntax. 也可以使用默认 值指定环境变量。 使用 ${NAME-fallback}
将在未设置 NAME
时返回 fallback
。 ${NAME:-fallback}
,会在 NAME
不存在或为空字符串时返回 fallback
。
Dependency Resolution
overrides
此字段允许您指示 pnpm 覆盖依赖关系图中的任何依赖项。 这对于强制所有软件包使用一个依赖项的单个版本、反向移植一个修复、用分叉替换依赖项或删除未使用的依赖项很有用。
请注意,overrides 字段只能在项目的根目录下设置。
An example of the overrides
field:
overrides:
"foo": "^1.0.0"
"quux": "npm:@myorg/quux@^1.0.0"
"bar@^2.1.0": "3.0.0"
"qar@1>zoo": "2"
你可以用 ">" 来覆盖某个包下的子依赖的版本,比如 qar@1>zoo
只会覆盖 qar@1
依赖的 zoo
的版本,而不会影响其他依赖。
一个overide可以被定义为直接依赖项的规则的引用。
这通过依赖名称前缀一个 $
实现:
{
"dependencies": {
"foo": "^1.0.0"
}
}
overrides:
foo: "$foo"
被引用的包不必匹配需要覆盖的包:
overrides:
bar: "$foo"
If you find that your use of a certain package doesn't require one of its dependencies, you may use -
to remove it. For example, if package foo@1.0.0
requires a large package named bar
for a function that you don't use, removing it could reduce install time:
overrides:
"foo@1.0.0>bar": "-"
此功能对于 optionalDependencies
特别有用,其中大多数可选包可以被安全地跳过。
packageExtensions
packageExtension
字段提供了一种用额外信息扩展现有软件包定义的方法。 例如,如果 react-redux
本应该在它的 peerDependencies
中包含 react-dom
但它没有,则可以用 packageExtensions
来填补上 react-redux
。
packageExtensions:
react-redux:
peerDependencies:
react-dom: "*"
packageExtensions
中的键是包名或包名和 semver 范围,因此可以只修补包的某些版本:
packageExtensions:
react-redux@1:
peerDependencies:
react-dom: "*"
以下字段可以使用 packageExtensions
进行扩展: dependencies
、optionalDependencies
、peerDependencies
和 peerDependenciesMeta
。
一个更大的例子:
packageExtensions:
express@1:
optionalDependencies:
typescript: "2"
fork-ts-checker-webpack-plugin:
dependencies:
"@babel/core": "1"
peerDependencies:
eslint: ">= 6"
peerDependenciesMeta:
eslint:
optional: true
我们与 Yarn 一起维护一个 packageExtensions
的数据库,以便修补在生态系统中损坏的包。
如果你使用 packageExtensions
, 考虑发送一个 PR 上游并将你的扩展贡献给 [@yarnpkg/extension
] 数据库。
allowedDeprecatedVersions
此项设置允许忽略特定依赖包的 deprecation 警告。
示例:
allowedDeprecatedVersions:
express: "1"
request: "*"
使用上述配置,pnpm 将不会打印 request
任何版本和 express
v1 版本的弃用警告。
updateConfig
updateConfig.ignoreDependencies
有时您无法更新依赖项。 例如,最新版本的依赖项开始使用 ESM,但您的项目尚未采用 ESM。 恼人的是,这样的包将始终被 pnpm outdated
命令打印出来,并在运行 pnpm update --latest
时更新。 但是,你可以在 ignoreDependencies
字段中列出你不想更新的包:
updateConfig:
ignoreDependencies:
- load-json-file
模式匹配也是支持的,因此你可以忽略在特定范围内的任何包: @babel/*
。
支持的架构
你可以指定要安装的可选依赖项的架构,即使它们与运行安装的系统的架构不匹配。
例如,以下配置指示安装 Windows x64 的可选依赖项:
supportedArchitectures:
os:
- win32
cpu:
- x64
而此配置将为 Windows、macOS 以及当前正在运行安装的系统架构安装可选依赖项。 它包括 x64 和 arm64 CPU 的工件:
supportedArchitectures:
os:
- win32
- darwin
- current
cpu:
- x64
- arm64
另外, supportedArchitectures
还支持指定系统的 libc
。
ignoredOptionalDependencies
如果可选依赖项的名称包含在此数组中,则会跳过它。 示例:
ignoredOptionalDependencies:
- fsevents
- "@esbuild/*"
依赖提升设置
hoist
- 默认值:true
- 类型:Boolean
当为 true
时,所有依赖项都会被提升到 node_modules/.pnpm/node_modules
。 这使得 node_modules
中的所有包都可以访问未列出的依赖项。
hoistWorkspacePackages
- 默认值:true
- 类型:Boolean
When true
, packages from the workspaces are symlinked to either <workspace_root>/node_modules/.pnpm/node_modules
or to <workspace_root>/node_modules
depending on other hoisting settings (hoistPattern
and publicHoistPattern
).
hoistPattern
- 默认值:['*']
- 类型:string[]
告诉 pnpm 哪些包应该被提升到 node_modules/.pnpm/node_modules
。 默认情况下,所有包都被提升 — 但是,如果你知道只有某些有缺陷的包具有幻影依赖,你可以使用此选项专门提升幻影依赖(推荐做法)。
例如:
hoistPattern:
- "*eslint*"
- "*babel*"
你还可以在模式前面添加 !
来避免提升。
例如:
hoistPattern:
- "*types*"
- "!@types/react"
publicHoistPattern
- 默认值:[]
- 类型:string[]
Unlike hoistPattern
, which hoists dependencies to a hidden modules directory
inside the virtual store, publicHoistPattern
hoists dependencies matching
the pattern to the root modules directory. 提升至根模块目录中意味着应用代码可以访问到幻影依赖,即使它们对解析策略做了不当的修改。
当处理一些不能正确解析依赖关系的有缺陷可插拔工具时,此设置很有用。
例如:
publicHoistPattern:
- "*plugin*"
Note: Setting shamefullyHoist
to true
is the same as setting
publicHoistPattern
to *
.
你还可以在模式前面添加 !
来避免提升。
例如:
publicHoistPattern:
- "*types*"
- "!@types/react"
shamefullyHoist
- 默认值: false
- 类型:Boolean
默认情况下,pnpm 创建一个半严格的 node_modules
,这意味着依赖项可以访问未声明的依赖项,但 node_modules
之外的模块不行。
通过这种布局,生态系统中的大多数的包都可以正常工作。
但是,如果某些工具仅在提升的依赖项位于根目录的 node_modules
时才有效,你可以将其设置为 true
来提升它们。
Node 模块设置
modulesDir
- 默认值:node_modules
- 类型:路径
将安装依赖项的目录(而不是 node_modules
)。
nodeLinker
- 默认值:isolated
- 类型:isolated、hoisted、pnp
定义应该使用什么链接器来安装 Node 包。
- isolated - 依赖项从虚拟存储
node_modules/.pnpm
中建立符号链接 - hoisted - 创建一个没有符号链接的扁平的
node_modules
。 与 npm 或 Yarn Classic 创建的node_modules
一致。 当使用此设置时,Yarn 的一个库用于提升。 使用此设置的正当理由:- 你的工具无法很好地与符号链接配合使用。 React Native 项目很可能只有在你使用提升的
node_modules
才能工作。 - 你的项目会被部署到 serverless 服务提供商。 一些 serverless 提供商(例如 AWS Lambda)不支持符号链接。 此问题的另一种解决方案是在部署之前打包你的应用程序。
- 如果你想使用
"bundledDependencies"
发你的包。 - 如果你使用 --preserve-symlinks 标志运行 Node.js。
- 你的工具无法很好地与符号链接配合使用。 React Native 项目很可能只有在你使用提升的
- pnp — 没有
node_modules
。 Plug'n'Play 是一种 Yarn Berry 使用的创新的 Node 依赖策略。 当使用pnp
作为你的链接器时,建议同时将symlink
设置为false
。
symlink
- 默认值:true
- 类型:Boolean
当 symlink
设置为 false
时,pnpm 创建一个没有任何符号链接的虚拟存储目录。 It is a useful setting together with nodeLinker=pnp
.
enableModulesDir
- 默认值:true
- 类型:Boolean
当为 false
时,pnpm 不会将任何文件写入模块目录
(node_modules
)。 这对于在用户空间的文件系统 (FUSE) 中挂载模块目录时很有用。 有一个实验性 CLI 允许你在 FUSE 中挂载模块目录:@pnpm/mount-modules。
virtualStoreDir
- 默认值:node_modules/.pnpm
- 类型:路径
带有指向存储的链接的目录。 所有直接和间接依赖项都 链接到此目录中。
这是一个有用的设置,可以解决 Windows 上长路径的问题。 如果你有一些路径很长的依赖项,你可以选择将虚拟存储放在驱动器的根目录中(例如 C:\my-project-store
)。
或者你可以将虚拟存储设置为 .pnpm
并将其添加到 .gitignore
。 这将使堆栈跟踪更清晰,因为依赖项的路径将会提高一个目录层级。
**注意:**虚拟存储不能在多个项目之间共享。 每个项目都应该有自己的虚拟存储(除了在工作空间中被共享的根目录)。
virtualStoreDirMaxLength
- 默认值:
- 在 Linux/macOS 上:120
- 在 Windows 上:60
- 类型:number
设置虚拟存储目录 (node_modules/.pnpm
) 中目录名称的最大允许长度。 如果你在 Windows 上遇到长路径问题,你可以将其设置为较低的数字。
packageImportMethod
- 默认值: auto
- 类型:auto、hardlink、copy、clone、clone-copy
Controls the way packages are imported from the store (if you want to disable symlinks inside node_modules
, then you need to change the nodeLinker setting, not this one).
- auto - 尝试从存储克隆包。 如果不支持克隆 则从存储硬链接包。 如果克隆和链接都不支持,则回退到复制
- hardlink - 从存储硬链接包
- clone-or-copy - 尝试从存储中克隆包。 如果不支持克隆则回退到复制。
- copy - 从存储中复制包
- clone - 从存储中克隆(也称为 copy-on-write 或参考链接)包
克隆是将包写入 node_modules 的最佳方式。 这是最快的方式,也是最安全的方式。 当使用克隆时,你可以在 node_modules 中编辑文件,并且它们不会在中央内容可寻址存储中被修改。
不幸的是,并非所有文件系统都支持克隆。 我们建议使用写时复制 (CoW) 文件系统(例如,在 Linux 上使用 Btrfs 而不是 Ext4)以获得最佳的 pnpm 体验。
modulesCacheMaxAge
- 默认值:10080 (以分钟为单位的 7 天)
- 类型:number
孤立包应该从模块目录中被删除的时间(以分钟为单位)。 pnpm 在模块目录中保存了一个包的缓存。 切换分支或降级依赖项时,这会提高安装速度。
dlxCacheMaxAge
- 默认值:1440 (以分钟为单位的 1 天)
- 类型:number
Dlx 缓存过期的时间(以分钟为单位)。 执行 dlx 命令后,pnpm 会保留一个缓存,该缓存会省略后续调用同一 dlx 命令的安装步骤。
enableGlobalVirtualStore
Added in: v10.12.1
- Default: false (always false in CI)
- 类型:Boolean
- Status: Experimental
When enabled, node_modules
contains only symlinks to a central virtual store, rather than to node_modules/.pnpm
. By default, this central store is located at <store-path>/links
(use pnpm store path
to find <store-path>
).
In the central virtual store, each package is hard linked into a directory whose name is the hash of its dependency graph. As a result, all projects on the system can symlink their dependencies from this shared location on disk. This approach is conceptually similar to how NixOS manages packages, using dependency graph hashes to create isolated and shareable package directories in the Nix store.
This should not be confused with the global content-addressable store. The actual package files are still hard linked from the content-addressable store—but instead of being linked directly into
node_modules/.pnpm
, they are linked into the global virtual store.
Using a global virtual store can significantly speed up installations when a warm cache is available. However, in CI environments (where caches are typically absent), it may slow down installation. If pnpm detects that it is running in CI, this setting is automatically disabled.
To support hoisted dependencies when using a global virtual store, pnpm relies on the NODE_PATH
environment variable. This allows Node.js to resolve packages from the hoisted node_modules
directory. However, this workaround does not work with ESM modules, because Node.js no longer respects NODE_PATH
when using ESM.
If your dependencies are ESM and they import packages not declared in their own package.json
(which is considered bad practice), you’ll likely run into resolution errors. There are two ways to fix this:
- Use packageExtensions to explicitly add the missing dependencies.
- Add the @pnpm/plugin-esm-node-path config dependency to your project. This plugin registers a custom ESM loader that restores
NODE_PATH
support for ESM, allowing hoisted dependencies to be resolved correctly.
存储设置
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 将复制包而不是硬链接它们,因为硬链接只能发生在同一文件系统上。
verifyStoreIntegrity
- 默认值:true
- 类型:Boolean
默认情况下,如果存储中的文件已被修改,则在将其链接到项目的 node_modules
之前会检查该文件的内容。 If verifyStoreIntegrity
is set to false
, files in the content-addressable store will not be checked during installation.
useRunningStoreServer
已弃用的功能
- 默认值: false
- 类型:Boolean
只允许使用存储服务器进行安装。 如果没有在运行的存储服务器,安装将失败。
strictStorePkgContentCheck
- 默认值:true
- 类型:Boolean
一些注册源允许以不同的包名或版本,发布完全相同的内容。 这破坏了存储中包的有效性检查。 To avoid errors when verifying the names and versions of such packages in the store, you may set the strictStorePkgContentCheck
setting to false
.
锁文件设置
lockfile
- 默认值: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
。 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
此配置匹配当前分支名称以确定是否合并所有 git 分支锁文件文件。 默认情况下,你需要手动传递 --merge-git-branch-lockfiles
命令行参数。 这项配置允许自动完成这个过程。
例如:
mergeGitBranchLockfilesBranchPattern:
- main
- release*
你还可以使用 !
来排除模式。
peersSuffixMaxLength
- 默认值:1000
- 类型:number
添加到锁文件中的依赖项键的 peer ID 后缀的最大长度。 如果后缀较长,则用井号替换。
注册源 & 身份验证设置
registry
- 默认值: .https://registry.npmjs.org/
- 类型:url
npm 包注册表的基准 URL(包括尾部斜杠)。
<scope>:registry
应用于指定范围的包的 npm 注册源。 例如,设置 @babel:registry=https://example.com/packages/npm/
将在你使用 pnpm add @babel/core
或任何 @babel
范围的包时,该包将强制从 https://example.com/packages/npm
而不是默认注册源中获取。