拆 Bun 源码:一个 JS 运行时的 Rust 工程力

项目卡片

• 项目：Bun^[1]
• 状态：v1.3.x / 92k+ Star / Rust + C++ + TS 三语混编
• 一句话判断：JS 运行时领域工程完成度最高的项目之一，从 Zig 到 Rust 的全面迁移本身就是一份大规模多语言项目的工程样本

92k Star、Rust 重写、集运行时/打包/测试/包管理于一身——Bun 的功能介绍已经够多了。我更在意的是：它到底怎么把这么多东西塞进一个二进制的？

翻完源码，我的判断是：Bun 的工程完成度比它的"快"更值得关注。本文从源码切入，拆四条链路——构建系统、事件循环、打包器、代码生成。不讲功能介绍，只讲实现。

Bun 的代码分四层，每层有明确的职责边界：

Rust 层（~200 个 crate，1290 个 .rs 文件）：所有业务逻辑——CLI 命令分发、打包器、包管理器、事件循环、FFI、Shell。这是项目的"大脑"。

C++ 层（188 个 .cpp 文件）：JavaScriptCore 绑定。自定义 ZigGlobalObject（继承 JSC::JSGlobalObject），注册 100+ 个原生 JS 类，桥接 Rust 和 JSC。这一层是"神经突触"。

JSC 层（WebKit/JavaScriptCore）：JS 执行引擎，预编译静态链接。

TypeScript 层（内置 JS 模块 + 构建系统）：src/js/ 下的内置模块和 scripts/build.ts 构建系统。

一个细节：src/ 下有 554 个 .zig 文件，但它们不参与编译、不随产品发布。这些是原始 Zig 实现的遗留代码，仅作为 Rust 移植期的行为参考。Bun 正在从 Zig 全面迁移到 Rust，Zig 文件就是活文档。

Bun 的构建系统不是 CMake，也不是 Makefile。它是一个用 TypeScript 编写的 Ninja 生成器。

入口 scripts/build.ts，三个阶段：

Phase 1 — 配置：configure.ts 发现工具链（clang、cargo、cmake），生成 build/<profile>/build.ninja。

Phase 2 — 依赖构建：bun.ts::emitBun() 遍历 22 个 vendored 依赖，按四种模式构建：

• direct：源码直接进入 ninja 图（zlib、boringssl、mimalloc 等 17 个）
• nested-cmake：调用依赖自己的 cmake（lsquic）
• cargo：cargo build（lolhtml）
• prebuilt：下载预编译产物（WebKit）

依赖的链接顺序经过编排——WebKit 放在最后链接，因为 JSC 提供所有上层可能引用的符号。

Phase 3 — 执行 ninja：Rust 部分通过 cargo build -p bun_bin 生成 libbun_rust.a，配置了 lto = "fat" + codegen-units = 1，整个 Rust workspace 被压缩成单一 LLVM 模块。

这个思路值得借鉴：当你的项目依赖了十几个 C/C++ 库、需要交叉编译、需要 debug/release 多套配置时，与其维护几千行 CMake，不如写一个 TypeScript 脚本程序化地生成构建图。高级语言生成低级构建文件，调试和跨平台都好处理。

这是 Bun 和 Node.js 最根本的架构差异。

Node.js 所有平台统一通过 libuv 抽象 I/O 多路复用。Bun 在 POSIX 上绕过 libuv，直接调用 epoll/kqueue：

// packages/bun-usockets/src/eventing/epoll_kqueue.c
loop->fd = epoll_create1(EPOLL_CLOEXEC);

Linux 上用 epoll_pwait2（syscall 441）获得纳秒级超时精度。只在 Windows 上因 IOCP 复杂性才 fallback 到 libuv。

我一般先看事件循环的实现来判断一个运行时的工程水平。Bun 这一块做得比较"底层"——libuv 那层间接调用在正常场景开销不大，但当你做 HTTP 服务器需要亚毫秒级响应时，省掉就是实打实的。

tick 流程

tick() → tickConcurrent() → 处理任务队列 → drainMicrotasks()
       → tickConcurrent() → 还有任务？继续
       → 没有 → autoTick() → loop.tickWithTimeout()（epoll_wait）
       → setImmediate → POSIX timer

