Zig 增量编译内幕揭秘2026 年 7 月 28 日作为 Zig 核心团队一员参与过的最具影响力项目之一便是在 Zig 编译器实现 _增量编译_ 功能。该功能可让编译器检测项目上次构建后函数和声明变化仅重编更改代码将生成字节修补到输出二进制文件使重建极快。Zig 项目为实现此功能努力已久。过去几个发布周期该功能从概念验证发展到可用于实际项目且 Zig 核心团队多数成员日常使用。如今借助该功能可在毫秒级修改真实复杂应用程序。这里有个无音频视频展示使用 Zig 快速修改和测试 Fizzy像素编辑应用程序过程初始构建约 5 秒后续修改重建仅需 50 - 70 毫秒。演示中需将 Fizzy 升级到 Zig 的 master 分支因 Zig 0.16.0 虽支持增量编译但缺重要链接器功能这些功能后续才实现。若想用 Zig 标记版本可能要等 0.17.0 版本发布后尝试此功能。Fizzy 随机修改的快速增量重建若被说服想知道如何使用该功能可直接看本文最后部分。若怀疑其是否适用于多数项目或想了解工作原理下面深入探讨细节。处理源文件Zig 编译器流程分几部分先以整个源文件为粒度在循环中执行从磁盘读取源文件将文件解析为抽象语法树AST用 “AstGen” 过程将 AST 转换为 “ZIR” 格式。ZIR 是无类型的静态单赋值SSA形式的中间表示。AstGen 运行时会识别源文件中 Zig 导入对导入文件重复此过程最终找到编译中每个 Zig 源文件并转换为 ZIR。此流程有特性对每个文件处理是文件内容纯函数无共享或外部状态Parse 和 AstGen 快在笔记本上对 Zig 编译器 src/ 目录运行这两步约 920 毫秒因 Zig 用面向数据设计模式ZIR 可通过 writev/readv 系统调用读写磁盘无需 “序列化” 步骤。这些特性带来好处整个过程高度并行发现新源文件可将任务加入线程池队列多线程运行唯一共享状态用互斥锁保护实现增量编译简单将生成 ZIR 缓存到磁盘文件更改时才重建。这两个优化在 Zig 中默认启用多年多数情况能让此流程瞬间完成通过标准错误输出进度信息可看到速度显示 “AST 降级” 时此流程运行很多 Zig 用户可能首次运行编译器时才注意到。不过这只是简单部分后续更棘手。语义分析流程的语义分析部分很重要包括类型检查和 comptime 求值。主要任务是 “解释” 之前生成的 ZIR发出编译错误为运行时函数构建另一种中间表示。“容器级声明” 在 Zig 中类似其他语言 “顶级声明”指 “函数、全局常量或全局变量”。语义分析是编译器最难增量处理部分因语言设计在此阶段重要。虽多数现代语言可支持增量编译但某些设计决策会增加实现难度Zig 多年来调整设计以支持快速增量编译。关键是将编译过程拆分成可独立分析部分用依赖图建模部分间依赖关系。Zig 编译器有四种分析单元struct 或 union 类型布局容器级声明类型容器级 const 声明值运行时函数主体。分析单元时会确定其依赖的其他单元集合如分析函数 foo 主体时会确定其依赖 global_0 和 global_1 类型及 global_1 值若这些发生变化需重新分析该函数。运行时函数主体分析单元在依赖图中只有 “出边”对 const 声明值的依赖源于 Zig 在 comptime 使用这些值的能力对类型布局的依赖源于拥有该类型的值或需了解布局信息。为解决源代码依赖问题不仅跟踪分析单元间依赖还跟踪其与源代码片段依赖ZIR 包含特定源代码区域哈希值源代码变化哈希值改变编译器前端易检测。通过示例代码和依赖图展示若修改源代码编译器会生成新 ZIR比较声明哈希值找到依赖该哈希值的单元重新分析相关单元最终引出代码生成阶段。代码生成代码生成“codegen”是编译器流程阶段将语义分析生成的 AIR 转换为类似机器指令的 MIR 形式MIR 指令和机器指令几乎一一对应每个目标架构有单独实现。代码生成是高度并行任务不进行内联等函数间优化的构建中不同函数代码生成无共享状态可在多线程处理待处理函数队列但要控制队列大小。增量编译时此阶段简单因 AIR 和 MIR 以单个函数为粒度编译器无需缓存代码生成完成后 AIR 丢弃MIR 传递给链接器后丢弃。链接增量链接是难题可能是其他主要工具链未支持增量编译的重要原因。通用增量链接器不常见wild 最初设计为增量链接器但近年重点转向冷链接性能且无明确增量链接时间表。wild 创建者讨论过增量链接困难如比较输入对象确定变化。控制整个编译流程时有更简单方案将链接器与编译器紧密集成。无增量编译时链接器单线程工作接收 MIR 后转换为机器代码生成重定位信息在输出段预留空间保存相关信息。增量链接更复杂写入机器代码、分配地址和应用重定位信息需在知道二进制文件完整内容前完成并能后续更新。为解决问题Jacob Young 在 Zig 编译器引入 link.MappedFile 抽象它将输出文件内存映射跟踪文件中 “节点” 树API 用户可添加或扩展节点空间不足时处理移动其他节点调整节点时设置 “脏” 标志链接器检测并应用必要修复。目前 MappedFile 节点分配逻辑简单可在未来改进。实现增量链接时完成机器代码生成后在映射文件创建或调整节点设置 “脏” 标志链接器空闲或编译结束时检查并清理虽有时修复工作耗时但多数情况无需移动内容通过指数增长因子分摊成本实际中更新慢情况罕见。刷新完成整个流程的增量处理后需进行收尾工作。因 Zig “懒分析” 功能与增量编译交互需图遍历确定哪些函数、声明等被引用忽略未引用内容的编译错误不进行符号导出等。确定引用内容后告诉链接器导出全局符号报告编译错误执行杂项任务调用链接器 flush 函数完成剩余工作最后关闭文件编译完成。跟踪更新Tracy 是实时性能分析工具可集成到 Zig 编译器通过构建标志启用。对 Fizzy 更改时的 Tracy 输出显示增量更新耗时 37 毫秒前 6 毫秒线程池进行按文件处理工作检查每个源文件computeAliveFiles 函数遍历文件导入图分配文件到模块并检查是否参与编译updateZirRefs 函数关联旧 ZIR 和新 ZIR 并更新内部引用。完成按文件处理后进入流程核心部分语义分析约 1.2 毫秒代码生成约 240 微秒链接工作约 170 微秒此部分共约 1.6 毫秒。刷新阶段前端请求部分链接工作约 50 微秒。剩余 31 毫秒花在 resolveReferencesInner 函数上用于确定 Zig 声明引用情况虽此函数本身不低效但图大影响速度可通过避免重新计算未改变的引用图和只重新计算变化部分来提高效率。使用增量编译假设你有 Zig 项目和构建脚本且能在最近 master 分支版本的 Zig 上编译Zig 0.17.0 发布后也可。目前该功能在以 x86_64-linux 为目标时才能发挥作用因其他代码生成和链接器后端不成熟Zig 核心团队先专注此平台后续会为其他目标添加支持。目前使用该功能非零成本未来会将编译器状态缓存到磁盘自动加载但现在只需运行 zig build --watch -fincremental 命令--watch 参数监视源文件更改触发重建-fincremental 参数使用增量编译。运行此命令时即使有热缓存项目中可执行文件、库或对象会重新构建若不便可修改 build.zig 文件用 -Dincremental 代替 -fincremental 对特定步骤进行初始重建。初始构建完成后编辑源文件保存即可看到重建结果无编译错误时在 zig-out/ 目录找到更新后的可执行文件。若将 --watch 与运行程序构建步骤结合短时间运行程序适用但长时间运行程序要注意构建系统需在程序关闭后触发增量重建可正常构建后手动运行程序后续会对构建系统改进支持其他工作流程。和 Zig 项目其他部分一样增量编译目前不稳定存在 bug使用时遇到问题可在 Zig 仓库提交 issue。感谢帮助测试和尝试使用该功能的用户以及向 Zig 软件基金会捐款的人。