简单点

Appearance

pnpm patch 完整使用指南 ​

pnpm patch 是 pnpm 提供的用于临时修改第三方依赖源码的核心命令，无需手动改动 node_modules 内的文件，修改会被妥善管理和复用，下面分步骤详细讲解。

一、核心作用 ​

pnpm patch 的核心作用是：临时修改项目中已安装的第三方 npm 依赖的源码，解决第三方依赖存在的 bug、满足个性化需求等场景，且修改后的内容可被跟踪和复用，避免直接修改 node_modules 导致的修改丢失、团队协作不一致等问题。

二、完整使用步骤 ​

步骤1：生成依赖的可编辑副本 ​

首先，针对已安装的依赖，生成一个可编辑的临时副本，命令格式如下：

bash
# 基本用法：pnpm patch <package-name>[@<version>]
pnpm patch lodash  # 不指定版本（默认当前项目安装的版本）
pnpm patch axios@1.6.0  # 指定具体版本（适用于多版本共存场景）

执行命令后，pnpm 会输出两个关键信息：

  1. 临时编辑目录的路径（类似 /tmp/xxx/lodash）
  2. 后续需要执行的 pnpm patch-commit <临时目录路径> 命令（需留存）

此时，你可以进入该临时目录，对依赖的源码进行任意修改（修改逻辑和普通项目开发一致）。

步骤2：提交修改并生成 patch 文件 ​

当你在临时目录中完成源码修改后，通过以下命令提交修改，生成对应的 patch 文件：

bash
# 格式：pnpm patch-commit <临时编辑目录的路径>
pnpm patch-commit /tmp/xxx/lodash  # 路径替换为步骤1输出的实际路径

执行该命令后，pnpm 会在项目根目录下自动创建 patches 文件夹，并在其中生成一个 patch 文件（命名格式类似 lodash@4.17.21.patch），该文件记录了你的所有修改差异，可被 Git 跟踪。

步骤3：让项目自动应用 patch 修改 ​

修改 package.json 文件，在其中添加 pnpm.patchedDependencies 字段，指定需要应用 patch 的依赖及对应的 patch 文件路径，格式如下：

json
{
  "name": "your-project",
  "version": "1.0.0",
  "pnpm": {
    "patchedDependencies": {
      "lodash@4.17.21": "./patches/lodash@4.17.21.patch",
      "axios@1.6.0": "./patches/axios@1.6.0.patch"  // 多个依赖可依次添加
    }
  }
}

添加完成后，执行以下命令，pnpm 会自动应用 patch 修改到项目的 node_modules 中：

bash
pnpm install  # 或简写 pnpm i

此时，项目运行时会使用你修改后的依赖源码，而非原始的依赖包内容。

步骤4：修改后的更新/维护（可选） ​

  1. 若需要再次修改该依赖：重复步骤1-3，新的 patch 文件会覆盖旧文件（或生成新文件，需同步更新 package.json 中的路径）
  2. 若需要取消 patch 修改：删除 package.json 中对应的 patchedDependencies 配置，删除对应的 patch 文件，再执行 pnpm install 即可恢复原始依赖
  3. 团队协作：将 patches 文件夹和 package.json 提交到 Git 仓库，其他团队成员拉取代码后执行 pnpm install，会自动应用 patch 修改，无需额外操作

三、补充说明 ​

  1. 适用场景：临时修复第三方依赖 bug、个性化定制依赖功能、验证依赖修改效果等，不推荐长期依赖（长期需求建议提 PR 给依赖作者或 fork 后自行维护）
  2. 版本兼容性：pnpm patch 要求 pnpm 版本 ≥ 6.22.0，若版本过低，可通过 pnpm add -g pnpm 升级
  3. 注意事项：修改依赖源码时，尽量保持代码风格一致，避免破坏依赖的原有功能；若依赖后续升级，需重新验证 patch 是否兼容

总结 ​

  1. pnpm patch <包名>：生成可编辑的依赖副本
  2. pnpm patch-commit <临时路径>：提交修改生成 patch 文件
  3. package.json 配置 pnpm.patchedDependencies：关联依赖与 patch 文件
  4. pnpm install：自动应用 patch 修改，团队协作无缝同步

有时候不能修改 package.json，否则流水线编译不过。pnpm-lock.yaml 有记录这个 patch 信息就够了。