GitLab CI 怎么配置缓存加速构建流程

GitLab CI 缓存加速构建的关键在于选对路径、算准 key、避开平台陷阱：缓存需结合包管理器自身缓存目录，key 应基于锁文件哈希，且所有 runner 必须统一基础镜像以避免污染。

GitLab CI 配置缓存加速构建，核心不是“多缓存什么”，而是“缓存对、命得准、不污染”。关键在三点：选对路径、算准 key、避开平台陷阱。配置本身几行 YAML 就能搞定，但细节错了反而拖慢构建。

选对缓存路径，别只盯 node_modules

单纯缓存 node_modules/ 效果差——它体积大、文件多，上传下载慢，还容易因平台差异失效。真正高效的做法是配合包管理器自身缓存目录一起缓存：

• npm 项目：缓存 node_modules/ + package-lock.json（用于生成 key）
• yarn v1：缓存 node_modules/ + .yarn-cache/
• yarn v3+ 或 pnpm：缓存 node_modules/ + .yarn/cache/ 或 .pnpm-store/
• Maven 项目：缓存 .m2/repository/ + pom.xml（用于 key）

这样既能跳过重复下载，又大幅减少传输量——实测比单缓存 node_modules 快 2–3 倍。

用 files 方式生成 key，锁文件变了才换缓存

别用 $CI_COMMIT_REF_SLUG 当 key。它只看分支名，哪怕你改了一行依赖，缓存还是旧的，轻则装错版本，重则构建失败。

正确做法是让 GitLab 自动计算锁文件内容哈希：

• key: files: [package-lock.json]（npm）
• key: files: [yarn.lock]（yarn）
• key: files: [pom.xml]（Maven）

只要锁文件没变，就复用缓存；一改，自动触发新缓存。这才是“依赖不变，秒过安装”的底层逻辑。

规避缓存污染，统一环境是前提

node_modules 里有编译型模块（比如 sharp、node-sass），它们绑定 Node ABI 和系统库。Linux 上缓存的模块，在 macOS 或不同 glibc 版本的镜像里直接复用会崩溃。

• 所有 runner 必须用同一基础镜像，例如 node:20-bullseye 或 maven:3.9-openjdk-17
• 禁止跨操作系统共享缓存——Linux job 不能 restore macOS job 推送的缓存
• 原生模块多的项目，可在 before_script 加检查：ls -la node_modules/.bin | head -5，确认关键命令存在且可执行

配合安装命令，让缓存真正生效

缓存再好，装依赖时用错命令也白搭：

• 必须用 npm ci 或 yarn install --frozen-lockfile，不能用 npm install
• npm ci 会清空旧 node_modules 并严格按 lock 文件还原，避免残留干扰
• 加 --no-progress 减少日志开销；yarn 可配 yarn config set ignore-engines true 跳过引擎校验（尤其 Node 升级时）

这些组合下来，依赖安装从几分钟压到 1–3 秒，缓存命中率轻松超 85%。