Skip to main content
Version: 10.x

pnpm patch <pkg>

准备一个用于修补的包（受到 Yarn 中类似命令的启发）。

🌐 Prepare a package for patching (inspired by a similar command in Yarn).

此命令将导致将包提取到可随意编辑的临时目录中。

🌐 This command will cause a package to be extracted in a temporary directory intended to be editable at will.

完成修改后，运行 pnpm patch-commit <path>（其中 <path> 是你收到的临时目录）来生成补丁文件，并通过 patchedDependencies 字段将其注册到你的顶层清单中。

🌐 Once you're done with your changes, run pnpm patch-commit <path> (with <path> being the temporary directory you received) to generate a patchfile and register it into your top-level manifest via the patchedDependencies field.

用法：

🌐 Usage:

pnpm patch <pkg name>@<version>
note

如果你想更改一个软件包的依赖，不要通过修改软件包的 package.json 文件来使用补丁。要覆盖依赖，请使用 overrides 或 package hook。

🌐 If you want to change the dependencies of a package, don't use patching to modify the package.json file of the package. For overriding dependencies, use overrides or a package hook.

选项​

🌐 Options

--edit-dir <dir>​

需要打补丁的包会被解压到该目录下。

🌐 The package that needs to be patched will be extracted to this directory.

--ignore-existing​

打补丁时忽略现有补丁文件。

🌐 Ignore existing patch files when patching.

配置​

🌐 Configuration

patchedDependencies​

当你运行 pnpm patch-commit 时，该字段会被自动添加/更新。它使用字典来定义依赖的补丁，其中：

🌐 This field is added/updated automatically when you run pnpm patch-commit. It defines patches for dependencies using a dictionary where:

  • 键：具有精确版本、版本范围或仅名称的软件包名称。
  • 值：补丁文件的相对路径。

示例：

🌐 Example:

patchedDependencies:
  express@4.18.1: patches/express@4.18.1.patch

依赖可以按版本范围进行修补。优先顺序如下：

🌐 Dependencies can be patched by version range. The priority order is:

  1. 精确版本（最高优先级）
  2. 版本范围
  3. 仅指定名称的补丁（适用于所有版本，除非被覆盖）

一个特殊情况：版本范围 * 的行为类似于仅限名称的补丁，但不会忽略补丁失败。

🌐 A special case: the version range * behaves like a name-only patch but does not ignore patch failures.

示例：

🌐 Example:

patchedDependencies:
  foo: patches/foo-1.patch
  foo@^2.0.0: patches/foo-2.patch
  foo@2.1.0: patches/foo-3.patch
  • patches/foo-3.patch 应用于 foo@2.1.0。
  • patches/foo-2.patch 适用于所有匹配 ^2.0.0 的 foo 版本，除了 2.1.0。
  • patches/foo-1.patch 适用于所有其他的 foo 版本。

避免版本范围重叠。如果需要具体化子范围，请明确将其从更广的范围中排除。

🌐 Avoid overlapping version ranges. If you need to specialize a sub-range, explicitly exclude it from the broader range.

示例：

🌐 Example:

patchedDependencies:
  # Specialized sub-range
  "foo@2.2.0-2.8.0": patches/foo.2.2.0-2.8.0.patch
  # General patch, excluding the sub-range above
  "foo@>=2.0.0 <2.2.0 || >2.8.0": patches/foo.gte2.patch

在大多数情况下，定义一个精确的版本就足以覆盖更大范围的补丁。

🌐 In most cases, defining an exact version is enough to override a broader range.

allowUnusedPatches​

新增于：v10.7.0（以前名为 allowNonAppliedPatches）

🌐 Added in: v10.7.0 (Previously named allowNonAppliedPatches)

  • 默认：假
  • 类型：布尔

当 true 时，如果 patchedDependencies 字段中的某些补丁未被应用，安装也不会失败。

🌐 When true, installation won't fail if some of the patches from the patchedDependencies field were not applied.

patchedDependencies:
  express@4.18.1: patches/express@4.18.1.patch
allowUnusedPatches: true

ignorePatchFailures​

新增于：v10.7.0

🌐 Added in: v10.7.0

  • 默认：未定义
  • 类型：布尔值、未定义

控制补丁失败的处理方式。

🌐 Controls how patch failures are handled.

行为：

🌐 Behaviour:

  • 未定义（默认）：
    • 当具有精确版本或版本范围的补丁失败时会抛出错误。
    • 忽略仅指定名称的补丁导致的失败。
  • false：任何补丁失败都会出错。
  • true：当任何补丁无法应用时，打印警告而不是失败。