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

# bun patch

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

`bun patch` 以可维护、git 友好的方式持久化修补 `node_modules` 中的包。

有时你需要对 `node_modules/` 中的包进行小的更改来修复 bug 或添加功能。`bun patch` 让你无需引入整个包即可完成此操作。

特性：

* 生成 `.patch` 文件，Bun 在安装时会将其应用到 `node_modules` 中的依赖上
* `.patch` 文件可以提交到你的仓库，并在不同安装、项目和机器之间重用
* `"patchedDependencies"` 在 `package.json` 中跟踪修补过的包
* 修补 `node_modules/` 中的包，同时保持 Bun 的[全局缓存](/pm/global-cache)的完整性
* 在提交之前使用 `bun patch --commit <pkg>` 在本地测试你的更改
* 为节省磁盘空间并保持 `bun install` 快速，修补过的包会被提交到全局缓存并在可能的情况下在项目间共享

#### 步骤 1. 准备要修补的包

使用 `bun patch <pkg>` 准备要修补的包：

```bash terminal icon="terminal" theme={null}
# 你可以提供包名
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 <path or pkg>`。

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

```bash terminal icon="terminal" theme={null}
# 你可以提供修补包的路径
bun patch --commit node_modules/react

# ...或包名以及可选的版本
bun patch --commit react@17.0.2

# 选择存储补丁文件的目录
bun patch --commit react --patches-dir=mypatches

# `patch-commit` 可用于与 pnpm 兼容
bun patch-commit react
```

***

# CLI 用法

```bash theme={null}
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>

### 项目文件与 Lockfile

<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> 或不保存 lockfile
</ParamField>

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

<ParamField path="--frozen-lockfile" type="boolean">
  禁止更改 lockfile
</ParamField>

<ParamField path="--save-text-lockfile" type="boolean">
  保存基于文本的 lockfile
</ParamField>

<ParamField path="--lockfile-only" type="boolean">
  仅生成 lockfile，不安装依赖
</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">
  生命周期脚本的最大并发作业数（默认：2 倍 CPU 核心数）
</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">
  打包时仅显示 tarball 名称
</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>