為 Bun 做貢獻

配置 Bun 的開發環境可能需要 10-30 分鐘，具體取決於你的網絡連接和計算機速度。你將需要約 10GB 的可用磁盤空間用於倉庫和構建產物。

如果你使用 Windows，請參考本指南

使用 Nix（替代方案）

提供了一個 Nix flake 作為手動安裝依賴的替代方案：

bash

nix develop
# 或者顯式使用純 shell
# nix develop .#pure
export CMAKE_SYSTEM_PROCESSOR=$(uname -m)
bun bd

這在隔離的、可重現的環境中提供所有依賴，無需 sudo 權限。

安裝依賴（手動）

使用系統的包管理器安裝 Bun 的依賴：

bash

$ brew install automake cmake coreutils gnu-sed go icu4c libiconv libtool ninja pkg-config rust ruby sccache

bash

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

bash

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

bash

$ sudo dnf install cargo clang19 llvm19 lld19 cmake git golang libtool ninja-build pkg-config rustc ruby libatomic-static libstdc++-static sed unzip which libicu-devel 'perl(Math::BigInt)'

bash

$ sudo zypper install go cmake ninja automake git icu rustup && rustup toolchain install stable

注意：Zig 編譯器會自動安裝和更新由構建腳本完成。無需手動安裝。

開始之前，你需要已經安裝好 Bun 的發布版本，因為我們使用自己的打包器來轉譯和壓縮代碼，以及用於代碼生成腳本。

bash

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

bash

$ npm install -g bun

bash

$ brew tap oven-sh/bun
$ brew install bun

可選：安裝 `sccache`

sccache 用於緩存編譯產物，顯著加快構建速度。它必須安裝 S3 支持：

bash

# 對於 macOS
$ brew install sccache

# 對於 Linux。注意你的包管理器中的版本可能沒有 S3 支持。
$ cargo install sccache --features=s3

這將安裝帶有 S3 支持的 sccache。我們的構建腳本會自動檢測並使用帶有我們共享 S3 緩存的 sccache。注意：並非所有版本的 sccache 都編譯時帶有 S3 支持，因此我們建議通過 cargo 安裝它。

為 `sccache` 注冊 AWS 憑證（僅限核心開發人員）

核心開發人員擁有共享 S3 緩存的寫入權限。要啟用寫入權限，你必須使用 AWS 憑證登錄。最簡單的方法是使用 aws CLI 並調用 aws configure 提供你的 AWS 安全信息。

cmake 腳本應該會自動從環境或 ~/.aws/credentials 文件中檢測你的 AWS 憑證。

登錄到 `aws` CLI

1. 按照 [官方指南](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) 安裝 AWS CLI。
2. 登錄到你的 AWS 賬戶控制台。團隊成員應該向你提供你的憑證。
3. 點擊右上角你的名字 > Security credentials。
4. 滾動到 "Access keys" 並創建新的訪問密鑰。
5. 在終端中運行 `aws configure` 並在提示時提供訪問密鑰 ID 和秘密訪問密鑰。

常見問題

- 要確認緩存正在使用，你可以在構建後立即使用 `sccache --show-stats` 命令。這將顯示非常有用的統計信息，包括緩存命中/未命中。
- 如果你配置了多個 AWS 配置文件，請確保在 `AWS_PROFILE` 環境變量中設置了正確的配置文件。
- `sccache` 遵循服務器 - 客戶端模型。如果你遇到 `sccache` 拒絕使用 S3 的奇怪問題，即使你已經配置了 AWS 憑證，嘗試使用 `sccache --stop-server` 終止任何正在運行的 `sccache` 服務器，然後重新運行構建。

安裝 LLVM

Bun 需要 LLVM 19（clang 是 LLVM 的一部分）。這個版本要求是為了匹配 WebKit（預編譯），因為版本不匹配會導致運行時內存分配失敗。在大多數情況下，你可以通過系統包管理器安裝 LLVM：

bash

$ brew install llvm@19

bash

$ # LLVM 有一個自動安裝腳本，兼容所有版本的 Ubuntu
$ wget https://apt.llvm.org/llvm.sh -O - | sudo bash -s -- 19 all

bash

$ sudo pacman -S llvm clang lld

bash

$ sudo dnf install llvm clang lld-devel

bash

$ sudo zypper install clang19 lld19 llvm19

如果以上解決方案都不適用，你將不得不手動安裝它。

確保 Clang/LLVM 19 在你的路徑中：

bash

$ which clang-19

如果沒有，運行此命令手動添加它：

bash

# 如果你使用 fish，使用 fish_add_path
# 如果你使用 zsh，使用 path+="$(brew --prefix llvm@19)/bin"
$ export PATH="$(brew --prefix llvm@19)/bin:$PATH"

bash

# 如果你使用 fish，使用 fish_add_path
$ export PATH="$PATH:/usr/lib/llvm19/bin"

構建 Bun

克隆倉庫後，運行以下命令進行構建。這可能需要一段時間，因為它將克隆子模塊並構建依賴項。

bash

bun run build

二進制文件將位於 ./build/debug/bun-debug。建議將這個添加到你的 $PATH。要驗證構建是否成功，讓我們打印開發版本 Bun 的版本號。

bash

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

bun-debug

運行調試構建

bd package.json 腳本編譯並運行 Bun 的調試版本，僅在構建過程失敗時打印輸出。

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

當有 Zig 更改時，Bun 編譯調試版本大約需要 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=<path-to-file>.log。調試日志在發布版本中會被積極地移除。
src/js/**.ts 更改幾乎可以瞬間重新構建。C++ 更改稍慢一些，但仍比 Zig 代碼快得多（Zig 是一個編譯單元，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 -- 生成 build/debug/codegen/ZigGeneratedClasses*，為 Zig 中實現的 JavaScriptCore 類生成 Zig 和 C++ 綁定。在 **/*.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 對 Safari 內置函數的處理方式，這樣我們可以從 WebKit 復制粘貼實現作為起點。