与 JSC microtask queue 的集成用了引用计数方案：每次进入 JS 调用前 enter()，调用后 exit()。只有计数回到 0（最外层退出）才排空 microtask，避免嵌套调用在中途清空 Promise 队列。

任务分发：tagged pointer + 无锁队列

Bun 用 tagged pointer union 做任务分发。每个 Task 16 字节：u8 tag（69 种任务类型）+ 类型擦除的 *mut ()。

后台线程通过无锁 MPSC 队列（UnboundedQueue<ConcurrentTask>）投递到 JS 线程，再用 epoll 的 eventfd 唤醒主循环。

更底层：epoll 事件中用49-bit 指针 + 15-bit tag 直接区分 uSockets socket 和 Bun FilePoll，不需要查找表。

#define CLEAR_POINTER_TAG(p) ((void *) ((uintptr_t) (p) & 0x0000FFFFFFFFFFFF))

Promise/Future 桥接

Rust 线程池任务和 JS Promise 之间的桥接靠 ConcurrentPromiseTask：

pub trait ConcurrentPromiseTaskContext: Sized {
    fn run(&mut self);            // 线程池中执行
    fn then(&mut self, promise: &mut JSPromise); // JS 线程中 resolve
}

JS 线程创建 pending Promise → schedule() 提交到线程池 → run() 执行阻塞 I/O → enqueue_task_concurrent() 投递回 JS 线程 → then() resolve。

KeepAlive 机制保证 pending 的异步操作不会让事件循环提前退出：创建时 ref()，resolve 时 unref()，支持线程安全原子操作。

Bun 的打包器不依赖 SWC。它有自己的一套 JS/TS 解析器（src/js_parser/）和代码生成器（src/js_printer/）。

打包链路

enqueue_entry_points() → 并行 Parse（线程池）
  → on_parse_task_complete()（桶文件优化 → 递归解析依赖）
  → find_reachable_files()（DFS 标记可达文件）
  → link()（扫描导入/导出 → tree shaking + code splitting → 计算 chunks）
  → generate_chunks_in_parallel()（并行重命名 → 并行代码生成 → 写盘）

SoA 存储

模块图用 MultiArrayList——Structure of Arrays 布局。所有模块的 Part、ImportRecord、Symbol 按列存储。

tree shaking 扫描时，遍历某一列的所有元素可以连续访问内存，CPU 缓存命中率高于传统的 struct 数组。esbuild 用的还是 Go 的 struct 数组。

Tree shaking

Part 级 liveness marking，和 esbuild 思路类似。每个文件拆成多个 Part，标记 can_be_removed_if_unused。从入口点 DFS 标记可达 Part，未标记的在代码生成时跳过。

有个独有优化——桶文件优化（barrel_imports.rs）：当文件满足 sideEffects: false、所有导出都是 re-export、不是其他桶文件的 export star 目标时，识别为桶文件。其中未被使用的导入在解析前就标记为 IS_UNUSED，直接跳过。

并行化：双线程池

Worker Pool（CPU 核心数等量）处理解析和代码生成。macOS/Windows 上额外启用 IO Pool（最多 4 线程）。

macOS 需要 IO Pool 的原因很具体：IORWLock 在 4+ 线程并发读文件时存在竞争，独立 IO Pool 能获得 60% 性能提升。Linux 上没这个问题，禁用 IO Pool。

每个 Worker 有自己的 Transpiler 深拷贝，通过 #[thread_local] 缓存 (generation, *mut Worker) 对避免锁竞争。

这是全文最值得细看的架构设计。

.classes.ts 文件用声明式 DSL 定义 JS 类结构，generate-classes.ts 同时生成三份代码：

• C++ 绑定层（ZigGeneratedClasses.cpp）：声明 extern 符号名，注册到 JSC
• Rust 业务层（generated_classes.rs）：实现 extern 符号，调用 Rust struct 的 inherent method
• Zig 遗留层（ZigGeneratedClasses.zig）：逐步弃用

