跳到主内容
版本：11 & 12

Node-Modules & Hoisting Settings

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 的一个库用于提升。 使用此设置的正当理由：
    1. 你的工具无法很好地与符号链接配合使用。 React Native 项目很可能只有在你使用提升的 node_modules 才能工作。
    2. 你的项目会被部署到 serverless 服务提供商。 一些 serverless 提供商（例如 AWS Lambda）不支持符号链接。 此问题的另一种解决方案是在部署之前打包你的应用程序。
    3. 如果你想使用 "bundledDependencies" 发你的包。
    4. 如果你使用 --preserve-symlinks 标志运行 Node.js。
  • pnp — 没有 node_modules。 Plug'n'Play 是一种 Yarn Berry 使用的创新的 Node 依赖策略。 当使用 pnp 作为你的链接器时，建议同时将 symlink 设置为 false。

nodeExperimentalPackageMap​

添加于：v11.8.0

  • 默认值： false
  • 类型：Boolean

当为 true 时，pnpm 会通过向 NODE_OPTIONS 添加 Node.js 的 --experimental-package-map 选项，将生成的 node_modules/.package-map.json 注入到由 pnpm 管理的 Node.js 脚本环境中。

包映射是在隔离安装和提升安装过程中生成的。 此设置仅控制 pnpm 是否将生成的映射传递给脚本。

CLI 和环境变量配置使用 kebab-case 风格的名称 node-experimental-package-map。

nodeExperimentalPackageMap: true

nodePackageMapType​

添加于：v11.8.0

  • 默认：standard
  • 类型：standard，loose

控制 node_modules/.package-map.json 的生成方式。

  • standard - 只有已声明的依赖项可通过包映射访问。
  • loose —— 还会映射那些可通过已安装的 node_modules 布局访问到的包，这使得未显式声明但被提升的依赖项能够被解析。

CLI 和环境变量配置使用 kebab-case 风格的名称 node-package-map-type。

nodePackageMapType: loose

符号链接​

  • 默认值：true
  • 类型：Boolean

当 symlink 设置为 false 时，pnpm 创建一个没有任何符号链接的虚拟存储目录。 这与 node-linker=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 上遇到长路径问题，你可以将其设置为较低的数字。

virtualStoreOnly​

添加于：v11.0.0

  • 默认值： false
  • 类型：Boolean

当设置为 true 时，pnpm 会装入虚拟存储店，而不会创建导入器的符号链接、钩子、二进制链接或运行生命周期脚本。 这对于预先填充存储（例如，在 Nix 构建中）非常有用，而不会创建不必要的项目级工件。 pnpm fetch 内部使用此模式。

packageImportMethod​

  • 默认值： auto
  • 类型：auto、hardlink、copy、clone、clone-copy

控制从存储中导入包的方式（如果要禁用 node_modules 中的符号链接，则需要更改 nodeLinker 设置，而不是此设置）。

  • 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​

添加于：v10.12.1

  • 默认值： false
  • 类型：Boolean
注意

在 pnpm v11 中，全局安装（pnpm add -g）和 pnpm dlx 默认使用全局虚拟存储。

如果启用，node_modules 只包含到一个中心虚拟存储的符号链接，而不是 node_modules/.pnpm。 默认情况下，此中央存储位于 STORE_PATH/links（使用 pnpm store path 来查找 STORE_PATH）。

在中央虚拟存储中，每个包都被硬链接到一个目录中，该目录的名称是其依赖关系图的哈希值。 因此，系统上的所有项目都可以从磁盘上的这个共享位置符号链接它们的依赖项。 这种方法在概念上类似于 NixOS 管理包的方式，使用依赖图哈希在 Nix 存储中创建隔离且可共享的包目录。

这不应与全局内容可寻址存储混淆。 实际的包文件仍然与内容可寻址存储硬链接 - 但不是直接链接到 node_modules/.pnpm，而是链接到全局虚拟存储。