修改 ESM 模塊

某些模塊（如 node:fs、node:stream、bun:sqlite 和 ws）是用 JavaScript 實現的。這些位於 src/js/{node,bun,thirdparty} 文件中，並使用 Bun 預打包。

發布構建

要編譯 Bun 的發布版本，運行：

bash

bun run build:release

二進制文件將位於 ./build/release/bun 和 ./build/release/bun-profile。

從拉取請求下載發布構建

為了節省你在本地構建發布版本的時間，我們提供了一種運行拉取請求中發布版本的方法。這對於在合並之前在發布版本中手動測試更改很有用。

要從拉取請求運行發布版本，你可以使用 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-number} 添加到 $PATH 中。然後你可以使用 bun-${pr-number} 運行構建。

bun-1234566 --version

這是通過從鏈接的拉取請求上的 GitHub Actions 構件下載發布版本來工作的。你可能需要安裝 gh CLI 來進行 GitHub 身份驗證。

AddressSanitizer

AddressSanitizer 有助於發現內存問題，在 Linux 和 macOS 上的 Bun 調試版本中默認啟用。這包括 Zig 代碼和所有依賴項。它使 Zig 代碼的構建時間大約增加 2 倍，如果這影響了你的工作效率，你可以通過在 cmake/targets/BuildBun.cmake 文件中將 -Denable_asan=$<IF:$<BOOL:${ENABLE_ASAN}>,true,false> 設置為 -Denable_asan=false 來禁用它，但通常我們建議在構建之間批量處理你的更改。

要使用 Address Sanitizer 構建發布版本，運行：

bash

bun run build:release:asan

在 CI 中，我們使用至少一個使用 Address Sanitizer 構建的目標運行測試套件。

在本地構建 WebKit + JSC 調試模式

WebKit 默認不克隆（為了節省時間和磁盤空間）。要在本地克隆和構建 WebKit，運行：

bash

# 將 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 將在 ./build/debug-local 目錄（而不是 ./build/debug）中構建 Bun，你需要更改幾個地方以使用這個新目錄：

src/js/builtins.d.ts 的第一行
.clangd 配置中的 CompilationDatabase 行應該是 CompilationDatabase: build/debug-local
在 build.zig 中，codegen_path 選項應該是 build/debug-local/codegen（而不是 build/debug/codegen）
在 .vscode/launch.json 中，許多配置使用 ./build/debug/，根據需要更改它們

注意 WebKit 文件夾（包括構建產物）大小為 8GB+。

如果你使用 JSC 調試版本並使用 VScode，請確保運行 C/C++: Select a Configuration 命令來配置 intellisense 以找到調試頭文件。

注意，如果你要更改我們的 WebKit 分支，你還需要更改 SetupWebKit.cmake 以指向提交哈希。

故障排除

在 Ubuntu 上找不到 'span' 文件

Clang 編譯器默認使用 libstdc++ C++ 標准庫。libstdc++ 是 GNU 編譯器集合（GCC）提供的默認 C++ 標准庫實現。雖然 Clang 可以鏈接到 libc++ 庫，但這需要在運行 Clang 時顯式提供 -stdlib 標志。

Bun 依賴於 C++20 特性，如 std::span，這些特性在 GCC 11 以下版本中不可用。GCC 10 沒有實現所有 C++20 特性。因此，運行 make setup 可能會失敗並出現以下錯誤：

txt

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

這個問題可能在初次運行 bun setup 時表現為 Clang 無法編譯一個簡單的測試程序：

txt

The C++ compiler

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

is not able to compile a simple test program.

要修復此錯誤，我們需要將 GCC 版本更新為 11。為此，我們需要檢查發行版的官方倉庫中是否有最新版本，或使用提供 GCC 11 包的第三方倉庫。以下是一般步驟：

bash

$ 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

$ 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

$ brew install pkg-config

macOS `library not found for -lSystem`

如果你在編譯時看到此錯誤，運行：

bash

$ xcode-select --install

找不到 `libatomic.a`

Bun 默認靜態鏈接 libatomic，因為並非所有系統都有它。如果你在確實沒有靜態 libatomic 的發行版上構建，你可以運行以下命令啟用動態鏈接：

bash

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 中

使用 Nix（替代方案） ​

安裝依賴（手動） ​

可選：安裝 sccache ​

為 sccache 注冊 AWS 憑證（僅限核心開發人員） ​

安裝 LLVM ​

構建 Bun ​

VSCode ​

運行調試構建 ​

代碼生成腳本 ​

修改 ESM 模塊 ​

發布構建 ​

從拉取請求下載發布構建 ​

AddressSanitizer ​

在本地構建 WebKit + JSC 調試模式 ​

故障排除 ​

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

libarchive ​

macOS library not found for -lSystem ​

找不到 libatomic.a ​

使用 bun-debug ​

使用 Nix（替代方案）

安裝依賴（手動）

可選：安裝 `sccache`

為 `sccache` 注冊 AWS 憑證（僅限核心開發人員）

安裝 LLVM

構建 Bun

VSCode

運行調試構建

代碼生成腳本

修改 ESM 模塊

發布構建

從拉取請求下載發布構建

AddressSanitizer

在本地構建 WebKit + JSC 調試模式

故障排除

在 Ubuntu 上找不到 'span' 文件

libarchive

macOS `library not found for -lSystem`

找不到 `libatomic.a`

使用 bun-debug