贡献 - 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 编写，需要特定的 nightly 工具链（已固定在 rust-toolchain.toml 中）。请使用 rustup 安装 Rust，而不是使用发行版提供的 rust/cargo 软件包——构建脚本会使用 rustup 自动安装并更新已固定的 nightly 工具链：

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

运行调试构建

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 的接口；代码生成器读取这些接口，生成用于在 C++ 中实现 JavaScript 对象并将其与 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 pipeline。

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 的调试版本，产物在 ./vendor/WebKit/WebKitBuild/Debug
# 可选：用 `bun run jsc:build` 构建发布版
bun run jsc:build:debug && rm vendor/WebKit/WebKitBuild/Debug/JavaScriptCore/DerivedSources/inspector/InspectorProtocolObjects.h

# 初次运行 `make jsc-debug` 后，可以用下面命令重建 JSC：
cmake --build vendor/WebKit/WebKitBuild/Debug --target jsc && rm vendor/WebKit/WebKitBuild/Debug/JavaScriptCore/DerivedSources/inspector/InspectorProtocolObjects.h

# 用本地 JSC 构建 Bun
bun run build:local

bun run build:local 会处理所有事务：配置 JSC、构建 JSC，以及构建 Bun。后续运行时，如果 WebKit 源代码发生变化，JSC 会进行增量重建。首次构建后，ninja -Cbuild/debug-local 也可以使用，并且会同时构建 Bun 和 JSC。

src/js/builtins.d.ts 第一行
.clangd 配置中的 CompilationDatabase 路径改为 build/debug-local
build.zig 中的 codegen_path 改为 build/debug-local/codegen
.vscode/launch.json 中相应配置的路径改为 ./build/debug-local/
src/js/builtins.d.ts 第一行
.clangd 配置中的 CompilationDatabase 行应为 CompilationDatabase: build/debug-local
.vscode/launch.json 中，许多配置使用了 ./build/debug/，请按需修改

WebKit 文件夹（包括构建产物）大小超过 8GB。如果你在 VSCode 中使用 JSC 调试版本，请运行 C/C++: Select a Configuration 命令，以便 IntelliSense 找到调试头文件。如果你修改了 Bun 的 WebKit fork，还必须修改 scripts/build/deps/webkit.ts 中的 WEBKIT_VERSION，使其指向你的提交哈希或发布标签。

Ubuntu 上出现 ‘span’ 文件未找到

⚠️ 以下说明针对 Ubuntu 特有的问题，其他 Linux 发行版一般不会遇到此类问题。

⚠️ 这些说明仅适用于 Ubuntu。在其他 Linux 发行版上通常不会遇到相同的问题。

Clang 默认使用 libstdc++，这是由 GNU Compiler Collection（GCC）提供的 C++ 标准库实现。Clang 也可以改为链接 libc++，但这需要显式传递 -stdlib 标志。 Bun 依赖 std::span 等 C++20 特性，而这些特性在低于 11 的 GCC 版本中不可用。因此，运行 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
# 如果报错找不到包，需添加 APT 仓库
sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
# 再试安装
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 调试模式

Ubuntu 上出现 ‘span’ 文件未找到

libarchive

macOS 编译时出现 `library not found for -lSystem`

找不到 `libatomic.a`

使用 bun-debug

​使用 Nix（可选方案）

​安装依赖（手动）

​可选：安装 ccache

​安装 LLVM

​构建 Bun

​VSCode

​运行调试构建

​代码生成脚本

​修改 ESM 模块

​发布版本构建

​从 Pull Request 下载发布版本构建

​从终端查看 CI 失败情况

​AddressSanitizer

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

​Ubuntu 上出现 ‘span’ 文件未找到

​libarchive

​macOS 编译时出现 library not found for -lSystem

​找不到 libatomic.a

​使用 bun-debug

使用 Nix（可选方案）

安装依赖（手动）

可选：安装 `ccache`

安装 LLVM

构建 Bun

VSCode

运行调试构建

代码生成脚本

修改 ESM 模块

发布版本构建

从 Pull Request 下载发布版本构建

从终端查看 CI 失败情况

AddressSanitizer

本地构建 WebKit + JSC 调试模式

Ubuntu 上出现 ‘span’ 文件未找到

libarchive

macOS 编译时出现 `library not found for -lSystem`

找不到 `libatomic.a`

使用 bun-debug