CI/CD / 系统课时

缓存没有命中怎么定位

缓存没有命中怎么定位

GitHub Actions 缓存持续 miss 时,问题通常不在“缓存服务坏了”,而在缓存键发生变化、路径没有实际内容、分支作用域不同,或依赖锁文件改变。排查时应同时观察 key 的生成依据和缓存步骤日志,避免盲目修改 key。

学习目标

  • 能从缓存日志判断是首次创建还是异常未命中
  • 能检查 key、缓存路径、分支作用域和锁文件变化
  • 能设计稳定且会随依赖变化失效的缓存键

先把 key 和路径变成可观察信息

缓存排障第一步是确认本次运行到底使用了什么 key。对于 actions/cache,key 必须精确匹配才能直接命中;restore-keys 可以在精确匹配失败后寻找前缀匹配的缓存。

下面以 npm 下载缓存目录为例。hashFiles('**/package-lock.json') 会让锁文件内容变化反映到 key 中:

yaml
name: cache-check
on:
  workflow_dispatch:

jobs:
  check-cache:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Show npm cache path
        run: npm config get cache

      - name: Restore npm cache
        id: npm-cache
        uses: actions/cache@v4
        with:
          path: ~/.npm
          key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-npm-

      - name: Report cache result
        run: echo "cache-hit=${{ steps.npm-cache.outputs.cache-hit }}"

首次使用新 key 时,预期结果类似:

text
/home/runner/.npm
cache-hit=false

相同 key 已存在时,最后一行预期为:

text
cache-hit=true

实际日志还会包含缓存恢复或保存信息,其细节可能随 Action 版本变化,因此判断时重点看 cache-hit 和最终使用的 key。

检查 key 为什么变化

如果每次运行都 miss,先检查 key 中是否混入每次都会变化的数据,例如运行编号、提交 SHA 或时间戳。这些值会让每次运行产生全新的 key,缓存自然无法复用。

锁文件哈希则是有意的变化来源。package-lock.json、pnpm-lock.yaml、yarn.lock 等发生变化后,新 key miss 通常是正确行为,因为依赖集合已经改变。此时 restore-keys 可以复用较接近的旧缓存,再由包管理器补齐差异。

确认缓存路径真的有内容

key 正确并不意味着一定能保存有效缓存。路径写错、目录尚未创建,或者缓存步骤执行后没有任何工具向该目录写入内容,都会让后续运行无内容可恢复。

对于 npm,可用下面的命令确认真实缓存目录:

bash
npm config get cache

预期输出

text
/home/runner/.npm

Linux GitHub-hosted runner 上通常得到上述路径;不同 runner 或配置下实际路径可能不同。应以命令返回值为准,并让 path 与真实缓存目录一致。

检查分支作用域和锁文件

缓存具有作用域限制,并不是仓库中任意分支创建的缓存都能被所有其他分支无条件读取。若默认分支可以命中,而某个功能分支持续 miss,应结合缓存创建分支、当前分支以及工作流触发方式检查可访问范围。

GitHub Actions 缓存未命中排查流程

定位时不要把“锁文件变化导致新 key”和“缓存机制异常”混为一谈。最可靠的验证方法是在依赖和 key 都不变的前提下连续运行两次:第一次允许创建缓存,第二次应观察到精确命中;若仍为 false,再回到路径、保存日志和分支作用域继续检查。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

缓存没有命中怎么定位

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通