入行十年, 我最怕听到的一句话不是需求又改了, 而是我改了下公共头文件, 重新编一下。一个被几百个 .cpp 包含的头文件, 哪怕只加了一行注释, C 增量构建也会老老实实地把所有受影响目标重新编译一遍。进度条卡在 90%、到最后又崩掉的滋味, 相信每个 C 工程师都懂。C构建缓存加速, 正是针对这个痛点来的: 不重写代码, 不换编译器, 而在构建链路里把重复的编译劳动直接拿掉。下面这套操作, 我很早之前就想写成一篇总结。缓存工具怎么选、CMake 怎么接、命中率怎么调、CI 里怎么持久化、最后链接阶段怎么补, 这些坑我都踩过。这篇文章既适合正在被大项目编译折磨的工程师, 也适合刚接触 CMake 的 C 学习者。读完之后, 你应该能在半小时内把一个真实项目接入构建缓存, 并且知道后续优化该往哪个方向走。1. C 编译流程中的重复劳动1.1 拆开一次编译看时间都花在哪了C 从源码到二进制, 大致要经过预处理、编译、汇编、链接四步。预处理阶段负责展开头文件、宏替换, 把一个几千行的 .cpp 扩张成几万行甚至几十万行的翻译单元; 编译阶段则对这堆展开后的代码做词法、语法、语义分析, 再经过优化、生成汇编, 这一步通常最耗时; 汇编阶段把汇编指令翻译成机器码, 相对快; 最后链接阶段合并所有目标文件, 解析符号引用, 在大项目里也能吃掉不少时间。一个 .cpp 完整编译也许只要几秒, 但 100 个 .cpp 就是几百秒。更麻烦的是, 这些 .cpp 之间往往大量共享同一个头文件, 也就是说, 每个翻译单元都在重复展开同一段代码、重复解析同一些声明。这种重复劳动是 C 构建慢的根源, 也解释了为什么 C 的增量构建经常名存实亡。1.2 增量构建为什么救不了你Make 和 Ninja 这类增量构建工具, 底层模型是文件级依赖记录每个目标依赖哪些源文件和头文件, 然后通过时间戳和文件内容判断是否需要重建。这种模型在处理改了某个 .cpp时很高效, 毕竟只重编那一个目标就行。但一旦改动头文件, 问题就来了: 头文件是依赖的放大器和传染源。举个具体例子: 一个公共头文件被 500 个 .cpp include, 你只是调整了里面一个宏的取值, 500 个编译单元全部失效。从 Make 的角度看, 这 500 个目标都依赖这个头文件, 谁都不能跳过, 于是增量构建瞬间退化成了全量构建。更隐蔽的是, 很多公共头文件里塞满了常量、内联函数和模板, 这些东西在每个翻译单元里都会被重新解析一遍。这件事文件级增量构建解决不了, 只能靠更高层的缓存机制。1.3 缓存的本质:把编译变成查表构建缓存的核心思路, 不是追踪文件改没改, 而是判断这次编译的输入, 和上次某次编译的输入, 是不是一模一样。如果一模一样, 直接复用当时生成的对象文件。为了判断一模一样, 工具会计算一个哈希键, 里面包括预处理后的源码内容、编译器版本、命令行参数、相关头文件内容、绝对路径信息等等。哈希一致就是命中, 不一致就 miss, 老老实实重新编译。打个比方: 你做完一道数学题, 第二次遇到一模一样的题, 当然不需要重新演算, 直接抄答案就行。难点在于一模一样的判断必须绝对可靠——题目形式变一点、运算过程变一点, 答案都不该直接抄。缓存工具也一样, 判断得太宽松可能把错误结果当成正确结果, 判断得太严格又让命中率上不去。所以 C构建缓存加速的调优, 本质就是在可靠性和命中率之间找平衡, 这也是后面所有章节的主线。2. 三款主流缓存工具怎么选2.1 ccache:稳了二十年的单机方案ccache 应该是目前最广为人知的 C/C 构建缓存工具, 从 1999 年出现到现在, 经历了几代项目检验。它的核心行为很简单: 在真实编译器外面包一层, 计算哈希后决定是复用缓存还是调用编译器。ccache 支持 GCC、Clang, 对 MSVC 也有一定程度的支持, 虽然没有前面两个那么丝滑。ccache 有两种工作模式: 直接模式(direct)和预处理模式(preprocessor)。直接模式直接基于源文件和头文件的内容计算哈希, 附加开销小, 是默认推荐的选择; 预处理模式会先跑一遍预处理器, 拿展开后的完整代码做哈希, 在某些复杂场景下会回退到这个模式。对普通开发者来说, ccache 最大的优点是装上就能用, 最大的短板是缓存默认只在本地单机。想让 A 机器上编译过的结果直接在 B 机器复用, 就得靠共享文件系统或把 CCACHE_DIR 放到网络盘上, 体验算不上优雅。2.2 sccache:为共享缓存而设计sccache 是 Mozilla 用 Rust 写的构建缓存工具, 它拆分出了 client 和 server 两层: client 负责接收编译命令、计算哈希, server 负责把缓存结果存进共享存储。存储可以放在本地磁盘、内存, 也支持 S3、GCS、Redis 等对象存储或服务端。换句话说, sccache 天生就是为多台构建机共享一份缓存设计的, 这一点是它和 ccache 最根本的差异。sccache 不只支持 C/C, 对 Rust 的支持也很好, CUDA 编译也能走同一套缓存体系。如果你们团队有多个后端语言, 统一引入 sccache 可能会比每个语言单独配一套缓存工具更省心。代价是要多维护一个存储服务端, 环境变量、权限、网络配置都多一层。如果你只在单机开发, 用它反而有些大材小用。2.3 clcache 与 distcc,别搞混了clcache 是专门为 MSVC 的 cl.exe 设计的缓存工具, Python 实现。当你的构建环境是 Windows 原生 MSVC, 并且没有迁移到 CMake/Ninja 体系时, clcache 是值得考虑的方案。不过它本身的维护频率不高, 遇到新版本 Visual Studio 可能需要额外验证。distcc 则经常被误认为缓存工具, 实际上它是分布式编译: 把预处理后的源码分发到多台闲置机器上并行编译。它解决的是单次编译的墙钟时间太长的问题, 而不是重复编译被反复执行的问题。就算完全相同的代码编译两次, distcc 也会老老实实重新编译。所以 distcc 和缓存工具并不冲突, 甚至可以互补: 缓存负责让重复构建秒级完成, 分布式编译负责让首次构建或 miss 构建更快。2.4 选型参考表工具适用编译器是否支持共享上手复杂度典型场景ccacheGCC、Clang、部分 MSVC单机/NFS 共享目录低个人日常开发、本地重复构建sccacheC/C、Rust、CUDA 等S3/GCS/Redis 等中团队 CI、多机共享缓存clcacheMSVC cl.exe单机低Windows 原生 VS 工程distccGCC、Clang无缓存能力中大规模并行编译, 与缓存互补2.5 我的经验:先从 ccache 落地如果团队之前完全没用过构建缓存, 我的建议是老老实实先上 ccache。不是因为它最强, 而是因为它最不容易翻车。先在一个人的本机跑通, 看全量构建耗时降了多少, 把影响命中率的因素摸清楚, 再考虑要不要动 sccache 和分布式存储。我见过不少团队一上来就想搞分布式缓存, 结果缓存存储、路径漂移、权限、网络连通性这些问题一起爆出来, 团队最后觉得缓存方案不行而放弃。其实缓存本身没问题, 是步子迈太大了。C构建缓存加速这个事, 成功的关键是循序渐进, 先用一个可靠的简单工具建立信心, 再逐步升级。3. 把 ccache 接进 CMake:从零到命中3.1 安装与最小化验证Linux 上直接用发行版包管理器安装即可, 比如 Ubuntu/Debian 的sudo apt install ccache, macOS 上brew install ccache, Windows 可以用 scoop 或 choco 安装。装完之后先别急着接 CMake, 做一次最小验证: 打开终端, 创建hello.cpp, 然后执行两次ccache g -c hello.cpp。每次执行完用ccache -s看统计, 第一次应该是 miss, 第二次就应是 hit。这一步能确认 ccache 本身安装正常, 后面所有问题都出在构建系统接入姿势上。3.2 CMAKE_CXX_COMPILER_LAUNCHER 是唯一入口CMake 从 3.4 开始支持在真实编译器前面加 launcher, 这个机制本来就为 ccache 这类工具设计。关键点是: 这个变量必须在检测编译器之前设置, 也就是通过命令行-D传入, 或者在project()之前用set()写进 CMakeLists.txt。最常见的做法是命令行:cmake -S . -B build -DCMAKE_CXX_COMPILER_LAUNCHERccache如果你想确认有没有真正生效, 看第一次构建日志里每条编译命令是否以ccache开头, 或者直接盯ccache -s的统计数字在不在涨。很多教程只说加这个变量就够了, 但没提醒必须放在 project() 之前, 新手很容易把set()写在project()之后, 那样 CMake 可能已经确定了编译器路径, launcher 不会生效。3.3 用 CMakePresets 固化配置如果你换机器频繁, 或者团队里有新同事 onboarding, 我很推荐把这一层写进 CMakePresets.json。这样大家 clone 下来直接cmake --preset dev, 缓存配置自动带上, 不用每次口头解释环境变量。下面是我常用的片段:{ version: 3, configurePresets: [ { name: dev, displayName: Dev with ccache, binaryDir: ${sourceDir}/build/dev, cacheVariables: { CMAKE_CXX_COMPILER_LAUNCHER: ccache } } ] }有些团队会多留一个 ci preset, 把 launcher 设为sccache或者留空, 让 CI 用 CI 自己的缓存体系。我建议本地开发统一走 ccache, CI 单独配置, 两边的缓存目录和策略不要混在一起, 排查问题时会省很多力气。3.4 如何判断缓存真的生效了最直观的指标是ccache -s输出里的cache hit (direct)行。你连续执行两次干净的完整构建, 如果第二次命中率能到 95% 以上, 说明配置基本正确。但别把编译耗时下降当唯一依据——ccache 命中后的输出可能是复制对象文件, 也可能是硬链接, 如果缓存目录放在 IO 很差的机械盘上, 命中后仍然会花不少时间, 这会让新手产生缓存根本没有用的错觉。缓存目录尽量放在 SSD/NVMe 上, 物理介质对体验的影响比想象中更大。3.5 Windows/MSVC 下的特殊姿势Windows 上的情况比 Linux 绕。MinGW/GCC 工具链配 ccache 基本没坑; 但如果编译器是 MSVC 的 cl.exe, ccache 虽然能识别, 也必须拿到 INCLUDE 和 LIB 两个环境变量, 否则它封装 cl 的时候大概率会报错。所以不要在普通 cmd 里直接跑 CMake, 要去Developer Command Prompt或者 Visual Studio 的 CMake 集成环境里操作。说句实在话, 在 Windows 上我反而更愿意选 sccache: 它对 cl.exe 的兼容性更好, 省得折腾环境变量传递, 以后还能直接挂对象存储做共享缓存。如果团队就是 Windows MSVC 且暂时没有迁移计划, 直接按 sccache 的接入文档来, 会比在 ccache 上死磕舒服很多。3.6 常见看似生效实则无效的坑一些朋友配置完成后, 发现编译命令确实带了 ccache, 但每次重新构建命中率都很低。常见原因有三: 一是 CMake 检测到的编译器是绝对路径, 每次环境不同路径就不同; 二是编译参数里带了绝对路径, 比如-I/Users/alice/lib/include, 换台机器全部 miss; 三是项目在构建过程中动态生成头文件, 内容每次都有变化。这些我放到下一章详细展开。4. 为什么缓存经常不命中:命中率调优实录4.1 先学会读 ccache -sccache -s的输出看着字段很多, 关键是下面这几行:cache hit (direct): 直接模式命中, 这是最理想的情况cache hit (preprocessed): 预处理模式命中, 速度比 direct 略慢但仍是命中cache miss: 没命中, 实际调用了编译器called for link/called for preprocessing: 这些不算编译目标, 不用在意一个健康的本地开发环境, 重复编译同一份代码时命中率应该接近 100%; 但如果跨分支、改了很多头文件, 命中率掉到 70% 甚至 50% 也正常, 不必恐慌。真正要警惕的是: 明明什么都没改, 只是重启电脑后重新编译了一次, 命中率却只有一半, 那大概率是路径或时间类变量在捣乱。4.2 改一个注释为何引发雪崩在 direct 模式下, ccache 通过内容哈希判断头文件是否变化。你在公共头文件里加一行注释, 这个头文件的内容变了, 所有 include 它的翻译单元的哈希都会变, 于是大面积 miss。从正确性角度看这没什么错——你确实改了头文件, 重新编译更保险; 但很多团队因此觉得ccache 没用, 其实是误解了它的工作方式。真正让人难受的是touch 文件但内容没变的场景。如果你使用 preprocessor mode, 只摸一下文件都会 miss; 使用 direct mode 则不会, 因为 direct mode 按内容计算, 不关心修改时间。所以在日常开发中, 我始终建议保持 direct mode, 除非遇到某些无法兼容的编译参数才回退。另外, 千万别为了提升命中率把所有 sloppiness 都开满, 那是拿正确性换速度, 后面还会专门讲。4.3TIME和DATE是命中率杀手C 和 C 标准库里预定义的__TIME__、__DATE__、__TIMESTAMP__宏, 会记录编译时刻。只要源文件里用了它们, 比如:const char* build_time __DATE__ __TIME__;每次编译都会产生不一样的等价内容, 缓存必然 miss。解决办法有几类:构建缓存工具层面忽略时间宏, 比如 ccache 的CCACHE_SLOPPINESS里加time_macros如果确实要在日志里记录构建时间, 别把时间直接写进代码, 让构建脚本生成一个单独的版本头文件, 并接受这个文件每次变化带来的 miss生产环境更推荐用构建编号或版本号替代精确时间, 既能追溯发布链路, 又不会频繁让缓存失效实践里我发现很多小型项目都有类似写法, 改成构建编号后, 命中率的提升往往是立竿见影的。4.4 绝对路径漂移与 CCACHE_BASEDIR同一份源码, 放在/home/alice/proj编译, 镜像到 CI 的/build/proj再次编译, 即使把同一个缓存目录挂过去, 大部分键值也对不上, 因为源码文件的绝对路径被算进了哈希。CCACHE_BASEDIR就是为解决这个来的: 把它设置成项目根目录, ccache 在计算哈希前会把该目录下的绝对路径替换成相对路径, 于是只要项目根目录下的相对结构一致, 缓存就能跨机器复用。export CCACHE_BASEDIR/home/alice/proj注意, 如果项目大量使用了不在CCACHE_BASEDIR下的外部依赖, 路径漂移照样会存在。所以最省心的做法, 是让 CI 和本机采用同一种目录布局, 比如都在一个约定好的/opt/buildroot下展开代码。这个经验对 sccache 同样适用, 而且共享缓存场景下路径漂移造成的破坏更大, 因为一个错误键值会影响所有消费这台缓存的机器。4.5 关于 sloppiness,我的态度ccache 提供了CCACHE_SLOPPINESS环境变量, 可以把某些检查放宽松。常见项有time_macros、file_stat_matches、include_file_ctime等。我的态度是: 只在明确知道放宽某项检查不会导致错误结果时才加, 而且每加一项都要盯一段时间的 CI 结果, 不能为了命中率盲目叠加。缓存工具最怕的不是 miss, 而是错误命中。一旦你在发布前夜遭遇一次缓存告诉你编译过了, 但其实环境已经变了的问题, 团队对缓存的信任就会崩塌。所以宁可 miss, 不可错, 这是我在构建加速这件事上唯一不敢让步的原则。4.6 一个真实项目的调优结果我自己维护过一个约 200 万行的服务端 C 项目, 最初全量构建需要 27 分钟, 接入 ccache 后降到 9 分钟, 后来把统一目录布局、CCACHE_BASEDIR、消除__TIME__这几件事做完, 全量构建稳定在 6 分钟左右。命中率从 62% 拉到了 97%。增量构建方面, 改一个 .cpp 的编译阶段从 4 分钟压到 12 秒, 剩下的时间基本都花在最终链接上。这个数据不算夸张, 但也说明一件事: 缓存命中率高不等于整个构建一定快。因为缓存文件在命中之后仍然要读取、校验、复制到目标目录, 存储介质和缓存目录的 IO 能力, 会直接影响你感受到的爽度。这也是为什么我始终强调缓存目录要用 NVMe。5. 多机共享缓存与 CI 持久化玩法5.1 单机缓存的天花板本地开发阶段 ccache 确实舒服, 但有两个场景它帮不上大忙: 一是 CI 每次启动全新容器, 容器销毁缓存也销毁, 等于每次从零编译; 二是团队里 A 编译过的模块, B 还得再编一遍, 几台开发机互相之间缓存不共享。前者浪费的是 CI 算力, 后者浪费的是每个人的排队时间。如果只是追求大家能共用一份缓存, 最简单粗暴的办法是把CCACHE_DIR放到 NFS 上, 由网络文件系统充当共享缓存。这种做法在团队规模小、并发低时是能用的, 但一旦构建并发放大,NFS 的 IO 性能和锁竞争就会成为新瓶颈, 到时候还不如退回到单机缓存。5.2 GitHub Actions / GitLab CI 的目录缓存最常见的落地方式, 是把 ccache 缓存目录做成 CI 平台的缓存。以 GitHub Actions 为例:- uses: actions/cachev3 with: path: ~/.cache/ccache key: ${{ runner.os }}-ccache-${{ hashFiles(**/CMakeLists.txt, **/*.cpp, **/*.hpp) }} restore-keys: | ${{ runner.os }}-ccache-这里的 key 设计有讲究: 如果只用hashFiles, 源码一变 key 就变, 之前的缓存几乎等于作废。所以一定要加restore-keys, 让没有精确命中时能把最近一次的缓存恢复回来, 再由 ccache 自己判断哪些键值还能复用。GitLab CI 的思路也类似, 把.ccache/目录挂进cache关键字即可。需要注意别把 ccache 目录和构建目录放在同一个路径下, 否则清理策略会互相干扰。5.3 sccache 的共享架构当构建机很多、缓存需要跨机器甚至跨数据中心共享时, sccache 是更对路的方案。它的架构是每一台构建机上跑 client, 编译时把哈希发给 server, server 到共享存储里查结果。存储后端可选 S3 兼容对象存储、GCS、Redis 等。以内网 MinIO 为例, 典型配置大致是:export SCCACHE_BUCKETbuild-cache export SCCACHE_ENDPOINThttp://minio.internal.example export SCCACHE_S3_USE_SSLfalse export SCCACHE_REGIONus-east-1然后在 CMake 里把 launcher 换成 sccache:cmake -S . -B build -DCMAKE_CXX_COMPILER_LAUNCHERsccache对 S3/Redis 服务的连通性、权限要做足预案。sccache 在缓存服务不可用的时候通常会回退到直接编译, 不会让构建失败, 但你要确认自己用的版本确实有这个行为, 并且把缓存服务异常暴露到监控里。别等构建全绿但缓存全 miss 了才发现, 那就等于缓存白挂了。5.4 共享缓存的三条红线第一, 编译器版本和构建参数必须作为哈希的一部分。同一份源码不一定产生同一份对象文件, 编译器版本不同、宏定义不同、优化级别不同, 都可能是不同结果。ccache 和 sccache 默认都会考虑这些差异, 但你不能手动去覆盖或混淆。第二, Debug 和 Release 的缓存建议分开目录管理。虽然工具理论上会按参数隔离, 但分开目录之后, 排查为什么 Release 用了 Debug 的对象文件这类问题会直观很多。第三, 共享缓存一定要设置生命周期和容量上限。缓存是无状态资源, 不清理就会无限膨胀, 对象存储的请求量和费用也会跟着涨。我们团队的做法是 30 天滚动淘汰, 或者按容量阈值清理, 具体数字看项目规模和构建频率再定。6. 缓存之外,还有几块木板要补6.1 链接器正吃掉你的时间改一行代码, 编译阶段有了缓存可能只需要几秒, 但整个项目如果只有一个大二进制, 链接那一下可能就要十几分钟。所以缓存把编译压下来之后, 下一个瓶颈往往会暴露在链接阶段。Linux 上可以尝试把链接器换成 lld:cmake -S . -B build -DCMAKE_EXE_LINKER_FLAGS-fuse-ldlld实测对大型 C 二进制, 链接时间往往能降一半甚至更多。mold 这类工具在部分场景更快, 但它不是默认链接器, 引入前需要自己确认许可证和稳定性是否符合团队要求。Windows 下 MSVC 的 link.exe 没有直接替代品, 能做的更多是架构上拆分动态库或插件, 减少每次全量链接的体积。6.2 预编译头和 Unity Build 要配合使用预编译头(PCH)和 Unity Build(把多个源文件合并成一个大翻译单元)都能减少头文件的重复解析。CMake 3.16 之后, 分别对应target_precompile_headers()和set_target_properties(... UNITY_BUILD ON)。但这两者都会改变缓存的命中模式。PCH 本身要参与哈希, PCH 一旦变化, 所有使用它的翻译单元都会 miss; Unity Build 的合并顺序一变, 哈希也跟着变。所以别在接入 ccache 的同一天把这两个开关也全部打开, 否则你分不清提速是来自缓存还是来自合并编译。我的建议是开一个实验分支, 逐个开关地开, 对比总体时间和命中率的变化, 再决定生产构建最终采用哪套组合。6.3 头文件依赖本身才是根因说了这么多, 有个现实要面对: 缓存把重复编译拿掉了, 但并没有解决头文件解析太多的问题。一个 .cpp include 一个头文件, 头文件又 include 十几个内部头文件, 这棵依赖树可能非常深。长期来看, 还是要做头文件裁剪: 用前置声明代替 include, 把纯数据接口和重量级实现解耦, 尽量减少模板实例化。C20 Modules 是治本的方向, 但目前生态还在成熟阶段, 大型存量项目不要幻想一步切换。我见过一个团队把所有公共头文件做减法之后, 全量构建时间又降了 30%, 而且 ccache 的命中率进一步提升, 原因是每个翻译单元的哈希缩小了、依赖集合变简单了。缓存和依赖治理不是互斥的, 它们是乘法关系。我在自己项目里把缓存、lld、依赖裁剪这套事情做完之后, 最直观的感受不是数字多好看, 而是心态变了: 以前要改公共头文件, 得挑一个大家都不提交代码的时段, 生怕触发一次全组等待; 现在随手就能推, 因为即使触发大规模重编, 大部分也是缓存命中, 几秒钟就过去了。但如果只让我留一条经验, 我会说: 别为了追求漂亮的命中率, 把可靠性让出去。缓存可以一点点加, 信任一旦崩塌很难重建。