C++ 层完全不知道实现是 Zig 还是 Rust。从 Zig 迁移到 Rust 只需在 .classes.ts 中设置 lang: "rust"。如果对应的 Rust struct 缺少方法，cargo check 直接编译报错——不是运行时 panic，是编译期就拦截。

Rust emitter 里有个自动路径解析器，遍历 src/runtime/lib.rs 的 pub mod 树，建立 type name → crate::... path 的映射。引用不存在的类型，编译就不过。

R-2 安全：防重入 miscompile

代码生成有个 sharedThis 选项（现已为默认值 true）。开启后生成的 Rust thunk 用 &T 而非 &mut T。

这个选项的引入是因为一个真实 bug：NodeHTTPResponse::cork 中 &mut self 带 LLVM noalias 属性，方法重入 JS 时另一个 host-fn 在同一实例上执行，编译器缓存了 *self 字段导致 miscompile。改用 &T 消除了 noalias 假设，从根本上解决。

内置模块的调试热重载

内置模块（node:fs 等）在编译时被嵌入为 C 字符串。但 debug 构建下有 BUN_DYNAMIC_JS_LOAD_PATH 宏，直接从磁盘读取最新源码——改 src/js/ 下的文件不需要重新编译 C++/Rust。这个设计对贡献者非常友好。

FFI：TinyCC JIT 编译

Bun.ffi 不只是 dlopen 封装。它集成了 TinyCC 轻量级 C 编译器，可以在内存中 JIT 编译 C 代码：

let state_ptr = TCC::State::init::<CompileC, true>(TCC::Config {
    output_type: TCC::OutputFormat::Memory,  // 内存输出
    options: Some(NonNull::from(compile_options)),  // "-std=c11 -g -O2"
    ...
})?;
state.relocate()?;  // JIT 重定位

macOS aarch64 上 JIT 写操作需要临时关闭 pthread_jit_write_protect_np，Bun 用 scopeguard 确保 W^X 保护一定恢复。函数名也诚实地叫 dangerously_run_without_jit_protections。

Shell：NodeId Arena 解决借用检查

Bun 内置的 Shell 解释器用状态机节点树 + continuation-passing style 实现非阻塞执行。从 Zig 移植到 Rust 时，Zig 的裸指针树（*Parent）碰上了借用检查——parent 和 child 不能同时 &mut。

解决方案：Vec<Node> + NodeId（u32 索引）替代树形指针。所有状态节点存在一个 flat Vec 里，用 NodeId 互相引用，O(1) 查找，同时规避了所有权问题。

cat、cd、echo、ls、mkdir、rm 等常见命令直接用 Rust 实现为内置命令，不 fork。

OOM：受控崩溃

FFI 边界上，OOM 不能让 Result::Err 传播到 C/C++ 侧。Bun 统一用 handle_oom 做受控崩溃——直接 crash，不让错误穿越语言边界。

如果让我挑几个最值得带走的设计：

代码生成的多端一致性。.classes.ts 一次定义 → C++ 绑定 + Rust 实现 + 编译期验证。任何需要维护多语言 FFI 绑定的项目都可以复用这个思路——用声明式 DSL 定义接口，工具生成各语言的桥接代码，缺失实现编译期拦截。

事件循环与 GC 的协同。进入 epoll_wait 之前调用 Bun__JSC_onBeforeWait 通知 JSC 可以安全执行 GC。GC 在 I/O 等待期间跑完，不占 JS 执行时间。这个模式适用于所有"计算 + I/O"混合的场景。

垂直整合带来的全局优化。解析器、打包器、运行时全自研，打包产物可以直接被运行时执行，支持字节码缓存（.jsc）。对比 Node.js 生态中 V8、esbuild、webpack 各自为政，垂直整合省掉了大量格式转换和序列化开销。

二次开发入口：插件系统（onResolve/onLoad）扩展打包器行为；FFI 系统让调用 C 库只需几行代码；Shell 解释器可以独立嵌入其他 Rust 项目；内置模块的调试热重载让贡献代码的门槛很低——改一个 JS 文件就能测。

这里会继续拆真实可用的开发者工具：少讲概念，多看入口、成本和坑点。你只需要判断一件事——它值不值得放进自己的工作流。

引用链接