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