GitLab CI/CD启用ccache共享缓存未提速的问题求助

算力阿峰

2026-7-7

排查GitLab CI/CD中ccache命中率为0%的问题

以下是针对你遇到的问题的具体排查步骤，按优先级排序：

1. 确认ccache是否实际参与编译流程

首先要排除CMake未正确调用ccache的情况：

在构建脚本中添加ccache -s命令，查看初始统计（首次构建前cache hits应为0），构建完成后再次执行ccache -s，如果cache misses和files cached增加，但cache hits始终为0，说明ccache被调用但未命中；如果cache misses也没变化，说明ccache根本没被触发。
检查编译日志，搜索是否有ccache前缀的编译命令（比如ccache gcc -c ...或ccache g++ ...）。如果没有，说明CMake的ccache配置未生效：
- 确认CMakeLists.txt中是否正确设置了编译器启动器：
```
find_program(CCACHE_PROGRAM ccache)
if(CCACHE_PROGRAM)
  set(CMAKE_C_COMPILER_LAUNCHER "${CCACHE_PROGRAM}")
  set(CMAKE_CXX_COMPILER_LAUNCHER "${CCACHE_PROGRAM}")
endif()
```
- 避免同时使用环境变量（如CC=ccache gcc）和CMake启动器配置，两者可能冲突。

检查.gitlab-ci.yml中的缓存配置：
- 确保cache.key设置为固定值（而非分支相关变量），实现全分支共享：
```
cache:
  key: shared-ccache
  paths:
    - /tmp/ccache/  # 需与Docker中CCACHE_DIR一致
  policy: pull-push  # 默认值，确保拉取+推送缓存
```
- 确认paths指向的目录与Dockerfile中设置的CCACHE_DIR完全匹配（比如Dockerfile中ENV CCACHE_DIR=/tmp/ccache，则CI缓存路径必须是/tmp/ccache/）。
检查缓存目录权限：GitLab CI缓存解压后，可能出现权限问题导致ccache无法读取缓存。在构建脚本开头添加：
```
chmod -R 777 $CCACHE_DIR  # 临时测试，后续可调整为更严格的权限
```
重新运行构建，查看命中率是否提升。

查看ccache详细缓存日志：在构建脚本中添加export CCACHE_VERBOSE=1，然后运行构建，日志中会显示每个编译单元的缓存命中/未命中原因（比如cache miss: different compiler version、cache miss: header changed等）。
检查ccache配置参数：运行ccache -p输出当前配置，重点确认：
- max_size：是否设置过小导致缓存被频繁清理（建议设置为10G以上，可通过export CCACHE_MAXSIZE=10G临时调整）。
- disable：是否被设置为true（若为true则缓存完全禁用）。
- hash_dir：是否开启（默认开启，确保不同目录下的相同代码能命中缓存）。
确认编译器与编译参数一致性：ccache会校验编译器版本、预定义宏、编译选项等，若不同分支/构建的这些参数不一致，会导致缓存失效。检查：
- 所有构建使用的Docker镜像是否一致（避免编译器版本差异）。
- 构建时的CMAKE_CFLAGS、CMAKE_CXXFLAGS等参数是否固定（避免每次构建传入不同参数）。

若你在CI中动态构建Docker镜像，需确保ccache目录被挂载到GitLab CI的缓存卷中，而非仅存在于镜像内部。建议使用预构建好包含ccache的镜像，避免每次构建镜像重置ccache环境。

确认Docker容器中运行构建的用户对CCACHE_DIR有读写权限，可在Dockerfile中添加：

RUN mkdir -p /tmp/ccache && chown -R builder:builder /tmp/ccache  # builder为CI运行用户
ENV CCACHE_DIR=/tmp/ccache

在CI构建脚本中添加以下命令，收集关键信息：

echo "CCACHE_DIR: $CCACHE_DIR"
ls -la $CCACHE_DIR
ccache -p
ccache -s
export CCACHE_VERBOSE=1

运行两次完全相同的构建（无代码变更），对比两次ccache -s的输出，若第二次cache hits仍为0，根据CCACHE_VERBOSE的日志定位未命中原因。

内容的提问来源于stack exchange，提问作者Piotr Ciosmak