> ## Documentation Index
> Fetch the complete documentation index at: https://bun.zhcndoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# bun 补丁

> 以对 git 友好的方式持久化修补 node_modules 包

`bun patch` 让你可以以一种可维护且对 git 友好的方式持久化修补 node\_modules。

有时候，你需要对 `node_modules/` 中的某个包进行小的改动，以修复 bug 或添加功能。`bun patch` 让你无需引入整个包（vendor），即可做到这一点，并且可以将补丁复用到多次安装、多个项目和多台机器上。

功能特点：

* 生成应用于 `node_modules` 依赖的 `.patch` 文件（在安装时生效）
* `.patch` 文件可以提交到你的仓库，跨多次安装、项目和机器复用
* `package.json` 中的 `"patchedDependencies"` 用以追踪已修补的包
* `bun patch` 允许你对 `node_modules/` 中的包进行补丁修改，同时保持 Bun [全局缓存](/pm/global-cache) 的完整性
* 使用 `bun patch --commit <pkg>` 可在提交补丁前，本地测试修改
* 为节省磁盘空间并保持 `bun install` 的速度，修补的包会提交到全局缓存，并在可能的情况下跨项目共享

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

开始时，使用 `bun patch <pkg>` 来准备补丁包：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 你可以直接提供包名
bun patch react

# 如果安装了多个版本，可以指定精确版本
bun patch react@17.0.2

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

<Note>
  别忘了执行 `bun patch <pkg>`！这一步可确保 `node_modules/` 中的包文件夹包含一份不带软链接/硬链接至 Bun 缓存的全新副本。

  如果忘记执行这步，你可能会误修改全局缓存中的包！
</Note>

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

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

#### 第 3 步. 提交修改

当你满意修改后，执行 `bun patch --commit <路径或包名>`。

Bun 会在 `patches/` 生成补丁文件，更新你的 `package.json` 和锁文件，随后 Bun 会开始使用补丁包：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 你可以提供已修补包的路径
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 theme={"theme":{"light":"github-light","dark":"dracula"}}
bun patch <package>@<version>
```

### 补丁生成

<ParamField path="--commit" type="boolean">
  安装包含 <code>dir</code> 中修改内容的包
</ParamField>

<ParamField path="--patches-dir" type="string">
  补丁文件存放目录（仅当使用 --commit 时生效）
</ParamField>

### 依赖管理

<ParamField path="--production" type="boolean">
  不安装 devDependencies。别名：<code>-p</code>
</ParamField>

<ParamField path="--ignore-scripts" type="boolean">
  跳过项目 <code>package.json</code> 中的生命周期脚本（依赖的脚本永远不会执行）
</ParamField>

<ParamField path="--trust" type="boolean">
  添加到项目 <code>package.json</code> 的 <code>trustedDependencies</code> 并安装该包
</ParamField>

<ParamField path="--global" type="boolean">
  全局安装。别名：<code>-g</code>
</ParamField>

<ParamField path="--omit" type="string">
  从安装中排除 <code>dev</code>，<code>optional</code> 或 <code>peer</code> 依赖
</ParamField>

### 项目文件与锁文件

<ParamField path="--yarn" type="boolean">
  写入 <code>yarn.lock</code> 文件（yarn v1）。别名：<code>-y</code>
</ParamField>

<ParamField path="--no-save" type="boolean">
  不更新 <code>package.json</code> 或保存锁文件
</ParamField>

<ParamField path="--save" type="boolean" default="true">
  保存至 <code>package.json</code>（默认开启）
</ParamField>

<ParamField path="--frozen-lockfile" type="boolean">
  禁止修改锁文件
</ParamField>

<ParamField path="--save-text-lockfile" type="boolean">
  保存文本格式的锁文件
</ParamField>

<ParamField path="--lockfile-only" type="boolean">
  仅生成锁文件，不安装依赖
</ParamField>

### 安装控制

<ParamField path="--backend" type="string" default="clonefile">
  针对依赖安装的特定平台优化。可选值：<code>clonefile</code>（默认），<code>hardlink</code>，<code>symlink</code>，<code>copyfile</code>
</ParamField>

<ParamField path="--linker" type="string">
  链接策略（<code>isolated</code> 或 <code>hoisted</code> 其中之一）
</ParamField>

<ParamField path="--dry-run" type="boolean">
  不实际安装
</ParamField>

<ParamField path="--force" type="boolean">
  始终请求最新版本并重新安装所有依赖。别名：<code>-f</code>
</ParamField>

<ParamField path="--no-verify" type="boolean">
  跳过验证新下载包的完整性
</ParamField>

### 网络与注册表

<ParamField path="--ca" type="string">
  提供证书颁发机构签名证书
</ParamField>

<ParamField path="--cafile" type="string">
  同 <code>--ca</code>，但为证书文件路径
</ParamField>

<ParamField path="--registry" type="string">
  使用指定的注册表，覆盖 <code>.npmrc</code>、<code>bunfig.toml</code> 及环境变量
</ParamField>

<ParamField path="--network-concurrency" type="number" default="48">
  最大并发网络请求数（默认48）
</ParamField>

### 性能与资源

<ParamField path="--concurrent-scripts" type="number" default="5">
  生命周期脚本最大并发数（默认5）
</ParamField>

### 缓存

<ParamField path="--cache-dir" type="string">
  从指定目录存储和加载缓存数据
</ParamField>

<ParamField path="--no-cache" type="boolean">
  完全忽略清单缓存
</ParamField>

### 输出与日志

<ParamField path="--silent" type="boolean">
  不输出任何日志
</ParamField>

<ParamField path="--quiet" type="boolean">
  打包时仅显示压缩包名称
</ParamField>

<ParamField path="--verbose" type="boolean">
  非常详细的日志输出
</ParamField>

<ParamField path="--no-progress" type="boolean">
  禁用进度条
</ParamField>

<ParamField path="--no-summary" type="boolean">
  不打印摘要信息
</ParamField>

### 平台目标

<ParamField path="--cpu" type="string">
  覆盖可选依赖的 CPU 架构（例如 <code>x64</code>, <code>arm64</code>, <code>\*</code> 表示全部）
</ParamField>

<ParamField path="--os" type="string">
  覆盖可选依赖的操作系统（例如 <code>linux</code>, <code>darwin</code>, <code>\*</code> 表示全部）
</ParamField>

### 全局配置与上下文

<ParamField path="--config" type="string">
  指定配置文件路径（<code>bunfig.toml</code>）。别名：<code>-c</code>
</ParamField>

<ParamField path="--cwd" type="string">
  设置当前工作目录
</ParamField>

### 帮助

<ParamField path="--help" type="boolean">
  打印此帮助菜单。别名：<code>-h</code>
</ParamField>