缓存 key 怎么设计
缓存按 key 隔离：用 lockfile 哈希做 key，让依赖变更即自动换缓存；前缀按分支隔离，避免不同分支互相污染；policy 控制读写角色。缓存的语义是加速而非存储：它不保证存在，任何命中失败都必须能回退到全量安装，关键文件永远走 artifacts 而不是 cache。
基本信息
| key | 字符串或 files（按文件内容哈希自动变化） |
|---|---|
| 前缀 | key 里带分支标识做隔离 |
| 策略 | policy: pull、push、pull-push |
| 语义 | 缓存不保证存在，命中失败要能回退全量安装 |
| 清理 | 旧缓存会成为孤儿，需要定期清理 |
典型使用场景
- 依赖缓存：node_modules、pip 与 maven 本地仓。
- 编译缓存：构建中间产物，注意与制品语义区分。
- 跨作业复用：同阶段多个作业共享一次安装结果。
- 分支隔离：不同分支各用前缀，避免互相污染。
- 只读作业：只下载不回传，避免并发覆盖。
按锁文件缓存
按锁文件缓存
cache:
key:
files: [package-lock.json]
paths: [node_modules/]
policy: pull-pushpolicy 对照
| policy | 行为 | 适用 |
|---|---|---|
| pull-push | 下载加回传 | 安装依赖的主作业 |
| pull | 只下载 | 只读作业避免覆盖 |
| push | 只回传 | 专门的缓存预热作业 |
只读作业可以 policy: pull 避免并发上传互相覆盖；上传统一交给一个作业处理。
key 变更即换缓存：调整 key 结构后旧缓存成为孤儿，定期在 Runner 侧清理释放空间。
缓存键要覆盖真实依赖：只写分支名时，依赖更新后缓存不失效，旧依赖一直被复用。
缓存容量按 Runner 配置：总容量超限时最旧的缓存被淘汰，热分支命中率会突然下滑。
按技术栈分 key：不同语言的缓存分开命名，失效互不影响，排查也有针对性。
预热策略：主干合并后主动跑一次安装作业，把常用缓存先热起来再跑后续作业。
key 规则升级带版本前缀：新旧缓存平滑过渡，避免结构变更引发全员冷启动。