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

Node-Modules & Hoisting Settings

節點模組設定​

modulesDir​

  • Default: node_modules
  • Type: path

The directory in which dependencies will be installed (instead of node_modules).

nodeLinker​

  • Default: isolated
  • Type: isolated, hoisted, pnp

定義應該使用哪些連結器來安裝 Node 套件。

  • isolated - dependencies are symlinked from a virtual store at node_modules/.pnpm.
  • hoisted - a flat node_modules without symlinks is created. Same as the node_modules created by npm or Yarn Classic. 使用這個設定時，有一個 Yarn 程式庫用於提升。 使用此設定的合法原因：
    1. 您的工具無法與符號連結一起使用。 A React Native project will most probably only work if you use a hoisted node_modules.
    2. 您的專案部署在一個無伺服器的主機服務提供者。 一些無伺服器的提供者 (例如 AWS Lambia) 不支援符號連結。 或者，您也可以在部署之前組合應用程式來解決此問題。
    3. If you want to publish your package with "bundledDependencies".
    4. If you are running Node.js with the --preserve-symlinks flag.
  • pnp - no node_modules. Plug'n'Play is an innovative strategy for Node that is used by Yarn Berry. It is recommended to also set symlink setting to false when using pnp as your linker.

nodeExperimentalPackageMap​

Added in: v11.8.0

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

When true, pnpm injects the generated node_modules/.package-map.json into pnpm-managed Node.js script environments by adding Node's --experimental-package-map option to NODE_OPTIONS.

The package map is generated during isolated and hoisted installs. This setting only controls whether pnpm passes the generated map to scripts.

CLI and environment configuration use the kebab-case name node-experimental-package-map.

nodeExperimentalPackageMap: true

nodePackageMapType​

Added in: v11.8.0

  • Default: standard
  • Type: standard, loose

Controls how node_modules/.package-map.json is generated.

  • standard - only declared dependencies are available through the package map.
  • loose - also maps packages that are reachable through the installed node_modules layout, which can allow undeclared hoisted dependencies to resolve.

CLI and environment configuration use the kebab-case name node-package-map-type.

nodePackageMapType: loose
  • Default: true
  • 型別：布林值

When symlink is set to false, pnpm creates a virtual store directory without any symlinks. It is a useful setting together with nodeLinker=pnp.

enableModulesDir​

  • Default: true
  • 型別：布林值

When false, pnpm will not write any files to the modules directory (node_modules). 這對於模組目錄同使用者空間內檔案系統 (FUSE) 裝載時有幫助。 There is an experimental CLI that allows you to mount a modules directory with FUSE: @pnpm/mount-modules.

virtualStoreDir​

  • Default: node_modules/.pnpm
  • Types: path

包含指向存放區連結的目錄。 專案所有直接和間接依賴的依賴套件都建立了指向此目錄的連結。

這個設定對解決 Windows 上長路徑的問題有幫助。 If you have some dependencies with very long paths, you can select a virtual store in the root of your drive (for instance C:\my-project-store).

Or you can set the virtual store to .pnpm and add it to .gitignore. 這將會讓 StrackTrace 更加簡潔，因為相依套件的路徑將會高出一個目錄。

NOTE: the virtual store cannot be shared between several projects. 每個專案都應該有自己的虛擬存放區 (共用根的工作區內除外)。

virtualStoreDirMaxLength​

  • 預設值：
    • On Linux/macOS: 120
    • On Windows: 60
  • Types: number

Sets the maximum allowed length of directory names inside the virtual store directory (node_modules/.pnpm). You may set this to a lower number if you encounter long path issues on Windows.

virtualStoreOnly​

Added in: v11.0.0

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

When set to true, pnpm populates the virtual store without creating importer symlinks, hoisting, bin links, or running lifecycle scripts. This is useful for pre-populating a store (e.g., in Nix builds) without creating unnecessary project-level artifacts. pnpm fetch uses this mode internally.

packageImportMethod​

  • Default: auto
  • Type: auto, hardlink, copy, clone, clone-or-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 - try to clone packages from the store. 如果不支援複製，則從存放區建立指向套的 Hardlink。 如果再製和建立連結都不可行，則回到複製
  • hardlink - hard link packages from the store
  • clone-or-copy - try to clone packages from the store. 如果不支援再製，則回到複製
  • copy - copy packages from the store
  • clone - clone (AKA copy-on-write or reference link) packages from the store

再製是將套件寫入 node_modules 的最佳方式。 這是最快速、最安全的方式。 使用再製時，您可以在 node_modules 中編輯檔案，而在中央的內容可定址存放區中，它們將不會被修改。

不過，不是所有的檔案系統都支援再製。 我們推薦使用寫入時複製 (CoW) 檔案系統 (例如，在 Linux 上使用 Btrfs 而非 Ext4)，以取得使用 pnpm 的最佳體驗。

modulesCacheMaxAge​

  • Default: 10080 (7 days in minutes)
  • Type: number

模組目錄中的孤立套件應該被移除的時間 (單位為分鐘)。 pnpm 會在模組目錄中保留套件的快取。 這會提高切換分支或降級相依性時的安裝速度。

dlxCacheMaxAge​

  • Default: 1440 (1 day in minutes)
  • Type: number

The time in minutes after which dlx cache expires. After executing a dlx command, pnpm keeps a cache that omits the installation step for subsequent calls to the same dlx command.

enableGlobalVirtualStore​

Added in: v10.12.1

  • 預設值：false
  • 型別：布林值
注意事項

In pnpm v11, global installs (pnpm add -g) and pnpm dlx use the global virtual store by default.

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.

important

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.

相依性提升設定​

hoist​

  • Default: true
  • Type: boolean

When true, all dependencies are hoisted to node_modules/.pnpm/node_modules. This makes unlisted dependencies accessible to all packages inside node_modules.

hoistWorkspacePackages​

  • Default: true
  • Type: 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​

  • Default: ['*']
  • Type: string[]

Tells pnpm which packages should be hoisted to node_modules/.pnpm/node_modules. 在預設情況下，所有的包都是被提升的，但是如果你知道只有一些有缺陷的包有幻影依賴關係， 您可以使用此選項來只提升有幻影依賴關係的包（推薦）。

例如：

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

You may also exclude patterns from hoisting using !.

例如：

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

publicHoistPattern​

  • Default: []
  • Type: 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 *.

You may also exclude patterns from hoisting using !.

例如：

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

shamefullyHoist​

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

By default, pnpm creates a semistrict node_modules, meaning dependencies have access to undeclared dependencies but modules outside of node_modules do not. 使用此頁面配置，生態系統中的大多數套件將沒有問題的運作。 However, if some tooling only works when the hoisted dependencies are in the root of node_modules, you can set this to true to hoist them for you.

hoistingLimits​

Added in: v11.5.0

  • Default: none
  • Type: none, workspaces, dependencies

Controls how far dependencies are hoisted when using nodeLinker: hoisted. This setting mirrors Yarn's nmHoistingLimits.

  • none - hoist as far as possible (the default).
  • workspaces - hoist only as far as each workspace package, preventing dependencies from being hoisted above the workspace package that depends on them.
  • dependencies - hoist only up to each workspace package's direct dependencies, preventing transitive dependencies from being hoisted into the workspace package's node_modules.