还在为第三方包 bug 头疼？patch-package 让你轻松打补丁！

什么是 patch-package？

简单来说，patch-package 就是一个让你能够修改 node_modules 里第三方包的工具。我们都知道，直接修改 node_modules 里的文件是不靠谱的，因为每次重新安装依赖，你的修改就没了。

patch-package 就是来解决这个痛点的！它会把你的修改保存成补丁文件，每次安装依赖时自动应用这些补丁。

为什么需要 patch-package？

想象一下这些场景：

• 你发现某个 npm 包有个 bug，但作者还没修复
• 你需要给某个包添加一个小功能
• 某个包的 API 不符合你的需求，需要微调

以前遇到这种情况，你只能：

1. 等作者修复（可能等到天荒地老）
2. Fork 一个仓库自己维护（太麻烦了）
3. 直接改 node_modules（每次重装就没了）

现在有了 patch-package，这些问题都不是事儿！

安装和配置

1. 安装 patch-package

# 作为开发依赖安装
npm install patch-package --save-dev

# 或者用 yarn
yarn add patch-package --dev

# 或者用 pnpm
pnpm add patch-package --dev

2. 配置 postinstall 脚本

在 package.json 里添加：

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

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

使用步骤

第一步：修改 node_modules 里的文件

找到你要修改的包，直接编辑文件。比如我要修改 lodash 的某个函数：

# 找到文件位置
node_modules/lodash/index.js

直接打开编辑，做你想要的修改。

第二步：生成补丁文件

修改完成后，运行：

npx patch-package lodash

这会在项目根目录生成一个 patches 文件夹，里面有个 lodash+4.17.21.patch 文件。

实际使用案例

案例 1：修复第三方包的 bug

假设 some-package 有个 bug，你找到了问题所在：

// node_modules/some-package/lib/utils.js
// 原来的代码有问题
function processData(data) {
  return data.map((item) => item.value); // 这里可能报错
}

// 你修改成：
function processData(data) {
  if (!Array.isArray(data)) return [];
  return data.map((item) => item?.value || null);
}

然后运行：

npx patch-package some-package

案例 2：添加新功能

给某个包添加一个你需要的功能：

// node_modules/awesome-lib/src/index.js
// 在文件末尾添加
export function myCustomFunction() {
  return "Hello from patch!";
}

生成补丁：

npx patch-package awesome-lib

注意事项

1. 版本兼容性

补丁文件包含版本号，如果包升级了，补丁可能不兼容。这时候需要：

• 重新修改新版本的文件
• 重新生成补丁

2. 防止自动升级

补丁文件包含版本号，如果包升级了，补丁可能不兼容。这时候需要：

• 锁定补丁模块的版本号

// 锁定补丁模块的版本号，防止自动升级
dependencies: {
  "lodash": "4.17.21"
}

记得把 patches 文件夹提交到版本控制，这样团队成员都能享受到你的修改。

3. 补丁文件管理

• 定期检查补丁是否还有必要
• 如果原包已经修复了 bug，记得删除对应的补丁
• 给补丁文件写清楚注释，说明为什么需要这个补丁

最佳实践

1. 先尝试其他方案：能通过配置解决的问题，就不要用补丁
2. 及时反馈：发现 bug 后，记得给原仓库提 issue 或 PR
3. 文档化：在补丁文件里写清楚修改原因
4. 定期清理：定期检查哪些补丁已经不需要了

总结

patch-package 是一个超级实用的工具，特别适合：

• 快速修复第三方包的 bug
• 给包添加小功能
• 临时解决依赖问题

虽然它很强大，但也要谨慎使用。记住，补丁只是临时方案，最好的做法还是推动原包作者修复问题。

现在你可以放心地修改 node_modules 了，再也不用担心修改会丢失！