背景

在實際項目開發中，依賴的三方庫（如 element-plus）難免會遇到 bug。有時候官方雖然已經修復，但新版本升級成本高，或者有兼容性風險。這時，給依賴打補丁是最優雅的解決方案之一。

本文以 element-plus 2.4.4 為例，演示如何用 pnpm 的 patch 機制，優雅地修復 PR#15197 中的 bug，而無需升級到 2.5.0。

---

需求說明

• 項目依賴 element-plus@2.4.4
• 官方在 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 官方文檔

---