贡献 - Bun

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

使用 Nix（替代方案）

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

nix develop
bun bd

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

安装依赖（手动）

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

brew install automake ccache cmake coreutils gnu-sed go icu4c libiconv libtool ninja pkg-config rustup-init ruby

sudo apt install curl wget lsb-release software-properties-common cmake git golang libtool ninja-build pkg-config ruby-full xz-utils

sudo pacman -S base-devel cmake git go libiconv libtool make ninja pkg-config python rustup sed unzip ruby

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)'

sudo zypper install go cmake ninja automake git icu rustup

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

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

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

curl -fsSL https://bun.com/install | bash

npm install -g bun

brew tap oven-sh/bun
brew install bun

可选：安装 `ccache`

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

# 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：

brew install llvm@21

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

sudo pacman -S llvm clang lld

sudo dnf install llvm clang lld-devel

sudo zypper install clang21 lld21 llvm21

如果以上都不行，请手动安装。确保 Clang/LLVM 21 在你的路径中：

which clang-21

如果没有，手动添加：

# 使用 fish 的话用 fish_add_path
# 使用 zsh 的话用 path+="$(brew --prefix llvm@21)/bin"
export PATH="$(brew --prefix llvm@21)/bin:$PATH"

# 使用 fish 的话用 fish_add_path
export PATH="$PATH:/usr/lib/llvm21/bin"

⚠️ 在 Ubuntu ≤ 20.04 上，你可能需要单独安装 C++ 标准库。请参阅故障排除部分。

构建 Bun

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

bun run build

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

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：

bun-debug

运行调试构建

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

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 的发布构建，运行：

bun run build:release

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

从 Pull Request 下载发布构建

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

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，你可以直接运行：

bun-1234566 --version

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

从终端查看 CI 失败信息

Bun 的 CI 在 BuildKite 上运行。安装 BuildKite CLI（brew install buildkite/buildkite/bk）并设置 BUILDKITE_API_TOKEN 为只读范围的 API token。仓库包含 .bk.yaml，因此 bk 命令默认指向 bun 管道。

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

bun run build:asan

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

本地构建 WebKit + JSC 调试模式

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

# 将 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 分支进行了更改，还必须更改 scripts/build/deps/webkit.ts 中的 WEBKIT_VERSION 以指向你的提交哈希或发布标签。

故障排除

’span’ 文件在 Ubuntu 上找不到

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

Clang 默认使用 GNU 编译器集合（GCC）提供的 C++ 标准库实现 libstdc++。Clang 也可以链接 libc++，但需要显式传递 -stdlib 标志。 Bun 依赖 C++20 特性，如 std::span，这些特性在 GCC 版本低于 11 时不可用。因此，运行 bun run build 可能会失败并显示以下错误：

fatal error: 'span' file not found
#include <span>
         ^~~~~~

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

The C++ compiler

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

is not able to compile a simple test program.

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

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 设置为默认编译器：

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 时看到错误，运行：

brew install pkg-config

macOS `library not found for -lSystem`

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

xcode-select --install

找不到 `libatomic.a`

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

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

开始入门

核心运行时

文件与模块系统

HTTP 服务器

网络通信

数据与存储

并发

进程与系统

互操作与工具

实用工具

标准与兼容性

贡献指南

贡献

使用 Nix（替代方案）

安装依赖（手动）

可选：安装 `ccache`

安装 LLVM

构建 Bun

VSCode

运行调试构建

代码生成脚本

修改 ESM 模块

发布构建

从 Pull Request 下载发布构建

从终端查看 CI 失败信息

AddressSanitizer

本地构建 WebKit + JSC 调试模式

故障排除

’span’ 文件在 Ubuntu 上找不到

libarchive

macOS `library not found for -lSystem`

找不到 `libatomic.a`

使用 bun-debug

​使用 Nix（替代方案）

​安装依赖（手动）

​可选：安装 ccache

​安装 LLVM

​构建 Bun

​VSCode

​运行调试构建

​代码生成脚本

​修改 ESM 模块

​发布构建

​从 Pull Request 下载发布构建

​从终端查看 CI 失败信息

​AddressSanitizer

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

​故障排除

​’span’ 文件在 Ubuntu 上找不到

​libarchive

​macOS library not found for -lSystem

​找不到 libatomic.a

​使用 bun-debug

使用 Nix（替代方案）

安装依赖（手动）

可选：安装 `ccache`

安装 LLVM

构建 Bun

VSCode

运行调试构建

代码生成脚本

修改 ESM 模块

发布构建

从 Pull Request 下载发布构建

从终端查看 CI 失败信息

AddressSanitizer

本地构建 WebKit + JSC 调试模式

故障排除

’span’ 文件在 Ubuntu 上找不到

libarchive

macOS `library not found for -lSystem`

找不到 `libatomic.a`

使用 bun-debug