团队踩坑实录:用 patch-package 临时修复第三方依赖的最佳实践

大家好,我是三十。今天想分享一个在团队里实际用到的工具------patch-package。它很好地解决了一个我们可能都遇到过的问题:如何临时修复一个第三方 npm 包中的 bug。

事情起因是团队里一个项目在构建时突然报错,排查后发现问题出在一个间接依赖的包上。这个包有个小bug,但在我们的使用场景下会被触发。

开发环境下对 node-modules 中的源码进行调试修改后发现是可以修复的,所以决定将这一修改作为一个临时解决方案。

但大家都知道,这个目录下的改动既不能保存,也无法和团队共享。今天你改好了,明天同事拉代码或服务器部署时又会失败。

调研后决定先通过 patch-package 临时解决。


patch-package 的工作原理

在对 node_modules 中的源码进行修改后,运行 patch-package 命令,它会把你对 node_modules 的修改记录下来,生成一个补丁文件 .patch 文件,保存在项目根目录下的 patches 文件夹中。

这样我们只需要每次 install 之后再去执行这些补丁文件就可以了。

而为了项目中所有人都可以共享这些补丁,所以需要将补丁文件和项目本身一起提交到 git 仓库中。这样,一个本地临时的修改,就变成了一个可共享、可重复的解决方案。


最佳实践

对 node_modules 中的源码巴拉巴拉一顿操作后把 bug 修复了。

1. 安装 patch-package postinstall-postinstall

为什么要使用 postinstall-postinstall,直接配置 postinstall 脚本不可以吗?后面 注意事项 中有解释。

csharp 复制代码
yarn add patch-package postinstall-postinstall

2. 配置 package.json

package.json 文件中,添加一个 postinstall 脚本来确保在安装依赖后应用补丁:

json 复制代码
"scripts": {
  "postinstall": "patch-package"
}

3. 创建补丁

go 复制代码
npx patch-package some-package # some-package 是 npm 包名

执行命令后会在项目根目录下创建一个 patches 文件夹,并在其中生成一个名为 xxxxx.patch 的补丁文件。

4. 提交补丁文件到代码仓库

sql 复制代码
git add patches/xxxxx.patch
git commit -m "修改三方库中的 bug"
git push origin main

5. 安装依赖并应用补丁

当执行了 install 命令后,postinstall 脚本会自动运行,patch-package 会自动检测 patches 文件夹中的补丁,并将其应用到对应的依赖上。


注意事项

为什么使用 postinstall-postinstall

Yarn 和 npm 对 postinstall 脚本的触发行为有差异:

  • npm: 在运行 npm install 后,它会自动运行 postinstall 脚本。
  • yarn: 在 v1 版本的默认情况下,postinstall 脚本只会在你 直接安装 某个包(例如 yarn add package-x)之后运行,但在后续 单纯运行 yarnyarn install 来安装所有依赖时,它 不会 自动运行。

这就导致一个问题:如果你只按照常规配置 "postinstall": "patch-package",那么当你的同事克隆项目后运行 yarn install,补丁可能根本不会被应用!

postinstall-postinstall 这个包,则可以确保 postinstall 脚本在 每一次 yarn install 之后都能被执行。

总结

通过 patch-package 可以把临时解决方案变得规范起来,避免团队协作和部署时的坑。同时在使用时建议在项目文档或 README 中简单记录一下对哪个包打了补丁、原因是什么,方便后续追踪。

如果你还没遇到过类似问题,可以先把它收进工具箱;如果已经遇到了,希望这个分享能帮到你。

相关推荐
拜无忧8 小时前
【案例】可视化模板,驾驶舱模板,3x3,兼容移动
前端·echarts·数据可视化
向葭奔赴♡8 小时前
前端框架学习指南:提升开发效率
前端·javascript·vue.js
小高0078 小时前
🔥🔥🔥Vue 3.5 核弹级小补丁:useTemplateRef 让 ref 一夜失业?
前端·javascript·vue.js
小许哥8 小时前
如何把微信小程序转换成支付宝小程序
前端
汤姆Tom8 小时前
CSS 最佳实践与规范
前端·css
golang学习记8 小时前
VS Code 2025 最顺眼又顺手的插件,效率Max,太上头了!
前端
一个不爱写代码的瘦子8 小时前
Map、weakMap和Set、weakSet
前端·javascript
认真的编剧8 小时前
freecodecamp全通关之CSS画喵咪
前端
_AaronWong8 小时前
Electron视频黑屏之谜:从H265编码到GPU禁用的深度排查
前端·electron·视频编码