bun patch 以可維護、對 Git 友好的方式持久化修補 node_modules 中的包。

有時你需要對 node_modules/ 中的包進行小幅修改，以修復 bug 或新增功能。bun patch 讓你無需將整個包納入專案即可完成這些操作。

功能特點：

生成 .patch 檔案，Bun 會在安裝時將其應用於 node_modules 中的相依項
你可以將 .patch 檔案提交到儲存庫，並在不同的安裝、專案和機器之間重複使用
package.json 中的 "patchedDependencies" 會跟蹤已修補的包
修補 node_modules/ 中的包，同時保留 Bun Global Cache 的完整性
使用 bun patch --commit <pkg> 提交修改前，可在本地測試修改
為了節省磁碟空間並加快 bun install，Bun 會將修補後的包提交到 Global Cache，並儘可能在多個專案之間共享

第 1 步. 準備包進行補丁

使用 bun patch <pkg> 準備要修補的包：

terminal

# 你可以直接提供包名
bun patch react

# 如果安裝了多個版本，可以指定精確版本
bun patch react@17.0.2

# 也可以提供包的路徑
bun patch node_modules/react

第 2 步. 本地測試你的修改

bun patch <pkg> 讓你可以直接安全地編輯 node_modules/ 中的 <pkg>，同時保留 Bun Global Cache 的完整性。它會在 node_modules/ 中重新建立一個沒有連結的包副本。隨後，bun patch --commit <pkg> 會將該副本與 Global Cache 中的原始包進行差異比較。

第 3 步. 提交修改

當你滿意修改後，執行 bun patch --commit <路徑或包名>。

Bun 會在 patches/ 中生成補丁檔案，更新你的 package.json 和鎖檔案，並開始使用修補後的包：

terminal

# 你可以提供已修補包的路徑
bun patch --commit node_modules/react

# 或只是包名，外加可選版本號
bun patch --commit react@17.0.2

# 指定存放補丁檔案的目錄
bun patch --commit react --patches-dir=mypatches

# 為相容 pnpm，可使用 patch-commit
bun patch-commit react

CLI 使用說明

bash

bun patch <package>@<version>

補丁生成

--commitboolean

安裝包含 dir 中修改內容的包

--patches-dirstring

補丁檔案存放目錄（僅當使用 --commit 時生效）

相依管理

--productionboolean

不安裝 devDependencies。別名：-p

--ignore-scriptsboolean

跳過所有包的生命週期指令碼，包括專案的 package.json 和可信賴的相依項

--trustboolean

新增到專案 package.json 的 trustedDependencies 並安裝該包

--globalboolean

全域性安裝。別名：-g

--omitstring

從安裝中排除 dev，optional 或 peer 相依

專案檔案與鎖檔案

--yarnboolean

寫入 yarn.lock 檔案（yarn v1）。別名：-y

--no-saveboolean

不更新 package.json 或儲存鎖檔案

--savebooleandefault true

儲存至 package.json（預設開啟）

--frozen-lockfileboolean

禁止修改鎖檔案

--save-text-lockfileboolean

儲存文本格式的鎖檔案

--lockfile-onlyboolean

僅生成鎖檔案，不安裝相依

安裝控制

--backendstring

用於安裝相依項的平臺專屬最佳化。可能的值：clonefile（macOS 上的預設值）、hardlink（Linux 和 Windows 上的預設值）、symlink、copyfile

--linkerstring

連結策略（isolated 或 hoisted 其中之一）

--minimum-release-agenumber

僅安裝至少在 N 秒前釋出的包（安全功能）

--dry-runboolean

不安裝包、不更新 package.json，也不儲存鎖檔案。仍會將包複製到 node_modules 以供打補丁，並且 --commit 仍會寫入補丁檔案

--forceboolean

始終請求最新版本並重新安裝所有相依。別名：-f

--no-verifyboolean

跳過驗證新下載包的完整性

網路與登錄檔

--castring

提供證書頒發機構簽名證書

--cafilestring

同 --ca，但為證書檔案路徑

--registrystring

使用指定的登錄檔，覆蓋 .npmrc、bunfig.toml 及環境變數

--network-concurrencynumberdefault 48

最大並行網路請求數（預設48）

效能與資源

--concurrent-scriptsnumber

生命週期指令碼的最大並行任務數（預設為 CPU 核心數的 2 倍）

快取

--cache-dirstring

從指定目錄儲存和載入快取資料

--no-cacheboolean

完全忽略清單快取

輸出與日誌

--silentboolean

不輸出任何日誌

--quietboolean

停用進度條

--verboseboolean

非常詳細的日誌輸出

--no-progressboolean

停用進度條

--no-summaryboolean

不列印摘要資訊

平臺目標

--cpustring

覆蓋可選相依的 CPU 架構（例如 x64，arm64，* 表示全部）

--osstring

覆蓋可選相依的作業系統（例如 linux，darwin，* 表示全部）

全域性設定與上下文

--configstring

指定設定檔路徑（bunfig.toml）。別名：-c

--cwdstring

設定當前工作目錄

幫助

--helpboolean

列印此幫助選單。別名：-h