Skip to main content
配置 Bun 的开发环境可能需要 10 到 30 分钟，具体取决于您的网络连接和计算机速度。您需要大约 10GB 的可用磁盘空间用于存储仓库和构建产物。 如果您使用的是 Windows，请参考 此指南

​
使用 Nix（可选方案）

提供了一个 Nix flake 作为手动安装依赖的替代方案： 
nix develop
# 或显式使用纯净 shell
# nix develop .#pure
export CMAKE_SYSTEM_PROCESSOR=$(uname -m)
bun bd
这样可以在隔离且可复现的环境中提供所有依赖，无需 sudo。

​
安装依赖（手动）

使用系统的包管理器安装 Bun 的依赖： 
brew install automake ccache cmake coreutils gnu-sed go icu4c libiconv libtool ninja pkg-config rust ruby
注意：Zig 编译器由构建脚本自动安装和更新，无需手动安装。
开始之前，您需要已安装 Bun 的发布版本构建，因为我们使用自己的打包器来转译和压缩代码，以及用于代码生成脚本。 
curl -fsSL https://bun.com/install | bash

​
可选：安装 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 19（clang 是 LLVM 的一部分）。这个版本需求是为了匹配 WebKit（预编译版本），版本不匹配会导致运行时内存分配失败。大多数情况下，您可以通过系统包管理器安装 LLVM： 
brew install llvm@19
如果上述方案都不适用，您需要手动安装。 确保 Clang/LLVM 19 在您的路径中： 
which clang-19
如果没有，请手动添加： 
# 如果使用 fish shell，使用 fish_add_path
# 如果使用 zsh，使用 path+="$(brew --prefix llvm@19)/bin"
export PATH="$(brew --prefix llvm@19)/bin:$PATH"
⚠️ Ubuntu 发行版（版本 ≤ 20.04）可能需要单独安装 C++ 标准库。详情见故障排查章节。

​
构建 Bun

克隆仓库后，运行以下命令构建。这可能需要一些时间，因为会克隆子模块和构建依赖。 
bun run build
生成的二进制文件位于 ./build/debug/bun-debug。建议将其添加到您的 $PATH 中。验证构建是否成功，可以打印开发版 Bun 的版本号： 
build/debug/bun-debug --version
x.y.z_debug

​
VSCode

VSCode 是推荐的 Bun 开发 IDE，且已配置好。打开后，您可以运行 Extensions: Show Recommended Extensions 来安装 Zig 和 C++ 的推荐扩展。ZLS 会自动配置。 如果您使用其他编辑器，请确保将 ZLS 配置为使用自动安装的 Zig 编译器，路径为 ./vendor/zig/zig.exe。文件名为 zig.exe 是为了兼容 Windows，但在 macOS/Linux 上同样有效（只是扩展名比较特殊）。 推荐将 ./build/debug 添加到您的 $PATH，这样就可以在终端中直接运行： 
bun-debug

​
运行调试构建

bd package.json 脚本会编译并运行 Bun 的调试构建，仅在失败时打印构建过程输出。 
bun bd <args>
bun bd test foo.test.ts
bun bd ./foo.ts
Bun 通常在 Zig 代码改动时，调试构建大约需要 2.5 分钟。如果您的开发流程是“改一行，保存，重建”，等待时间会很长。建议：
  • 批量提交改动
  • 确保 zls 在增量模式下运行以检查 LSP 错误（如果您使用 VSCode 并且安装了 Zig，且运行过 bun run build 下载 Zig，应当自动生效）
  • 优先使用调试器（VSCode 中的 “CodeLLDB”）逐步调试代码
  • 使用调试日志。设置 BUN_DEBUG_<scope>=1 可启用对应 Output.scoped(.<scope>, .hidden) 的调试日志。可设置 BUN_DEBUG_QUIET_LOGS=1 关闭所有未显式开启的调试日志。要将调试日志输出到文件，设置 BUN_DEBUG=<日志文件路径>.log。发布版本会严格移除调试日志。
  • src/js/**/*.ts 文件的改动重建几乎是即时的。C++ 改动慢一些，但仍远快于 Zig（Zig 是单一编译单元，C++ 是多个编译单元）。

​
代码生成脚本

