patch-package 打补丁方案详解

背景

在日常开发中，我们经常会遇到这样的场景：

• 使用了一个 npm 包，但它有个bug
• 社区的修复还没发布
• 又不想等待官方更新
• 或者这个包已经无人维护了

这时候，patch-package 就是你的解决方案。它可以让你对 node_modules 里的代码打补丁，并在每次 npm install 后自动应用这些补丁。

工作原理

patch-package 的核心原理是 git diff：

1. 记录修改前后 node_modules 中文件的差异
2. 生成 .patch 补丁文件（本质上是 git diff 记录）
3. 在 postinstall 脚本中自动应用这些补丁

使用步骤

步骤一：安装 patch-package

npm install patch-package postinstall-postinstall --save-dev

postinstall-postinstall 用于确保补丁在依赖安装完成后立即应用。

步骤二：修改 node_modules 中的文件

找到需要修复的包，直接修改 node_modules 中对应的文件。

例如，修复 @smallwei/avue 库的问题：

# 定位到 node_modules/@smallwei/avue 的代码，并修改代码

步骤三：生成 patch 补丁文件

npx patch-package @smallwei/avue

执行后，会在项目根目录下生成 patches/@smallwei+avue+x.x.x.patch 文件。

生成的文件结构类似：

patches/
└── @smallwei+avue+3.x.x.patch

步骤四：配置自动应用补丁

在 package.json 的 scripts 中添加：

{
  "scripts": {
    "postinstall": "patch-package"
  }
}

这样，每次执行 npm install 后，都会自动应用补丁。

完整示例

{
  "scripts": {
    "postinstall": "patch-package"
  },
  "dependencies": {
    "@smallwei/avue": "^3.x.x"
  },
  "devDependencies": {
    "patch-package": "^6.x.x",
    "postinstall-postinstall": "^2.x.x"
  }
}

patch 文件解读

生成的 .patch 文件本质上是 git diff 格式，例如：

diff --git a/node_modules/@smallwei/avue/lib/utils.js b/node_modules/@smallwei/avue/lib/utils.js
index abc1234..def5678 100644
--- a/node_modules/@smallwei/avue/lib/utils.js
+++ b/node_modules/@smallwei/avue/lib/utils.js
@@ -10,7 +10,7 @@
-const oldCode = 'xxx'
+const newCode = 'yyy'

进阶用法

为所有修改的包生成补丁

如果一次性修改了多个包，可以一次性生成所有补丁：

npx patch-package

忽略某些包

在 package.json 中配置忽略列表：

{
  "patchPackage": {
    "ignoredPackages": ["some-library"]
  }
}

与 yarn / pnpm 配合

yarn：

{
  "scripts": {
    "postinstall": "patch-package"
  }
}

pnpm：

pnpm v6+ 已经内置了 postinstall 支持，直接使用即可。

注意事项

1. 补丁文件需要提交到版本库：patches/ 目录下的文件必须提交到 git，确保团队成员都能应用相同的补丁

2. 升级包后可能需要更新补丁：当升级被补丁的包时，可能会出现冲突，需要重新生成补丁

3. 补丁路径包含版本号：如果包升级了版本，需要重新运行 npx patch-package <package-name> 生成新补丁

4. 不要修改锁文件版本：否则可能导致补丁应用失败

适用场景

场景	是否适合使用 patch-package
紧急 hotfix	✅ 适合
临时方案	✅ 适合
长期维护的修复	❌ 建议提 PR 给官方
大量修改	❌ 建议 fork 源码

总结

patch-package 是一个简单但强大的工具，它通过 git diff 的原理，让开发者能够灵活地修复第三方包的 bug，而无需等待官方发布更新。

核心流程：

安装 patch-package
    ↓
修改 node_modules 中的文件
    ↓
执行 npx patch-package 生成 .patch 文件
    ↓
配置 postinstall 脚本自动应用