Bun Zig→Rust 移植指南：语法映射策略与阶段化工程实践

Bun 团队于 2026 年 5 月初在 oven-sh/bun 仓库公开了一份超过六百行的内部移植文档（docs/PORTING.md），详细记录了将运行时核心从 Zig 重写为 Rust 的完整工程蓝图。这不是一次冲动的技术选型变更，而是一套经过精密拆解的阶段化迁移方案：从忠实的草案翻译开始，逐步过渡到编译通过、性能调优与生产级部署。以下从技术决策角度梳理这份指南的核心工程要点。

阶段化迁移策略：草案先行，编译在后

移植工作被明确划分为两个阶段。Phase A 的目标并非生成可直接编译的代码，而是产出一份与原始 Zig 文件并列的草案 Rust 文件，优先忠实地复现逻辑而非追求语言正确性。移植者被要求在文件中保留 // TODO(port): <reason> 标记任何无法自信翻译的部分，避免猜测导致错误语义。这种保守策略的核心逻辑在于：当代码库规模达到 Bun 这样的量级时，逐文件、逐语义的精确对应比快速推进更有价值。

Phase B 才开始处理真实的编译问题。Phase B 的工程师会逐一打开 Phase A 标记的 TODO(port) 注释，逐个解决 borrow checker 冲突与类型不匹配，同时 grep 出所有 // PERF(port): <zig idiom> 标记，在真实基准测试数据支撑下实施性能优化。指南明确要求 Phase A 的移植者不得为了立即通过编译而引入非等价的 Rust 惯用法 —— 即便代码能跑通，语言层面的语义偏移也会在后续 diff 对比中造成难以追溯的 bug。

禁用列表：为何不能用 tokio 与 async fn

指南的最硬性约束之一是 Phase A 期间禁止使用 tokio、rayon、hyper、async-trait、futures 以及标准库的 std::fs、std::net、std::process。Bun 拥有自己的事件循环与系统调用包装层，引入外部异步运行时将破坏与现有 I/O 模型的兼容性。此外，禁止使用 async fn，所有代码必须沿用 Zig 的回调加状态机模式。

这一约束的技术含义深远。Bun 的核心性能优势部分来自对 I/O 模型的精确控制：uWebSockets.js 集成、自定义系统调用包装与微秒级定时器都依赖于与事件循环的紧耦合。若在此阶段引入 tokio，整个调度模型将面临重构风险，而非简单的语言语法替换。Rust 的异步生态固然成熟，但 Bun 的调度语义不是 Send + Sync 标准模型，其 JSValue 类型被明确标记为 !Send + !Sync（通过 PhantomData<*const ()> 实现负特征约束），与 tokio 的线程安全假设根本不兼容。

类型映射：从 Zig 类型系统到 Rust 的精确对应

错误类型处理

Zig 的 anyerror!T 在 Rust 中的映射被严格规定为 Result<T, bun_core::Error>。这里有一个关键的工程决策：bun_core::Error 本身不是枚举，而是一个 #[repr(transparent)] 的 newtype wrapper，内部包装 NonZeroU16，通过链接时注册的名称表提供错误名称。bun_core::err!("ENOENT") 在编译期 intern 错误标签，产生一个 const Error。这种设计的动机是保持与 Zig 错误类型的二进制兼容性：Bun 的快照测试、JS 层的 error.code 以及崩溃处理器的 trace 编码都依赖精确的错误名称字符串。指南明确禁止使用 anyhow::Error 或 Box<dyn Error>—— 前者会堆分配，后者失去 Copy 特性且无法放入 #[repr(C)] 有效载荷。

指针与所有权模型

值得注意的是 bun.ptr.Shared 被刻意映射为 Rc<T> 而非 Arc<T>。指南给出的理由具体而务实：树范围内仅有 4 处使用，每个分配多消耗 8 字节的弱计数头部微不足道。引入自定义 IntrusiveRc 的收益低于维护成本。只有在指针跨 FFI 边界或通过 container_of! 恢复的场景下，才保留 intrusive 引用计数实现。

JSValue 的特殊约束

bun_jsc::JSValue 是一个 #[repr(transparent)] i64，被标记为 Copy 但 !Send + !Sync。最关键的约束写入了指南正文：永远不要将裸 JSValue 存储在堆分配 Rust 结构体的字段中。原因是保守式 GC 仅扫描栈与寄存器，堆上的 Box<JSValue> / Arc<JSValue> / Vec<JSValue> 不在扫描范围内，会产生悬挂指针。正确做法是使用 bun_jsc::Strong（从 VM handleSet 分配，GC root）或 bun_jsc::JsRef（自包装弱引用）。Strong 指向 Rust 结构体而 Rust 结构体通过 m_ctx 回指 Strong 的场景构成循环引用 —— 指南明确标注此类情况应使用 JsRef 而非 Strong。

分配器策略：arena 与全局分配器的分界线

指南对分配器使用划定了清晰的工程边界：AST / 解析器相关 crate 保留 arena 分配，其他所有地方删除 allocator 参数并使用全局分配器。

