全球套餐

全局包是通过 pnpm add -g 在系统范围内安装的 CLI 工具和实用程序。在 pnpm v11 中，全局包管理被重新设计，以实现更好的隔离性和可靠性。

🌐 Global packages are CLI tools and utilities installed system-wide with pnpm add -g. In pnpm v11, global package management was redesigned for better isolation and reliability.

安装全局包

🌐 Installing global packages

pnpm add -g <pkg>

例如：

🌐 For example:

pnpm add -g typescript prettier eslint

独立安装

🌐 Isolated installations

每个全局安装的包（或一起安装的包组）都有自己的独立安装目录，并拥有自己的 package.json、node_modules/ 和锁文件。这可以防止全局包通过同级依赖冲突、提升更改或版本解析变化而相互干扰。

🌐 Each globally installed package (or group of packages installed together) gets its own isolated installation directory with its own package.json, node_modules/, and lockfile. This prevents global packages from interfering with each other through peer dependency conflicts, hoisting changes, or version resolution shifts.

独立安装存储在 {pnpmHomeDir}/global/v11/{hash}/，其中哈希值是从一起安装的软件包集合中生成的。

🌐 Isolated installations are stored at {pnpmHomeDir}/global/v11/{hash}/, where the hash is derived from the set of packages installed together.

例如，运行以下两个命令：

🌐 For example, running the following two commands:

pnpm add -g typescript
pnpm add -g prettier

创建两个独立隔离的安装 —— typescript 和 prettier 各自拥有自己的 node_modules 树，并且无法影响对方的依赖解析。

🌐 creates two separate isolated installations — typescript and prettier each get their own node_modules tree and cannot affect each other's dependency resolution.

在单个命令中安装多个用 空格分隔 的软件包也会为每个软件包创建一个独立的隔离安装：

🌐 Installing multiple space-separated packages in a single command also creates a separate isolated install for each one:

pnpm add -g eslint prettier

eslint 和 prettier 各自拥有自己的 node_modules 树和锁文件，并且可以独立移除 —— pnpm remove -g eslint 保持 prettier 不受影响。

要将多个包打包到相同的独立安装中——这样它们共享一个 node_modules 树和锁文件，相互解析同伴依赖，并一起被移除——将它们作为逗号分隔的列表传递：

🌐 To bundle multiple packages into the same isolated install — so they share a node_modules tree and lockfile, resolve peer dependencies against each other, and are removed together — pass them as a comma-separated list:

pnpm add -g eslint,prettier

这里 eslint 和 prettier 形成一个单独的安装组。使用 pnpm remove -g 删除其中任何一个都会删除整个组。

🌐 Here eslint and prettier form a single install group. Removing either with pnpm remove -g removes the whole group.

这两种形式可以混合。例如：

🌐 The two forms can be mixed. For example:

pnpm add -g eslint,prettier typescript

在单独安装 typescript 的同时，将 eslint 和 prettier 打包成一个独立安装包。

🌐 bundles eslint and prettier into one isolated install while installing typescript on its own.

目录结构

🌐 Directory layout

{pnpmHomeDir}/global/v11/ 的内容如下:

🌐 The contents of {pnpmHomeDir}/global/v11/ look like:

{pnpmHomeDir}/global/v11/
├── {hash-A}              → symlink → ./{hash-A-target}/
├── {hash-A-target}/      ← isolated install dir
│   ├── package.json      ← lists the packages installed together
│   ├── pnpm-lock.yaml    ← lockfile for this install group
│   └── node_modules/
│       ├── <pkg>/        ← top-level dep, symlinked into the global virtual store
│       └── .pnpm/
├── {hash-B}              → symlink → ./{hash-B-target}/
├── {hash-B-target}/      ← another isolated install dir
└── store/                ← shared global virtual store
    └── ...

• The {hash} entries are symlinks; pnpm scans for them to enumerate active installs.

• The targets are real directories that act as ordinary pnpm projects — each has its own package.json and lockfile.

• The shared store/ directory holds the global virtual store. Each install group's direct dependencies — the entries at the root of its node_modules/ — are symlinks into that store, so the actual package contents are shared rather than copied per group.

• Bin shims live in {pnpmHomeDir}/bin/ and point through the appropriate install group's node_modules.

当一个软件包被移除或其安装组被替换时，哈希符号链接会被更新，孤立的目标目录最终会被 pnpm store prune 清理。