Bun 构建过程中使用了多个代码生成脚本。这些脚本在相关文件改动时自动运行。 主要有：
  • ./src/codegen/generate-jssink.ts — 生成 build/debug/codegen/JSSink.cpp 和 JSSink.h，实现多个用于与 ReadableStream 交互的类。这是 FileSink、ArrayBufferSink、"type": "direct" 流以及其他流相关功能的内部实现。
  • ./src/codegen/generate-classes.ts — 生成 build/debug/codegen/ZigGeneratedClasses*，生成 Zig 和 C++ 绑定，用于 Zig 实现的 JavaScriptCore 类。在 **/*.classes.ts 文件中定义各种类、方法、原型、getter/setter 等接口，代码生成器读取这些定义生成在 C++ 中实现JavaScript对象的模板代码并与 Zig 绑定。
  • ./src/codegen/cppbind.ts — 生成对带有 [[ZIG_EXPORT]] 特性的 C++ 函数的自动 Zig 绑定。
  • ./src/codegen/bundle-modules.ts — 打包内置模块如 node:fs、bun:ffi 成为可包含于最终二进制的文件。开发时可重新加载这些文件，无需重建 Zig（仍需运行 bun run build，但会从磁盘重新读取转译文件）。发布时嵌入二进制中。
  • ./src/codegen/bundle-functions.ts — 打包用 JavaScript/TypeScript 实现的全局函数，如 ReadableStream、WritableStream 等。这与内置模块类似，但生成的代码更接近 WebKit/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 运行发布构建的方法。方便在合并前手动测试更改。 运行 PR 的发布版，可以使用 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
它会从 PR 的 GitHub Actions 构建产物下载发布版本并添加到 $PATH，命名为 bun-${pr-number}。然后可以用命令 bun-${pr-number} 运行： 
bun-1234566 --version
需要安装 gh CLI 以进行 GitHub 认证。

​
AddressSanitizer

AddressSanitizer 用于检测内存问题，默认在 Linux 和 macOS 的 Bun 调试版启用，包括 Zig 代码和所有依赖。它使 Zig 代码构建时间大约增加两倍。如果这阻碍了您的效率，可以在 cmake/targets/BuildBun.cmake 文件中，将 -Denable_asan=$<IF:$<BOOL:${ENABLE_ASAN}>,true,false> 参数改为 -Denable_asan=false 以禁用，但推荐批量提交改动后再构建。 构建带 Address Sanitizer 的发布版，运行： 
bun run build:release:asan
在 CI 中，我们至少有一个目标使用 Address Sanitizer 来运行测试套件。

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

默认不克隆 WebKit（节约时间和空间）。要本地克隆并构建 WebKit： 
# 克隆 WebKit 到 ./vendor/WebKit
git clone https://github.com/oven-sh/WebKit vendor/WebKit

# 检出 cmake/tools/SetupWebKit.cmake 中 set(WEBKIT_VERSION <commit_hash>) 指定的提交
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
使用 bun run build:local 时，Bun 会构建到 ./build/debug-local 目录（非默认 ./build/debug），需要修改以下位置：
  • src/js/builtins.d.ts 第一行
  • .clangd 配置中的 CompilationDatabase 路径改为 build/debug-local
  • build.zig 中的 codegen_path 改为 build/debug-local/codegen
  • .vscode/launch.json 中相应配置的路径改为 ./build/debug-local/
注意 WebKit 文件夹（含构建产物）大小超过 8GB。 如果使用 JSC 调试构建且用 VSCode，务必运行 “C/C++: Select a Configuration” 以配置 IntelliSense 找到调试头文件。 修改我们 WebKit 仓库 的代码后，还需同步修改 SetupWebKit.cmake 中的提交哈希。

​
故障排查

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

⚠️ 以下说明针对 Ubuntu 特有的问题，其他 Linux 发行版一般不会遇到此类问题。
Clang 编译器默认使用 libstdc++ 作为 C++ 标准库，这也是 GCC 默认提供的。虽然 Clang 可以链接 libc++，但需要显式传递 -stdlib 参数。 Bun 依赖 C++20 特性，如 std::span，GCC 11 以下版本不支持。GCC 10 不支持所有 C++20 特性，因此运行 make setup 可能会报错： 
fatal error: 'span' file not found
#include <span>
         ^~~~~~
该错误可能出现在初次运行 bun setup 时，Clang 无法编译简单程序： 
The C++ compiler

  "/usr/bin/clang++-19"

is not able to compile a simple test program.
解决方法是将 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 -DUSE_STATIC_LIBATOMIC=OFF
但这样构建的 Bun 可能无法在其他系统运行。

​
使用 bun-debug

  • 禁用日志：BUN_DEBUG_QUIET_LOGS=1 bun-debug ...（关闭所有调试日志）
  • 为指定 Zig 作用域启用日志：BUN_DEBUG_EventLoop=1 bun-debug ...（启用 std.log.scoped(.EventLoop) 日志）
  • Bun 会对运行的每个文件进行转译，在调试构建中实际执行的代码位于 /tmp/bun-debug-src/...path/to/file，例如 /home/bun/index.ts 转译后在 /tmp/bun-debug-src/home/bun/index.ts