> ## 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 做出贡献

配置 Bun 的开发环境可能需要 10-30 分钟，具体取决于你的网络连接和计算机速度。仓库和构建工件需要约 10GB 的可用磁盘空间。

如果你使用的是 Windows，请参见 [在 Windows 上构建](/project/building-windows)。

## 使用 Nix（替代方案）

仓库包含一个 Nix flake，作为手动安装依赖的替代方案：

```bash theme={null}
nix develop
bun bd
```

`nix develop` 在隔离、可重现的环境中提供所有依赖项，无需使用 sudo。

## 安装依赖（手动）

使用系统的包管理器安装 Bun 的依赖项：

<CodeGroup>
  ```bash macOS (Homebrew) theme={null}
  brew install automake ccache cmake coreutils gnu-sed go icu4c libiconv libtool ninja pkg-config rustup-init ruby
  ```

  ```bash Ubuntu/Debian theme={null}
  sudo apt install curl wget lsb-release software-properties-common cmake git golang libtool ninja-build pkg-config ruby-full xz-utils
  ```

  ```bash Arch theme={null}
  sudo pacman -S base-devel cmake git go libiconv libtool make ninja pkg-config python rustup sed unzip ruby
  ```

  ```bash Fedora theme={null}
  sudo dnf install clang21 llvm21 lld21 cmake git golang libtool ninja-build pkg-config ruby libatomic-static libstdc++-static sed unzip which libicu-devel 'perl(Math::BigInt)'
  ```

  ```bash openSUSE Tumbleweed theme={null}
  sudo zypper install go cmake ninja automake git icu rustup
  ```
</CodeGroup>