🌐 When a package is removed or its install group is replaced, the hash symlink is updated and orphaned target directories are eventually cleaned up by pnpm store prune.

列出全局包

🌐 Listing global packages

pnpm list -g
pnpm list -g --json        # machine-readable
pnpm list -g --parseable   # paths only

因为每个安装组都有自己的锁文件，跨多个组列出的信息只能可靠地汇总它们安装时的顶层包——来自不同组的传递依赖树无法被一致地合并。因此：

🌐 Because each install group has its own lockfile, listing across multiple groups can only reliably aggregate the top-level packages they were installed with — transitive dependency trees from different groups can't be coherently merged. As a result:

• pnpm list -g (default --depth=0) always works and shows every globally installed package.

• pnpm list -g --depth=<n> (with n > 0) shows the full dependency tree only when:

  • 只有一个全局安装组，或者
  • 一个位置参数将请求缩小到单个安装组，例如 pnpm list -g eslint --depth=1。

如果请求了 --depth>0 但请求无法缩小到单个安装组，pnpm 会报错 ERR_PNPM_GLOBAL_LS_DEPTH_NOT_SUPPORTED。

🌐 If --depth>0 is requested but the request can't be narrowed to a single install group, pnpm errors with ERR_PNPM_GLOBAL_LS_DEPTH_NOT_SUPPORTED.

管理全局包

🌐 Managing global packages

命令	描述
pnpm add -g <pkg>	全局安装一个包
pnpm remove -g <pkg>	移除全局安装的包（如果它是安装组的一部分，将移除整个组）
pnpm update -g [pkg]	更新全局包（重新安装到新的隔离目录）
pnpm list -g	列出所有全局安装的包

note

pnpm install -g（不带参数）不被支持。使用 pnpm add -g <pkg> 安装特定的包。

二进制文件位置

🌐 Binaries location

全局安装的二进制文件存储在 PNPM_HOME 的 bin 子目录中（即 $PNPM_HOME/bin/）。这保持了 PNPM_HOME 目录的整洁——像 global/ 和 store/ 这样的内部目录不会在 PNPM_HOME 位于 PATH 时污染 shell 自动补全。

🌐 Globally installed binaries are stored in a bin subdirectory of PNPM_HOME (i.e., $PNPM_HOME/bin/). This keeps the PNPM_HOME directory clean — internal directories like global/ and store/ don't pollute shell autocompletion when PNPM_HOME is on PATH.

升级到 pnpm v11 后，运行 pnpm setup 来更新你的 shell 配置，以便 $PNPM_HOME/bin 在你的 PATH 中。

🌐 After upgrading to pnpm v11, run pnpm setup to update your shell configuration so that $PNPM_HOME/bin is on your PATH.

你可以使用以下命令检查当前的全局二进制目录：

🌐 You can check the current global bin directory with:

pnpm bin -g

全球虚拟商店

🌐 Global virtual store

全局安装使用全局虚拟存储。软件包存储在{storeDir}/links，并在全局安装中共享。当多个全局软件包依赖相同库时，这可以避免重复获取。

🌐 Global installs use the global virtual store. Packages are stored at {storeDir}/links and shared across global installations. This avoids redundant fetches when multiple global packages depend on the same libraries.

将本地包注册为全局

🌐 Registering local packages globally

要使本地包的二进制文件在整个系统中可用，请在包目录中使用 pnpm add -g .：

🌐 To make a local package's binaries available system-wide, use pnpm add -g . from the package directory:

cd ~/projects/my-tool
pnpm add -g .

这会注册该包的 bin 条目，以便可以从任何地方调用它们。有关更多详细信息，请参阅 pnpm link。

🌐 This registers the package's bin entries so they can be invoked from anywhere. See pnpm link for more details.

构建脚本审批

🌐 Build script approval

具有构建脚本的全局包（例如，postinstall）需要批准。当你安装需要运行构建脚本的全局包时，pnpm 会提示你以交互方式批准或拒绝该构建。

🌐 Global packages that have build scripts (e.g., postinstall) require approval. When you install a global package that needs to run build scripts, pnpm will prompt you to approve or deny the build interactively.

你也可以使用 --allow-build 标志来预先批准构建：

🌐 You can also pre-approve builds using the --allow-build flag:

pnpm add -g --allow-build=esbuild esbuild