GitHub Actions cache-mode 更新后如何限制缓存访问范围

GitHub Actions 最近增加了 cache-mode，可以把缓存权限从“这个工作流能不能用缓存”细化为“能恢复、能保存、只能保存，还是完全不能访问”。如果你的仓库同时运行可信的 push 构建和来自外部贡献的检查，建议先把低信任任务设为 read，再把确实需要写缓存的任务单独提升到 write。

官方地址：https://github.blog/changelog/2026-09-10-control-github-actions-cache-access-with-cache-mode/

cache-mode 到底限制了什么

它限制的是当前 job 拿到的缓存访问令牌，而不是缓存 key 的命名规则。四种模式的行为可以先按下面的表判断：

先把低信任工作流固定成 read

不显式设置时，GitHub 会根据触发器给出默认权限：可信触发器通常得到 write，低信任触发器通常得到 read。为了让配置意图不依赖默认值，可以在工作流顶层明确写出：

name: pull request checks

on:
  pull_request_target:

# 只允许恢复缓存，防止外部输入参与写入共享缓存
cache-mode: read

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/cache@v4
        with:
          path: ~/.npm
          key: npm-${{ hashFiles('**/package-lock.json') }}
      - run: npm ci
        # 缓存未命中时仍安装依赖，read 模式不会阻止后续步骤

在这种配置下，恢复成功仍然可以加速检查；保存阶段如果没有写权限，会被跳过并给出提示，job 不会因此失败。若根本不需要保存动作，也可以使用 actions/cache/restore，让工作流语义更清楚。

需要写缓存时只提升具体 job

一个工作流可能既有测试 job，又有可信的依赖预热 job。此时不要把整个 workflow 都改成可写，而是用 job 级配置缩小授权面：

cache-mode: read

jobs:
  checks:
    runs-on: ubuntu-latest
    # 继承 workflow 级 read，只做恢复
    steps:
      - uses: actions/cache/restore@v4
        with:
          path: ~/.cache/go-build
          key: go-${{ hashFiles('**/go.sum') }}

  trusted-build:
    runs-on: ubuntu-latest
    cache-mode: write
    steps:
      - uses: actions/cache@v4
        with:
          path: ~/.cache/go-build
          key: go-${{ hashFiles('**/go.sum') }}
      - run: go test ./...
        # 只有可信 job 承担缓存保存责任

作业级值会覆盖 workflow 级值。运行器还会通过 ACTIONS_CACHE_MODE 暴露有效模式，可在诊断日志中打印它来确认最终权限，而不是只看 YAML 的缩进位置。

可复用工作流和缓存投毒风险要一起看

cache-mode 会沿着 reusable workflow 传播。调用方 job 如果明确只给 read，被调用工作流声明 write 就会触发校验错误，运行不会开始。这个行为很适合把公共构建流程做成“默认只读”，由调用方按可信程度授权。

需要特别小心的是：显式把低信任事件改成 write 或 write-only，会绕过原本的只读保护，重新引入缓存投毒风险。缓存内容没有签名，任何能读到缓存的流程都应把它当作不可信输入；不要把 token、登录凭据或其他敏感文件放进缓存路径。

更稳妥的分工是：可信的 push 工作流负责保存缓存，外部贡献触发的检查只恢复缓存；如果业务确实需要低信任流程写入，就先确认它不会处理未信任代码，并让后续高权限流程把这些缓存视为不可信。

常见问题

不写 cache-mode 会立即失效吗？

不会。省略时仍按触发器使用现有默认值，但显式配置更容易审查，也能避免 reusable workflow 意外请求更高权限。

read 模式下保存失败会让任务失败吗？

不会。保存会被拒绝或跳过，步骤和 job 继续执行；需要避免日志警告时，可直接使用 restore 专用 action。

write-only 适合普通构建吗？

通常不适合。它不能恢复旧缓存，只能保存新缓存，适用于明确承担预热或写入职责的独立任务。

迁移时可以按“先全局 read、再给可信 job 最小化提升、最后检查 reusable workflow”三步落地。真正需要关注的不是缓存是否命中，而是哪一段未信任输入拥有了改变共享缓存的机会。