保留 arena 的 crate 清单包括 js_parser、css、bundler、bake、sourcemap、shell（解析器部分）、interchange 与 install/lockfile。这些模块构建大型节点树并在大规模释放时批量回收内存，arena 分配对吞吐量有决定性影响。Zig 的 std.heap.ArenaAllocator 在 Rust 中映射为 bumpalo::Bump（以 bun_alloc::Arena 重新导出）。allocator.create(T) 映射为 bump.alloc(init) 返回 &'bump mut T，arena.reset() 映射为 bump.reset()，所有生命周期 'bump 内的引用在 reset 后失效，borrow checker 强制执行这一约束。

AST crate 之外的所有代码则彻底删除 allocator 参数。std.mem.Allocator 参数 → 直接删除；allocator.dupe(u8, s) → Box::<[u8]>::from(s) 或 s.to_vec().into_boxed_slice()；allocator.create(T) → Box::new(init)。bun.handleOom(expr) 这一 Zig 的 panic-on-OOM 包装器被直接删除 —— 因为 Rust 的 Vec/Box 分配在 OOM 时直接 abort，与 Zig 包装后的行为一致，不再需要显式处理。

字符串模型：字节而非 UTF-8

指南用了一整个专门章节规定字符串处理，核心原则被浓缩为一句话：数据是字节，不是 str。std::string::String、&str、.to_string() 与 from_utf8() 在文件路径、源代码、HTTP 字节、模块标识符与环境变量等场景下被明确禁止使用。所有这些数据都是 &[u8] / Vec<u8> / Box<[u8]>。

这一决策的技术动机非常具体：Bun 需要处理 WTF-8 与任意字节序列，插入 UTF-8 验证既是性能税也是正确性 bug—— 它会拒绝有效的 Linux 路径中的非规范编码与孤立代理项。bun.String（WTFString-backed 共享缓冲区）被映射为 bun_str::String，其内部是一个 5 变体标签联合结构，通过 #[repr(C)] 保证与 C++ FFI 的二进制兼容性。ZigString 的 NUL 终止字节片映射为 &ZStr（bun_str::ZStr），携带长度信息但不将 NUL 计入长度。

平台条件编译与不可翻译构造

@import 语句底部导入块 → 简化为顶部的 use 语句并删除。pub const X = @import("../foo_jsc/..").y; 别名行 → 直接删除。Zig 中 to_js / from_js 是包级别导入的导出符号，而在 Rust 中它们是扩展 trait 方法，存在于 *_jsc crate 内，基本类型本身不再需要提及 jsc。

comptime 反射（@TypeOf、@typeInfo、@field）在 Rust 中没有直接等价物，指南给出了分层策略：@TypeOf(param) → 删除并直接命名泛型参数 <T>；@typeInfo 用于迭代结构体字段实现相等性 / 哈希 / 克隆 / 析构 → 直接 derive；用于实现领域协议 → 定义 trait 并逐类型 impl；@hasDecl 条件调用 → 替换为 trait bound 约束，编译期检查替代运行时分支。

实践参数：移植者可操作的检查清单

基于上述分析，以下是阶段化移植的关键工程参数与监控点，供参与此项目的开发者参考：

Phase A 交付标准：草案 .rs 文件在对应 .zig 文件旁，逻辑忠实度标记为 high/medium/low，包含完整 PORT STATUS trailer（含源文件行数、置信度、TODO 数量与 Phase B 注意事项）。不要求编译通过，但控制流、函数命名与字段顺序必须与 Zig 保持一致。

性能回填触发条件：搜索所有 // PERF(port) 注释并按热度分类。Zig 使用了 appendAssumeCapacity 的 push 操作、使用 arena 批量释放的模式、以及 comptime bool 分支守卫的运行时化 —— 这些标记了在 Phase B 需要用基准测试验证替换收益的场景。

GC 安全性检查：所有含 JSValue 字段的结构体必须在 Phase B 审查前完成 Strong/JsRef 迁移。使用 MarkedArgumentBuffer 而非 Vec<JSValue> 构建调用参数缓冲区，确保 GC root 覆盖。.classes.ts 托管类型的 hasPendingActivity 实现必须仅在 GC 线程上读取 Atomic 字段，声明周期 Ordering::Acquire，禁止分配或加锁。

字节正确性验证：所有外部数据源（文件系统、网络套接字、命令行参数）的字符串处理必须通过 &[u8] 路径，不得通过 UTF-8 验证。在 Phase B 添加 from_utf8 调用前必须有性能基准数据证明其必要性。

Bun 的这次迁移在工程上展示了语言移植的完整方法论：从详细的语法等价映射出发，通过禁用约束保持核心语义不变，以阶段化策略控制风险，最终在 Phase B 凭借基准测试数据推动性能优化。这不是语言层面的重新设计，而是一次精心策划的语义等价翻译。

参考来源

• Bun 官方 PORTING.md（Phase-A 移植指南），oven-sh/bun 仓库 commit 46d3bc2，2026 年 5 月
• Bun Zig→Rust 移植公告与 LLM 工作负载影响分析，dev.to，2026 年 5 月

systems