如何用 pnpm patch 给 element-plus 打补丁修复线上 bug（以 2.4.4 修复 PR#15197 为例）

背景

在实际项目开发中，依赖的三方库（如 element-plus）难免会遇到 bug。有时候官方虽然已经修复，但新版本升级成本高，或者有兼容性风险。这时，给依赖打补丁是最优雅的解决方案之一。

本文以 element-plus 2.4.4 为例，演示如何用 pnpm 的 patch 机制，优雅地修复 PR#15197 中的 bug，而无需升级到 2.5.0。

---

需求说明

• 项目依赖 [email protected]
• 官方在 2.5.0 修复了一个严重 bug（见 PR#15197）
• 现有项目不方便直接升级 element-plus
• 目标：只打补丁，修复 bug，且能持续跟随依赖升级

---

方案选型

常见的依赖补丁方案有两种：

1. patch-package
   适合 npm/yarn 用户，需手动维护 patch 文件和 postinstall 钩子。
2. pnpm patch
   pnpm 官方支持，自动管理 patch 文件和依赖关系，推荐 pnpm 用户使用。

本文采用 pnpm patch 方案。

---

实操步骤

1. 生成 patch 编辑环境

在项目根目录执行：

pnpm patch element-plus

pnpm 会自动解压 element-plus 到 .pnpm_patched 目录，并用编辑器打开。

---

2. 修改源码

根据 PR#15197 的改动，找到：

• components/date-picker/src/date-picker-com/panel-date-pick.js（lib 目录）
• components/date-picker/src/date-picker-com/panel-date-pick.mjs（es 目录）

分别做如下修改：

将：

const handleDatePick = (value, keepOpen) => {

改为：

const handleDatePick = async (value, keepOpen) => {

并在：

if (props.type === 'datetime') {
  handleFocusPicker()
}

之间插入：

if (props.type === 'datetime') {
  await nextTick()
  handleFocusPicker()
}

⚠️ 注意：element-plus 发布包通常有 lib/ 和 es/ 两套产物，都要 patch，否则有些构建工具（如 Vite）不会生效。

---

3. 保存并退出

保存所有修改，关闭编辑器。pnpm 会提示输入 patch message，随便写个描述，比如 fix: handleFocusPicker delay。

pnpm 会自动生成 patches/element-plus.patch 文件，并在 package.json 里写入：

"pnpm": {
  "patchedDependencies": {
    "element-plus": "patches/element-plus.patch"
  }
}

---

4. 应用 patch

##执行
pnpm install

pnpm 会自动应用 patch 文件到 node_modules。

---

5. 清理缓存，确保 patch 生效

Vite、Webpack 等现代构建工具有缓存，一定要清理缓存，否则 patch 可能不生效。

rm -rf node_modules/.vite dist .cache
pnpm install
pnpm run dev

---

6. 验证 patch 是否生效

• 直接在 node_modules/element-plus/es/components/date-picker/src/date-picker-com/panel-date-pick.mjs 和 lib/ 目录下，搜索你的改动（比如加个 console.log）。
• 页面上触发 date-picker，控制台应有输出。
• 如果没生效，优先怀疑缓存问题或实际用的不是被 patch 的文件。

---

常见问题与排查

1. patch 文件没生效？

   • 检查 package.json 里的 pnpm.patchedDependencies 配置
   • patch 文件路径和 node_modules 结构必须完全一致
   • 清理所有缓存和 lock 文件，重新 install

2. 只 patch 了 lib 或 es 目录？

   • 两个都要 patch，Vite 默认用 es 目录

3. pnpm 版本太低？

   • 建议用 pnpm 7.x 或 8.x，老版本不支持 patchedDependencies

4. 构建工具缓存？

   • 清理 .vite、dist、.cache 等目录

5. 实际用的不是 element-plus？

   • 检查 import 路径，确认用的就是 node_modules 里的 element-plus

---

总结

pnpm patch 是现代前端项目修复三方依赖 bug 的利器。
只需几步，就能优雅地给依赖打补丁，既不影响升级，也方便团队协作和 CI/CD。

遇到类似问题，记得：

• patch lib 和 es 两套产物
• 清理构建缓存
• 检查 patch 是否真正生效

希望本文对你有帮助，欢迎点赞、收藏、评论交流！

---

参考资料：

• element-plus PR#15197
• pnpm patch 官方文档
• patch-package 官方文档

---