Bun 使用 Rust 编写，需要特定的夜间工具链（在 `rust-toolchain.toml` 中固定）。使用 [rustup](https://rustup.rs) 安装 Rust，而不是使用发行版的 `rust`/`cargo` 软件包——构建脚本使用 rustup 自动安装和更新固定的夜间版本：

```bash theme={null}
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

开始之前，请安装一个发布版本的 Bun：构建过程使用 Bun 的打包器来转译和压缩代码，并运行代码生成脚本。

<CodeGroup>
  ```bash Native theme={null}
  curl -fsSL https://bun.com/install | bash
  ```

  ```bash npm theme={null}
  npm install -g bun
  ```

  ```bash Homebrew theme={null}
  brew tap oven-sh/bun
  brew install bun
  ```
</CodeGroup>

### 可选：安装 `ccache`

`ccache` 缓存编译产物，从而加速重新构建：

```bash theme={null}
# macOS
brew install ccache

# Ubuntu/Debian
sudo apt install ccache

# Arch
sudo pacman -S ccache

# Fedora
sudo dnf install ccache

# openSUSE
sudo zypper install ccache
```

如果 `ccache` 可用，构建脚本会自动检测并使用它。使用 `ccache --show-stats` 查看缓存统计信息。

## 安装 LLVM

Bun 需要 LLVM 21.1.8（`clang` 是 LLVM 的一部分）。构建系统强制执行此版本：版本不匹配会导致运行时内存分配失败。大多数情况下，你可以通过系统包管理器安装 LLVM：

<CodeGroup>
  ```bash macOS (Homebrew) theme={null}
  brew install llvm@21
  ```

  ```bash Ubuntu/Debian theme={null}
  # LLVM 有一个自动安装脚本，兼容所有 Ubuntu 版本
  wget https://apt.llvm.org/llvm.sh -O - | sudo bash -s -- 21 all
  ```

  ```bash Arch theme={null}
  sudo pacman -S llvm clang lld
  ```

  ```bash Fedora theme={null}
  sudo dnf install llvm clang lld-devel
  ```

  ```bash openSUSE Tumbleweed theme={null}
  sudo zypper install clang21 lld21 llvm21
  ```
</CodeGroup>

如果以上都不行，请[手动安装](https://github.com/llvm/llvm-project/releases/tag/llvmorg-21.1.8)。

确保 Clang/LLVM 21 在你的路径中：

```bash theme={null}
which clang-21
```

如果没有，手动添加：

<CodeGroup>
  ```bash macOS (Homebrew) theme={null}
  # 使用 fish 的话用 fish_add_path
  # 使用 zsh 的话用 path+="$(brew --prefix llvm@21)/bin"
  export PATH="$(brew --prefix llvm@21)/bin:$PATH"
  ```

  ```bash Arch theme={null}
  # 使用 fish 的话用 fish_add_path
  export PATH="$PATH:/usr/lib/llvm21/bin"
  ```
</CodeGroup>

<Warning>
  ⚠️ 在 Ubuntu ≤ 20.04 上，你可能需要单独安装 C++ 标准库。请参阅 [故障排除部分](#span-文件未找到-ubuntu)。
</Warning>

## 构建 Bun

克隆仓库后，运行以下命令进行构建。这可能需要一些时间：它会下载并构建依赖项。

```bash theme={null}
bun run build
```

二进制文件位于 `./build/debug/bun-debug`。建议将其添加到你的 `$PATH` 中。验证构建是否成功，打印其版本：

```bash theme={null}
build/debug/bun-debug --version
x.y.z_debug
```

## VSCode

VSCode 是开发 Bun 的推荐 IDE；仓库包含其配置。打开仓库后，运行 `Extensions: Show Recommended Extensions` 安装推荐的 Rust 和 C++ 扩展。rust-analyzer 会自动拾取工作区的 `Cargo.toml`，并使用 `rust-toolchain.toml` 中固定的工具链进行分析，因此诊断信息与构建匹配。

如果你使用其他编辑器，将 rust-analyzer（或你编辑器的 Rust 插件）指向仓库根目录——Cargo 工作区和 `rust-toolchain.toml` 会自动发现。

我们建议将 `./build/debug` 添加到你的 `$PATH` 中，这样你就可以在终端中运行 `bun-debug`：

```sh theme={null}
bun-debug
```

## 运行调试构建

`bd` package.json 脚本编译并运行 Bun 的调试构建，仅在失败时打印构建过程的输出。

```sh theme={null}
bun bd <args>
bun bd test foo.test.ts
bun bd ./foo.ts
```

当 Rust 或 C++ 发生变化时，完整的调试构建可能需要几分钟；cargo 的增量编译使后续纯 Rust 重新构建快得多。如果你的开发工作流是"改一行，保存，重新构建"，你仍然会在链接步骤上花费太多时间。建议：

* 将你的更改批量处理
* 使用 `cargo check -p <crate>`（或对整个工作区使用 `bun run rust:check`）检查 Rust 更改类型，无需链接。`bun run watch` 会在每次保存时运行 `cargo check`。
* 确保 rust-analyzer 正在运行以提供内联诊断（推荐的 VSCode 扩展已设置好）
* 优先使用调试器（VSCode 中的"CodeLLDB"）单步调试代码。
* 使用调试日志。`BUN_DEBUG_<scope>=1` 会启用对应 `declare_scope!(<scope>, ...)` / `scoped_log!(<scope>, ...)` 日志的调试输出。设置 `BUN_DEBUG_QUIET_LOGS=1` 可禁用所有未显式启用的调试日志。要将调试日志转储到文件，设置 `BUN_DEBUG=<path-to-file>.log`。调试日志在发布构建中会被移除。
* `src/js/**/*.ts` 更改几乎可即时重建。单 crate 的 Rust 更改和 C++ 更改是增量的；只有最后的链接步骤是不可避免的。

## 代码生成脚本

Bun 的构建过程会在某些文件发生变化时自动运行多个代码生成脚本：

* `./src/codegen/generate-jssink.ts` — 生成 `build/debug/codegen/JSSink.cpp`、`build/debug/codegen/JSSink.h`，实现与 `ReadableStream` 交互的各种类。这是 `FileSink`、`ArrayBufferSink`、`"type": "direct"` 流及其他流相关代码的内部实现方式。
* `./src/codegen/generate-classes.ts` — 为在 Rust 中实现的 JavaScriptCore 类生成 Rust 和 C++ 绑定。`**/*.classes.ts` 文件定义类、方法、原型和 getter/setter 的接口；代码生成器读取它们以生成实现 JavaScript 对象的样板代码（C++）并将其连接到 Rust。
* `./src/codegen/cppbind.ts` — 扫描 C++ 绑定中标记了导出属性的函数，为其生成自动的 Rust FFI 包装器（`cpp.rs`）。
* `./src/codegen/bundle-modules.ts` — 将内置模块（如 `node:fs`、`bun:ffi`）打包到最终二进制文件中包含的文件中。在开发中，这些模块无需重新构建原生代码即可重新加载（你仍然需要运行 `bun run build`，但之后它会从磁盘重新读取转译后的文件）。在发布构建中，这些会被嵌入到二进制文件中。
* `./src/codegen/bundle-functions.ts` — 打包用 JavaScript/TypeScript 实现的全局可访问函数，如 `ReadableStream` 和 `WritableStream`。这些函数的使用方式与内置模块类似，但输出更接近 WebKit/Safari 处理 Safari 内置函数的方式，因此实现可以作为起点从 WebKit 复制粘贴。

## 修改 ESM 模块

某些模块如 `node:fs`、`node:stream`、`bun:sqlite` 和 `ws` 是用 JavaScript 实现的。它们位于 `src/js/{node,bun,thirdparty}` 文件中，使用 Bun 预打包。

## 发布构建

要编译 Bun 的发布构建，运行：

```bash theme={null}
bun run build:release
```

二进制文件位于 `./build/release/bun` 和 `./build/release/bun-profile`。

### 从 Pull Request 下载发布构建

你可以从 pull request 下载发布构建，而无需在本地构建，这对于在合并前手动测试更改很有用。

使用 `bun-pr` npm 包：

```sh theme={null}
bunx bun-pr <pr-number>
bunx bun-pr <branch-name>
bunx bun-pr "https://github.com/oven-sh/bun/pull/1234566"
bunx bun-pr --asan <pr-number> # 仅限 Linux x64
```

`bun-pr` 从 pull request 的 GitHub Actions 工件中下载发布构建，并将其以 `bun-${pr-number}` 名称添加到 `$PATH`，你可以直接运行：

```sh theme={null}
bun-1234566 --version
```

你可能需要安装 `gh` CLI 来向 GitHub 进行身份验证。

### 从终端查看 CI 失败信息

Bun 的 CI 在 BuildKite 上运行。安装 [BuildKite CLI](https://github.com/buildkite/cli)（`brew install buildkite/buildkite/bk`）并设置 `BUILDKITE_API_TOKEN` 为只读范围的 [API token](https://buildkite.com/user/api-access-tokens)。仓库包含 `.bk.yaml`，因此 `bk` 命令默认指向 `bun` 管道。

```sh theme={null}
bun run ci:status         # 当前分支最新构建的进度摘要
bun run ci:errors         # 渲染的测试失败输出，标记 [new] 与 [also on main]
bun run ci:logs           # 将每个失败作业的完整日志保存到 ./tmp/ci-<build>/
bun run ci:watch          # 监视直到构建完成
bun run ci:find           # 打印构建编号（与原始 `bk` 配合使用）
```

所有这些命令接受一个目标：`#1234`（PR 编号）、PR URL、分支名称或构建编号。未指定时使用当前 git 分支。

## AddressSanitizer

[AddressSanitizer](https://en.wikipedia.org/wiki/AddressSanitizer) 有助于发现内存问题，在 Linux 和 macOS 上 Bun 的调试构建中默认启用。它覆盖 Rust 代码、C++ 绑定和所有依赖项。它会使构建时间延长约 2 倍；如果这妨碍了你的生产力，可以使用 `bun run build:debug:noasan` 禁用它（或向 `scripts/build.ts` 传递 `--asan=off`），但通常我们建议在构建之间批量处理更改。

要构建带 AddressSanitizer 的发布构建，运行：

```bash theme={null}
bun run build:asan
```

CI 使用至少一个启用 AddressSanitizer 的目标运行测试套件。

## 本地构建 WebKit + JSC 调试模式

WebKit 默认不会被克隆（以节省时间和磁盘空间）。要本地克隆和构建 WebKit，运行：

```bash theme={null}
# 将 WebKit 克隆到 ./vendor/WebKit
git clone https://github.com/oven-sh/WebKit vendor/WebKit

# 检出 scripts/build/deps/webkit.ts 中 WEBKIT_VERSION 指定的版本
# （提交 SHA 或 autobuild-* 发布标签；两者皆可）
bun sync-webkit-source

# 使用本地 JSC 构建 Bun——这会自动配置和构建 JSC
bun run build:local
```

`bun run build:local` 处理一切：配置 JSC、构建 JSC 和构建 Bun。后续运行时，如果任何 WebKit 源代码发生变化，JSC 会增量重新构建。首次构建后，`ninja -Cbuild/debug-local` 也可用，并同时构建 Bun 和 JSC。

构建输出位于 `./build/debug-local`（而不是 `./build/debug`），因此你需要更新以下几个地方：

* `src/js/builtins.d.ts` 的第一行
* `.clangd` 配置中的 `CompilationDatabase` 行应为 `CompilationDatabase: build/debug-local`
* 在 `.vscode/launch.json` 中，许多配置使用 `./build/debug/`，请按需更改

WebKit 文件夹（包括构建产物）大小在 8GB 以上。

如果你使用 JSC 调试构建配合 VSCode，运行 `C/C++: Select a Configuration` 命令，以便 IntelliSense 找到调试头文件。

如果你对 Bun 的 [WebKit 分支](https://github.com/oven-sh/WebKit)进行了更改，还必须更改 `scripts/build/deps/webkit.ts` 中的 `WEBKIT_VERSION` 以指向你的提交哈希或发布标签。

## 故障排除

### 'span' 文件在 Ubuntu 上找不到

<Warning>
  ⚠️ 这些说明仅针对 Ubuntu。其他 Linux 发行版不太可能出现相同问题。
</Warning>

Clang 默认使用 GNU 编译器集合（GCC）提供的 C++ 标准库实现 `libstdc++`。Clang 也可以链接 `libc++`，但需要显式传递 `-stdlib` 标志。

Bun 依赖 C++20 特性，如 `std::span`，这些特性在 GCC 版本低于 11 时不可用。因此，运行 `bun run build` 可能会失败并显示以下错误：

```txt theme={null}
fatal error: 'span' file not found
#include <span>
         ^~~~~~
```

首次运行 `bun run build` 时也可能出现此问题，Clang 无法编译简单程序：

```txt theme={null}
The C++ compiler

  "/usr/bin/clang++-21"

is not able to compile a simple test program.
```

要修复此错误，将 GCC 更新到版本 11。它可能在你发行版的官方仓库中可用；否则，添加提供 GCC 11 软件包的第三方仓库：

```bash theme={null}
sudo apt update
sudo apt install gcc-11 g++-11
# 如果上述命令失败，显示 `Unable to locate package gcc-11`，我们需要
# 添加 APT 仓库
sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
# 现在再次运行 `apt install`
sudo apt install gcc-11 g++-11
```

然后将 GCC 11 设置为默认编译器：

```bash theme={null}
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-11 100
sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-11 100
```

### libarchive

如果在 macOS 上编译 `libarchive` 时看到错误，运行：

```bash theme={null}
brew install pkg-config
```

### macOS `library not found for -lSystem`

如果在编译时看到此错误，运行：

```bash theme={null}
xcode-select --install
```

### 找不到 `libatomic.a`

Bun 默认静态链接 `libatomic`，因为并非所有系统都有它。如果你在没有静态 libatomic 的发行版上构建，请启用动态链接：

```bash theme={null}
bun run build --static-libatomic=off
```

如果以这种方式编译，构建的 Bun 版本可能无法在其他系统上运行。

## 使用 bun-debug

* 禁用日志：`BUN_DEBUG_QUIET_LOGS=1 bun-debug ...`（禁用所有调试日志）
* 启用特定范围的日志：`BUN_DEBUG_EventLoop=1 bun-debug ...`（启用 `scoped_log!(EventLoop, ...)` 输出）
* Bun 会转译它运行的每个文件。要在调试构建中查看实际执行的源代码，请在 `/tmp/bun-debug-src/...path/to/file` 中查找。例如，`/home/bun/index.ts` 的转译版本位于 `/tmp/bun-debug-src/home/bun/index.ts`