夜雨聆风项目卡片
项目：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 符号名，注册到 JSCRust 业务层（ generated_classes.rs）：实现 extern 符号，调用 Rust struct 的 inherent methodZig 遗留层（ 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 文件就能测。
这里会继续拆真实可用的开发者工具：少讲概念，多看入口、成本和坑点。你只需要判断一件事——它值不值得放进自己的工作流。
引用链接
[1]Bun: https://github.com/oven-sh/bun
