贡献

​

使用 Nix（可选方案）

nix develop
# 或显式使用纯净 shell
# nix develop .#pure
export CMAKE_SYSTEM_PROCESSOR=$(uname -m)
bun bd

​

安装依赖（手动）

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

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

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

npm install -g bun

brew tap oven-sh/bun
brew install bun

​

可选：安装 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

​

安装 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

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"

​

构建 Bun

bun run build

build/debug/bun-debug --version
x.y.z_debug

​

VSCode

bun-debug

​

运行调试构建

bun bd <args>
bun bd test foo.test.ts
bun bd ./foo.ts

• 批量进行更改
• 使用 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 的更改几乎可以瞬间重建。单个 Rust crate 的更改和 C++ 更改都是增量的；只有最终链接步骤是不可避免的。

​

代码生成脚本

• ./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 对象的样板代码，然后将其连接到 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 模块

​

发布版本构建

bun run build:release

​

从 Pull Request 下载发布版本构建

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-1234566 --version

​

从终端查看 CI 失败情况

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` 组合使用）

​

AddressSanitizer

bun run build:asan

​

本地构建 WebKit + JSC 调试模式

# 将 WebKit 克隆到 ./vendor/WebKit
git clone https://github.com/oven-sh/WebKit vendor/WebKit

# 检出 scripts/build/deps/webkit.ts 中 WEBKIT_VERSION 指定的提交哈希
git -C vendor/WebKit checkout <commit_hash>

# 构建 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

• 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/，请按需修改

​

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

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

The C++ compiler

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

is not able to compile a simple test program.

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

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

brew install pkg-config

​

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

xcode-select --install

​

找不到 libatomic.a

bun run build -DUSE_STATIC_LIBATOMIC=OFF

​

使用 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