C项目的构建速度大概是每个写过一段时间C的人都会遇到的头疼事。几百万行代码的仓库一次全量编译动辄半小时甚至一小时哪怕只是改了一个头文件的注释重新链接也常常要等上好几分钟。构建缓存加速就是在不改变源码结构、不重写构建系统的前提下把重复编译的时间压到最低的一套实用思路。这篇内容写给被“每次构建都要等半天”折磨的开发者也写给在CI上因为编译超时而焦头烂额的团队负责人。核心就是搞清楚缓存到底缓存了什么、怎么用ccache/sccache这类工具把命中率拉满、以及当缓存不生效时从哪几个方向去排查。先说个现象。很多C开发者第一次听说构建缓存时第一反应是“编译器不本来就有增量编译吗”。MinGW、MSVC、Clang这些编译器确实有自己的增量机制但“增量”和“缓存”是两码事。增量编译是在上一次构建的基础上只处理变动过的文件这依赖构建系统对依赖图的精确维护而缓存加速是直接跳过编译过程本身用哈希匹配的方式把以前算过的结果直接“抄答案”。理解了这一点后面所有的配置和调优逻辑都会清楚很多。1. 为什么C构建会成为效率瓶颈1.1 从一次“干净构建”说开去想理解缓存的价值就得先知道一次干净的C构建到底做了什么。很多新手以为编译就是“把代码变成二进制”这么简单但C的构建通常有预处理、编译、汇编、链接四个阶段整条链路里有几个环节是极其消耗CPU的。预处理阶段会把每个cpp文件里include的头文件全部展开一个几千行的cpp预处理之后可能变成几万行甚至几十万行。编译阶段要解析模板、做重载决议、生成抽象语法树最后生成汇编代码。这一步是纯CPU密集计算没有任何捷径。汇编阶段相对快一些但产生的目标文件数量多到一定程度后文件I/O也会成为瓶颈。最后的链接阶段虽然只做“拼接”但C的符号表、重定位信息非常复杂链接一个几GB的项目也常常要花上几十秒。我遇到过最夸张的情况是一个继承了十几年历史的老项目头文件层层嵌套一个cpp里光是公共头文件就include了十几个每个头文件里还有模板类。全量编译一次在当时的八核机器上要跑将近五十分钟。更难受的是代码逻辑改动其实只有几行但Java那种“改动一个类只重编一个类”的体验在C里根本不存在。1.2 改动一行代码为什么要重新编译那么多文件这里就得提到C最“原罪”的一个设计文本包含模型。头文件不是一种“接口声明”它会被预处理阶段原封不动地粘贴到每个cpp文件里。所以一个头文件哪怕只改了一个宏定义所有include了它的源文件都得重新编译一遍。打个比方这就像你有一叠打印好的文档每份都包含一个公共的封面页。有一天封面上的日期变了你不能只换封面而是要把所有文档重新打印一遍。模板类更狠模板的定义和实例化往往都写在头文件里几个cpp文件用同一个模板的不同参数组合等于把同一套模板代码反复编译多次。这也是为什么“改动一行代码”在C项目里经常意味着“重新编译几十上百个编译单元”。而构建缓存做的事情恰恰是把这些重复的编译结果保存下来下次遇到一模一样的输入时直接跳过CPU计算从缓存里把目标文件拷出来。所以它对C这种“结构性编译慢”的项目收益远比Java、Go这类编译模型快得多的语言要显著。2. 构建缓存的核心思路与常见方案选型2.1 缓存的本质让“重复劳动”变成“查表”构建缓存的基本原理其实很简单为每个编译单元也就是每个cpp文件计算一个哈希值这个哈希的输入包括源文件内容、头文件内容、编译器版本、编译参数、头文件搜索路径等。如果哈希一致说明这次编译和之前某次编译的输入完全相同那就不需要真正运行编译器直接把上次生成的目标文件复制过来即可。这套思路有一个关键前提编译器必须“纯函数化”。也就是说给定完全相同的输入必须产生完全相同的输出。实际项目里最大的变量来自两个地方一个是头文件路径编译时会把绝对路径记录进调试信息另一个是宏定义和编译器参数参数顺序不同也可能影响哈希结果。这两个问题后面会专门讲怎么处理。对比其他方案缓存的优势非常明显。它不改变源码结构不要求你改代码风格不要求你给每个类写前置声明。你只需要在构建系统里加一行配置让编译器“绕一下道”从缓存里取结果。对于已经有存量的大型项目这几乎是最平滑的优化手段。2.2 方案的取舍ccache vs sccache vs 构建系统自带缓存市面上的构建缓存工具不少最常用的有这几个ccache、sccache、Ninja自带的重建依赖机制以及Bazel这种重武器的远程缓存。我整理了一个简单的对比方便你根据自己的场景做选择。方案缓存位置支持的编译器优势劣势ccache本地磁盘GCC、Clang部署极简单社区成熟几乎所有Unix环境可用单机场景为主远程共享配置略麻烦sccache本地 远端存储Redis/S3等GCC、Clang、MSVC支持跨机器缓存共享CI场景很香多一个服务进程需要维护存储后端构建系统内置增量本地磁盘配合各编译器和构建系统深度集成状态信息丰富只做增量不做“跨分支/跨机器”缓存Bazel远程缓存远端存储GCC、Clang、MSVC通过规则大规模仓库最强支持远端执行需要迁移构建系统学习成本高先说明一个容易误解的点Ninja本身不是一个缓存工具但它的增量逻辑极其高效会精确记录每个输出的依赖和命令哪怕只是头文件的时间戳变了它也能判断出哪些目标需要重建。所以“Ninja ccache”是一个很常见的组合Ninja负责判断“要不要编”ccache负责“编的时候能不能直接抄”。如果你只是单机开发ccache是性价比最高的选择。如果你是团队协作CI上反复全量编译同一个仓库那sccache能让你直接省掉一大半的CI时间。如果公司项目大到需要上百台机器、上千个编译任务并行那Bazel那套才是长期解法。我的建议是不要一开始就上重型方案先用ccache把单机体验提到极致再按需上远端缓存。3. ccache实操从安装到项目接入3.1 安装与环境准备ccache本身是个很小的工具依赖非常少。Ubuntu/Debian上一条命令就能装好sudo apt install ccachemacOS上用Homebrew也一样brew install ccacheWindows环境稍微复杂一点但也不是不能用。MinGW和MSYS2的环境可以直接用包管理器装原生MSVC项目可以下载ccache的Windows编译版本或者更推荐直接用sccache它对MSVC的支持更完善。安装之后先验证一下ccache --version第一次使用前建议设置两个环境变量。一个是缓存目录默认是~/.ccache如果你的家目录在机械硬盘上而项目在固态硬盘上最好手动把缓存目录指到固态盘能明显提升读写速度。另一个是缓存上限export CCACHE_DIR/data/cache/ccache export CCACHE_MAXSIZE20GCCACHE_MAXSIZE按项目规模定一个中等规模的C项目所有目标文件加起来可能几个GB设个20G左右比较合理。太小了会导致缓存频繁淘汰太大又浪费磁盘空间。3.2 让CMake和Makefile用上ccacheCMake是现在C项目的主流构建系统接入ccache的方法非常简单。不需要改CMakeLists.txt只需要在配置时加一个变量cmake -B build -DCMAKE_CXX_COMPILER_LAUNCHERccache -DCMAKE_C_COMPILER_LAUNCHERccache如果你用的Makefile更直接在make命令里指定编译器make CCccache gcc CXXccache g -j8如果你用的是Ninja同样是通过CMake传入launcher。配置完成后构建流程会变成Ninja发现某个目标需要重新编译调用ccacheccache检查哈希如果命中直接把缓存里的目标文件复制到输出目录。整个过程对构建系统来说是透明的编译器路径没有变只是多了一层过滤。这里有个容易踩的坑如果你之前已经用CMake配置过好几次CMakeCache.txt里会记录旧的编译器路径。改了CMAKE_CXX_COMPILER_LAUNCHER之后最好删掉build目录重新配置一次否则变量不生效缓存自然也是空的。3.3 缓存命中率的观察与调优接入之后最关心的就是命中率。ccache自带一个很直观的统计命令ccache -s输出里有一排数据重点看这几个指标Hits命中的次数Misses未命中的次数Cache size当前缓存占用空间Uncacheable无法缓存的数量比如预处理错误、编译错误从我的经验来看单个开发者在本地正常改代码命中率保持在90%以上是应该的。如果你发现命中率很低先看编译参数是不是稳定。最常见的干扰项是编译参数里带了绝对路径比如-I/Users/me/project/include路径一旦因为目录迁移变化哈希就变了。解决办法是设置CCACHE_BASEDIR让ccache在计算哈希时忽略项目的根目录前缀同时打开CCACHE_NOHASHDIR告诉它不要因为调试信息里的绝对路径而影响哈希结果前提是你能接受调试信息里路径可能相对化。还有几个参数对性能影响比较大export CCACHE_BASEDIR$(pwd) export CCACHE_NOHASHDIR1 export CCACHE_DEPEND1 export CCACHE_SLOPPINESSinclude_file_mtime,file_macroCCACHE_DEPEND1是让ccache使用“依赖模式”只根据头文件的内容哈希做判断而不依赖头文件时间戳能显著减少必要预处理的工作量。file_macro这个选项要谨慎使用它对包含__FILE__宏的源文件放宽了哈希约束确实能提高命中率但如果你依赖__FILE__做路径相关的逻辑一定要测试清楚再开。提示如果你编译时用了-Werror因为警告而编译失败的目标不会被缓存这是正常的。错误的编译结果永远进不了缓存这个设计是为了防止缓存污染。4. 更进一步预编译头、Unity构建与分布式缓存4.1 预编译头PCH原理与配置当ccache把命中率拉到接近100%编译速度依然可能卡在“首次编译某个文件”上。这时候真正的性能瓶颈其实变成了头文件的重复解析。你想想几十个cpp文件都include同一个体积巨大的第三方头文件每个文件都得重新解析一遍同样的头文件这跟缓存无关是纯重复劳动。预编译头Precompiled Header解决的就是这个问题。PCH的思路是把项目中稳定的公共头文件打包编译成一个二进制快照之后编译器遇到include时直接加载快照而不是重新解析文本。这就像你去打印店店员把你常用的印章提前刻好每次盖一个章就行不用现场雕刻。CMake从3.16开始支持target_precompile_headers配置起来非常直接target_precompile_headers(MyTarget PRIVATE vector string unordered_map my_project/common.h )加了PCH之后首次全量构建可能反而变慢因为要额外生成一次PCH。但后续构建会快很多尤其是那些重头文件的文件。代价是PCH里任何一个头文件改动所有依赖这个PCH的文件都要重新编译所以PCH里只放绝对稳定的东西。第三方的、基本不动的、跨平台的标准库头文件是最佳选择自己项目里天天改的头文件不要放进去。4.2 Unity构建减少编译单元开销Unity构建是另一个思路字面上看有点反直觉把多个cpp文件合并到一个cpp文件里编译。比如你原本有100个cpp要分别启动100次编译器进程现在把它们合并成10个大文件启动10次编译器进程就够了。这样减少了进程启动的开销、头文件重复解析的开销还能让编译器对整个合并单元做更好的优化。CMake里开启Unity构建只需要一行配置cmake -B build -DCMAKE_UNITY_BUILDONUnity构建在GCC和Clang上效果非常明显尤其是那种大量小文件、每个文件都很短的项目。但要注意合并后的cpps可能因为两个源文件里有同名静态变量、同名匿名命名空间成员、或者宏冲突导致编译错误。解决方法是调整Unity分组策略或者用CMAKE_UNITY_BUILD_BATCH_SIZE控制每组包含的文件数量把冲突限定在可控范围内。我个人的经验是Unity构建和ccache并不冲突配合起来用效果更好。Unity构建减少了首次编译的CPU开销ccache则消除了重复编译的浪费。两者叠加构建时间能从“去泡杯咖啡”缩短到“起身接杯水”。4.3 分布式缓存与远端执行方案单机缓存的天花板在于一个人改完代码CI上还得全量编一遍。如果十个开发者都在改同一个仓库每台机器上都会产生各自的一套缓存互相不共享。分布式缓存就是把“共享缓存”这件事做了任何一台机器编译过的结果存到一个公共存储后端其他机器遇到相同输入时直接拉取。sccache是这里最推荐的方案。它由Mozilla开发最初是为Firefox这种巨型项目设计的。它支持本地缓存和远程缓存远程存储可以接Redis、S3、GCS、Memcached等。接入方式跟ccache类似cmake -B build -DCMAKE_CXX_COMPILER_LAUNCHERsccache设置好环境变量后sccache会把每次编译的结果统一上传到远端。CI的每次全量编译实际上大多数文件都是直接从远端缓存里拉的只有真正改动的文件才需要实际编译。我见过一个一百多人的团队CI编译时间从原先的20多分钟压缩到3分钟大部分时间还是花费在拉取代码和构建依赖上真正的编译过程几乎被掏空了。再往上走还有Bazel这类现代构建系统。它不仅做缓存还支持远程执行机器不够用时把编译任务派发到远端集群。这适用于动辄数GB源码、数千个编译任务的大项目。代价是需要付出较大的学习成本和构建系统迁移成本。对于大多数中小团队来说sccache已经足够香了。5. 常见问题与排查技巧实录5.1 缓存命中率低、缓存不生效的典型原因我见过很多团队兴致勃勃地接入ccache第二天一看统计命中率只有20%然后开始怀疑工具是否好用。这里列一下最常见的几个坑。第一个是编译器版本不一致。如果你在开发机上用GCC 9CI上用的是GCC 11两边编出来的目标文件自然不一样缓存也不可能共享。跨编译器版本的缓存是完全隔离的ccache会在哈希里带上编译器版本信息。如果你想让多台机器共享缓存先用ccache -p检查一下配置差异再统一编译器的版本和路径。第二个是编译参数动态变化。比如Makefile里根据构建类型设置了不同的-DDEBUG、-DNDEBUG或者每次都把__DATE__、__TIME__这些内置宏打进输出。这些都会导致同一个文件在不同时间编译出不同的哈希。__TIME__这种动态值会直接杀死缓存如果不需要编译时记录时间戳建议关掉。第三个是绝对路径问题前面提过。如果你的构建脚本用了类似-I$(shell pwd)这种写法每台机器的路径不同哈希就不同。给ccache设置CCACHE_BASEDIR能解决大部分问题但需要每个开发者都保持一致的配置。5.2 缓存污染与“看起来命中但结果不对”缓存污染是一个相对少见但极其严重的问题。ccache本身对输入的哈希校验非常严格正常情况下不会把错误的编译结果存进去。但有一种情况比较危险如果你在编译过程中手动中断了编译器或者构建系统在你编译的同时修改了源文件ccache可能记录到一个“不完整”的输出状态。ccache对此有防护机制但保险起见在CI上如果发现某次构建产物行为异常先执行一次ccache -C这个命令会清空整个缓存强制全量重新编译。虽然慢一次但能排除“缓存拿到的目标文件过期”的可能。另一个容易被忽略的是“命中但链接产物太小”。有些编译单元确实很快比如一个只有几行代码的cpp缓存命中后从磁盘复制目标文件这个过程可能只要几十毫秒。但如果你发现链接阶段还是特别慢问题就不在编译缓存了而在链接器的符号处理上这时候该考虑的是增量链接、动态库拆分甚至换用lld或mold这类更快的链接器。5.3 排查思路速查表现象可能原因排查方法命中率低于50%头文件频繁变化、编译参数不一致用ccache -s看Miss次数检查编译命令差异缓存占用暴涨多个项目共享一个缓存目录、不同参数组合多调低CCACHE_MAXSIZE为不同项目设置独立缓存目录同一文件每次都是Miss__TIME__/__DATE__宏、绝对路径变化设置CCACHE_BASEDIR、CCACHE_NOHASHDIRCI和本地互不相同编译器版本或路径不一致统一编译器版本统一缓存放后端编译结果可疑缓存污染、中断残留执行ccache -C全量重编一次有一个调试技巧特别有用ccache支持日志输出设置CCACHE_LOGFILE后每次缓存判断的原因都会被记录下来。比如export CCACHE_LOGFILE/tmp/ccache.log日志里会写清楚某个编译任务为什么Miss是头文件变了、参数变了还是编译器版本变了。这比盲目猜要高效得多。6. 实测效果与个人心得6.1 一个具体项目的加速数据讲一个我实际参与过的中型项目。项目是Windows和Linux双平台的一套C服务大约200个cpp文件依赖了一批公共库。原来在Linux CI上全量编译大约6分半钟改动一个头文件重编的时间也不短。接入ccache之后本地的增量构建从原先的“两分钟起步”降到了十五秒左右绝大多数时间还是花在了链接上。后来CI切换成sccache加Redis远端缓存冷缓存全量编译需要六分钟但第二次以后基本稳定在一分半钟因为绝大多数目标文件直接从远端拉取了。还有一个细节值得说接入缓存后“切换分支”的体验提升巨大。以前在两个功能分支之间来回切换每次切完都要重新编一大堆文件因为头文件内容变了。有了缓存之后切换分支后第一次编译可能还有不少Miss但只要编过一次切回去再切回来那些内容没变过的分支文件全部命中重新构建的时间几乎可以忽略不计。6.2 一些经验体会用到现在我自己有几个很深的体会。第一缓存的收益不是线性的它在你最频繁的操作上放大得最明显。C开发日常最多的不是全量编译而是“改一个文件然后反复构建验证”缓存把这件事从“等待”变成了“几乎是瞬时的正反馈”。第二缓存的杀手不是缓存本身而是不稳定。同一个项目今天能命中明天全Miss排查起来非常痛苦。所以从一开始就要养成好习惯编译参数要写死路径要用相对路径编译器版本要用同一个CI和本地要用同一套配置。这些工作看着琐碎但都是“花十分钟配置省下来的却是每天无数次等待”。第三构建速度是团队协作里最容易忽视的“隐性成本”。每个人每天等编译的时间加起来远远超过你的想象。几十个人的团队一天浪费在构建等待上的人时可能就有十几个小时。把这个时间省下来不只是大家的体验变好了整个项目的并行开发效率也会明显提高。我个人在实际操作中还有一个建议不要只盯着缓存工具本身可以顺带把编译时的-j并发数也调一调。有些机器默认编译并发数配得太保守缓存命中率高反而让CPU闲置了。用nproc看看核心数再配合ccache的并行输出复制构建速度还能再往上走一截。我试过在16核机器上把-j16和ccache搭配起来有空闲核心的情况下缓存命中的构建几乎全被I/O速度接管而不再是CPU时间。总之构建缓存加速是一次投入、长期回报的事早一天接入就早一天告别无休止的等待。
