Skip to main content
bun patch 让你可以以一种可维护且对 git 友好的方式持久化修补 node_modules。 有时，你需要对 node_modules/ 中的某个包进行小幅修改，以修复bug或添加功能。bun patch 让这个过程变得简单，无需整体供应包，并且能跨多次安装、多个项目和多台机器复用补丁。 功能特点：
  • 生成应用于 node_modules 依赖的 .patch 文件（在安装时生效）
  • .patch 文件可以提交到你的仓库，跨多次安装、项目和机器复用
  • package.json 中的 "patchedDependencies" 用以追踪已修补的包
  • bun patch 允许你对 node_modules/ 中的包进行补丁修改，同时保持 Bun 全局缓存 的完整性
  • 使用 bun patch --commit <pkg> 可在提交补丁前，本地测试修改
  • 为节省磁盘空间并保持 bun install 的速度，修补的包会提交到全局缓存，并在可能的情况下跨项目共享

​
第 1 步. 准备包进行补丁

开始时，使用 bun patch <pkg> 来准备补丁包：
terminal
# 你可以直接提供包名
bun patch react

# 如果安装了多个版本，可以指定精确版本
bun patch [email protected]

# 也可以提供包的路径
bun patch node_modules/react
别忘了执行 bun patch <pkg>！这一步可确保 node_modules/ 中的包文件夹包含一份不带软链接/硬链接至 Bun 缓存的全新副本。如果忘记执行这步，你可能会误修改全局缓存中的包！

​
第 2 步. 本地测试你的修改

bun patch <pkg> 允许你直接安全地编辑 node_modules/ 中的 <pkg>，同时保全 Bun 全局缓存 的完整性。其原理是在 node_modules/ 中重新创建一个未链接的克隆版本，并与全局缓存中的原始包做差异比对。

​
第 3 步. 提交修改

当你满意修改后，执行 bun patch --commit <路径或包名>。 Bun 会在 patches/ 生成补丁文件，更新你的 package.json 和锁文件，随后 Bun 会开始使用补丁包：
terminal
# 你可以提供已修补包的路径
bun patch --commit node_modules/react

# 或只是包名，外加可选版本号
bun patch --commit [email protected]

# 指定存放补丁文件的目录
bun patch --commit react --patches-dir=mypatches

# 为兼容 pnpm，可使用 patch-commit
bun patch-commit react

​
CLI 使用说明

bun patch <package>@<version>

​
补丁生成

​
--commit
boolean
安装包含 dir 中修改内容的包
​
--patches-dir
string
补丁文件存放目录（仅当使用 —commit 时生效）

​
依赖管理

​
--production
boolean
不安装 devDependencies。别名：-p
​
--ignore-scripts
boolean
跳过项目 package.json 中的生命周期脚本（依赖的脚本永远不会执行）
​
--trust
boolean
添加到项目 package.json 的 trustedDependencies 并安装该包
​
--global
boolean
全局安装。别名：-g
​
--omit
string
从安装中排除 dev，optional 或 peer 依赖

​
项目文件与锁文件

​
--yarn
boolean
写入 yarn.lock 文件（yarn v1）。别名：-y
​
--no-save
boolean
不更新 package.json 或保存锁文件
​
--save
boolean
default:"true"
保存至 package.json（默认开启）
​
--frozen-lockfile
boolean
禁止修改锁文件
​
--save-text-lockfile
boolean
保存文本格式的锁文件
​
--lockfile-only
boolean
仅生成锁文件，不安装依赖

​
安装控制

​
--backend
string
default:"clonefile"
针对依赖安装的特定平台优化。可选值：clonefile（默认），hardlink，symlink，copyfile
​
--linker
string
链接策略（isolated 或 hoisted 其中之一）
​
--dry-run
boolean
不实际安装
​
--force
boolean
始终请求最新版本并重新安装所有依赖。别名：-f
​
--no-verify
boolean
跳过验证新下载包的完整性

​
网络与注册表

​
--ca
string
提供证书颁发机构签名证书
​
--cafile
string
同 —ca，但为证书文件路径
​
--registry
string
使用指定的注册表，覆盖 .npmrc、bunfig.toml 及环境变量
​
--network-concurrency
number
default:"48"
最大并发网络请求数（默认48）

​
性能与资源

​
--concurrent-scripts
number
default:"5"
生命周期脚本最大并发数（默认5）

​
缓存

​
--cache-dir
string
从指定目录存储和加载缓存数据
​
--no-cache
boolean
完全忽略清单缓存

​
输出与日志

​
--silent
boolean
不输出任何日志
​
--quiet
boolean
打包时仅显示压缩包名称
​
--verbose
boolean
非常详细的日志输出
​
--no-progress
boolean
禁用进度条
​
--no-summary
boolean
不打印摘要信息

​
平台目标

​
--cpu
string
覆盖可选依赖的 CPU 架构（例如 x64, arm64, * 表示全部）
​
--os
string
覆盖可选依赖的操作系统（例如 linux, darwin, * 表示全部）

​
全局配置与上下文

​
--config
string
指定配置文件路径（bunfig.toml）。别名：-c
​
--cwd
string
设置当前工作目录

​
帮助

​
--help
boolean
打印此帮助菜单。别名：-h