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 自动计算锁文件内容哈希：
alfred-github-backup
下载
GitHub 仓库备份技能 - 将 OpenClaw 工作空间自动或手动备份至 GitHub 私有仓库。支持自动定时备份和手动交互式配置，引导完成 Token 配置、仓库创建、首次备份及定时任务设置。用途：(1) 首次设置 (2) 日常备份。
-
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%。
