Skip to main content
Version: 11.x

配置依赖

配置依赖允许你在多个项目之间共享和集中管理配置文件、设置和钩子。它们会在所有常规依赖（“dependencies”、“devDependencies”、“optionalDependencies”）之前安装，使其非常适合设置自定义钩子、补丁和目录条目。

🌐 Config dependencies allow you to share and centralize configuration files, settings, and hooks across multiple projects. They are installed before all regular dependencies ("dependencies", "devDependencies", "optionalDependencies"), making them ideal for setting up custom hooks, patches, and catalog entries.

配置依赖可帮助你将所有钩子、设置、补丁、覆盖、目录和规则保存在一个位置，并在多个存储库中使用它们。

🌐 Config dependencies help you keep all the hooks, settings, patches, overrides, catalogs, rules in a single place and use them across multiple repositories.

如果你的配置依赖按照 pnpm-plugin-*、@*/pnpm-plugin-* 或 @pnpm/plugin-* 的模式命名，pnpm 将自动从包根目录加载其 pnpmfile.mjs（如果没有则回退到 pnpmfile.cjs）。

🌐 If your config dependency is named following the pnpm-plugin-*, @*/pnpm-plugin-*, or @pnpm/plugin-* pattern, pnpm will automatically load its pnpmfile.mjs (falling back to pnpmfile.cjs) from the package root.

如何添加配置依赖​

🌐 How to Add a Config Dependency

配置依赖在你的 pnpm-workspace.yaml 中定义。它们的完整性校验和存储在 pnpm-lock.yaml 中（在专用的环境锁定文件文档中）。

🌐 Config dependencies are defined in your pnpm-workspace.yaml. Their integrity checksums are stored in pnpm-lock.yaml (in a dedicated env lockfile document).

例如，运行 pnpm add --config my-configs 会将此条目添加到你的 pnpm-workspace.yaml 中：

🌐 For example, running pnpm add --config my-configs will add this entry to your pnpm-workspace.yaml:

pnpm-workspace.yaml
configDependencies:
  my-configs: "1.0.0"

重要:

  • 配置依赖 不能 拥有自己的常规 dependencies。它们 可以 声明 optionalDependencies，但只能一层深——optionalDependencies 的 optionalDependencies 会被忽略。
  • 配置依赖 不能 定义生命周期脚本（如 preinstall、postinstall 等）。

通过 optionalDependencies 提供的平台特定二进制文件​

🌐 Platform-specific binaries via optionalDependencies

配置依赖可能通过 optionalDependencies 提供特定平台的二进制文件，这与 esbuild 和 swc 等工具使用的模式相同。每个平台二进制包通过 os、cpu 和/或 libc 字段声明其支持的平台，而 pnpm 只安装与当前主机匹配的版本。匹配的二进制文件会在全局虚拟存储中与父配置依赖并排创建符号链接，因此配置依赖内部的 require('my-config-platform-arch') 在运行时可以解析。

🌐 A config dependency may ship platform-specific binaries via optionalDependencies, the same pattern used by tools like esbuild and swc. Each platform-binary package declares its supported platform with os, cpu, and/or libc fields, and pnpm installs only the variant that matches the current host. The matching binary is symlinked next to the parent config dependency in the global virtual store, so require('my-config-platform-arch') from inside the config dependency resolves at runtime.

环境锁文件记录所有平台变体，无论主机平台如何，因此锁文件可以在不同机器之间保持可移植性。

🌐 The env lockfile records all platform variants regardless of host platform, so the lockfile stays portable across machines.

optionalDependencies 中的每一条目都必须使用确切版本声明（例如 "1.2.3"）——范围（"^1.0.0"、"~1.0.0"）和标签（"latest"）将被拒绝。这可以保持 config-dep 安装的可重现性：对于由完整性固定的父项，解析出的子依赖不会在不同机器间发生漂移。

🌐 Each entry in optionalDependencies must be declared with an exact version (e.g. "1.2.3") — ranges ("^1.0.0", "~1.0.0") and tags ("latest") are rejected. This keeps config-dep installs reproducible: the resolved subdep can't drift between machines for a parent that's pinned by integrity.

用法​

🌐 Usage

安装钩子中使用的依赖​

🌐 Installing Dependencies Used in Hooks

配置依赖在加载你的 .pnpmfile.mjs 的钩子之前被安装，从而允许你从配置包中导入逻辑。

🌐 Config dependencies are installed before hooks from your .pnpmfile.mjs are loaded, allowing you to import logic from config packages.

示例：

🌐 Example:

.pnpmfile.mjs
import { readPackage } from '.pnpm-config/my-hooks'

export const hooks = {
  readPackage
}

动态更新 pnpm 设置​

🌐 Updating pnpm Settings Dynamically

使用 updateConfig 钩子，你可以通过配置依赖动态更新 pnpm 的设置。

🌐 Using the updateConfig hook, you can dynamically update pnpm’s settings using config dependencies.

例如，以下 pnpmfile 会向 pnpm 的配置中添加一个新的 catalog 条目：

🌐 For example, the following pnpmfile adds a new catalog entry to pnpm's configuration:

@myorg/pnpm-plugin-my-catalogs/pnpmfile.mjs
export const hooks = {
  updateConfig (config) {
    config.catalogs.default ??= {}
    config.catalogs.default['is-odd'] = '1.0.0'
    return config
  }
}

如果你将其安装为配置依赖：

🌐 If you install it as config dependency:

pnpm add --config @myorg/pnpm-plugin-my-catalogs

然后你可以运行：

🌐 Then you can run:

pnpm add is-odd@catalog:

这将安装 is-odd@1.0.0 并将以下内容添加到你的 package.json 中：

🌐 This will install is-odd@1.0.0 and add the following to your package.json:

{
  "dependencies": {
    "is-odd": "catalog:"
  }
}

这使得跨项目维护和共享集中配置和依赖版本变得容易。

🌐 This makes it easy to maintain and share centralized configuration and dependency versions across projects.

加载补丁文件​

🌐 Loading Patch Files

你可以引用存储在配置依赖中的[补丁文件]。

🌐 You can reference patch files stored inside config dependencies.

示例：

🌐 Example:

pnpm-workspace.yaml
configDependencies:
  my-patches: "1.0.0"
patchedDependencies:
  react: "node_modules/.pnpm-config/my-patches/react.patch"