当有热缓存可用时，使用全局虚拟存储可以显著加快安装速度。 然而，在 CI 环境中（通常不存在缓存），它可能会减慢安装速度。 如果 pnpm 检测到它正在 CI 中运行，则此设置将自动禁用。

important

为了在使用全局虚拟存储时支持提升的依赖项，pnpm 依赖于 NODE_PATH 环境变量。 这允许 Node.js 解析来自提升的 node_modules 目录的包。 但是，此解决方法不适用于 ESM 模块，因为 Node.js 在使用 ESM 时不再尊重 NODE_PATH。

如果你的依赖项是 ESM，并且它们导入的包未在其自己的 package.json 中声明（这被认为是不好的做法），你可能会遇到解析错误。 有两种方法可以解决此问题：

  • 使用 packageExtensions 明确添加缺少的依赖项。
  • 将 @pnpm/plugin-esm-node-path 配置依赖项添加到你的项目。 该插件注册了一个自定义 ESM 加载器，可恢复对 ESM 的 NODE_PATH 支持，从而允许正确解析提升的依赖项。

依赖提升设置​

hoist​

  • 默认值：true
  • 类型：Boolean

当为 true 时，所有依赖项都会被提升到 node_modules/.pnpm/node_modules。 这使得 node_modules 中的所有包都可以访问未列出的依赖项。

hoistWorkspacePackages​

  • 默认值：true
  • 类型：Boolean

当为 true 时，工作区中的包将符号链接到 <workspace_root>/node_modules/.pnpm/node_modules 或 <workspace_root>/node_modules，具体取决于其他提升设置（hoistPattern 和 publicHoistPattern）。

hoistPattern​

  • 默认值：['*']
  • 类型：string[]

告诉 pnpm 哪些包应该被提升到 node_modules/.pnpm/node_modules。 默认情况下，所有包都被提升 — 但是，如果你知道只有某些有缺陷的包具有幻影依赖，你可以使用此选项专门提升幻影依赖（推荐做法）。

例如：

hoistPattern:
- "*eslint*"
- "*babel*"

你还可以在模式前面添加 ! 来避免提升。

例如：

hoistPattern:
- "*types*"
- "!@types/react"

publicHoistPattern​

  • 默认值：[]
  • 类型：string[]

不同于 hoist-pattern 会把依赖提升到一个虚拟存储中的隐藏的模块目录中，publicHoistPattern 将匹配的依赖提升至根模块目录中。 提升至根模块目录中意味着应用代码可以访问到幻影依赖，即使它们对解析策略做了不当的修改。

当处理一些不能正确解析依赖关系的有缺陷可插拔工具时，此设置很有用。

例如：

publicHoistPattern:
- "*plugin*"

注意：设置 shamefully-hoist 为 true 与设置 public-hoist-pattern 为 * 是一样的。

你还可以在模式前面添加 ! 来避免提升。

例如：

publicHoistPattern:
- "*types*"
- "!@types/react"

shamefullyHoist​

  • 默认值： false
  • 类型：Boolean

默认情况下，pnpm 创建一个半严格的 node_modules，这意味着依赖项可以访问未声明的依赖项，但 node_modules 之外的模块不行。 通过这种布局，生态系统中的大多数的包都可以正常工作。 但是，如果某些工具仅在提升的依赖项位于根目录的 node_modules 时才有效，你可以将其设置为 true 来提升它们。

hoistingLimits​

添加于：v11.5.0

  • 默认： none
  • 类型：none， workspaces， dependencies

控制在使用 nodeLinker: hoisted 时依赖项的提升层级。 此设置对应于 Yarn 的 nmHoistingLimits。

  • none - 尽可能向上提升（默认值）。
  • workspaces —— 仅将依赖提升至各自的工作区包层级，防止依赖被提升至依赖它们的那个工作区包之上。
  • dependencies —— 仅向上提升至各工作区包的直接依赖，从而防止传递依赖被提升到该工作区包的 node_modules 中。