GitHub Actions cache-mode：检查绿色 CI 背后的缓存权限
如果 CI 显示为绿色成功结束，但在下一次运行时又重新下载依赖项，人们往往会先去修改缓存键。而现在，还必须确认是否因权限问题跳过了保存步骤。因为仅凭工作流成功这一事实，并不能证明缓存已被创建。
GitHub 于 2026 年 9 月 10 日宣布 cache-mode 全面正式发布（GA）。在 github.com 的所有方案中，均可在工作流或作业级别指定缓存访问权限。在前一篇探讨只读默认值的文章基础上，本文进一步聚焦于显式配置与验证方法。
已确认的功能：恢复与保存的四种组合
read 仅允许恢复，write 允许恢复和保存。write-only 仅允许保存，none 则同时阻止这两者。第一步检查就是要避免将 write 误解为仅限保存。
作业中声明的值优先于工作流级别的全局设置。相反，在可重用工作流调用中，获取的访问权限不能超出调用方允许的级别。请勿仅凭单个文件的声明就去判定整个运行的实际权限。
绿色的运行记录并非保存的凭证
官方文档说明，未获授权的缓存操作会留下提示日志并继续执行。被阻止的恢复会被视为缓存未命中处理，而被阻止的保存则不会执行。工作流本身不会失败，这是可观测性的核心所在。
因此，在运维记录中将运行成功与否与缓存结果分开记录会更有用。在单次运行中确认是由哪个事件触发的、应用了哪种模式、是否完成了恢复，以及是否跳过了保存。这是基于官方功能说明提出的一种运维建议，并非系统自动提供的新仪表板功能。
应用前先制作一份简明权限表
展开代码库的实际工作流，找出生产缓存的作业与消费缓存的作业。在受信任分支中准备依赖项的作业、测试外部变更的作业，以及验证部署产物的作业，无需绑定相同的权限。
针对每个作业写下两句话：该作业是否需要读取现有缓存？是否允许留下该作业的结果供下次运行读取？如果两者都不需要，就可以反思随手添加缓存的惯性做法。不过，实际配置仍需根据代码库的信任边界和构建架构来决定。
最小化实验：只读消费作业
例如，在测试工作流的顶层显式声明 cache-mode: read，并确认作业级别没有覆盖该设置。对比使用缓存时的测试结果与无缓存状态下的测试结果是否一致。缓存应当是缩短运行时间的辅助手段，如果缺少缓存会导致正确性发生改变，则应首先排查构建假设。
该实验的通过标准不是多了一条 CI 成功的记录，而是能够解释恢复尝试与跳过保存的行为，并能在下次运行中用相同输入再次验证。将实验前后的提交、触发器、有效配置及日志位置一同记录下来，便于其他同事复现判断过程。
可重用工作流需结合调用链路一并审视
即使在通用工作流中设置了安全的默认值，也必须连同调用方及各作业配置一同审查。不同代码库调用同一个文件的事实，并不等同于它们会以相同的权限运行。
审查时，请尝试从调用方开始，按作业的缓存声明、被调用工作流的顺序依次追踪。如果预期权限与实际日志不一致，在把键设计得更复杂之前，请先查明配置的来源。这是为了减少大量使用重用工作流的团队的诊断时间而提出的建议，并不代表经过测量的具体性能提升数值。
需要注意的例外情况与应用顺序
如果在 pull_request_target 等低信任度事件中显式指定 write 或 write-only，可能会覆盖只读的默认限制，进而增加缓存污染的风险。GitHub 在这种情况下会添加警告批注。切忌为了消除警告而盲目扩大写入权限。
反之，全盘阻止所有缓存的做法也是有代价的。这可能会导致下载和构建时间增加，因此建议先在一个具有代表性的作业中实际对比运行时间，然后再扩大应用范围。与其靠推测数字来承诺性能效果，不如由团队共同确定安全所需的限制与可接受的延迟。
团队现在应确认的问题
今天要做的事并非将新配置批量应用到所有代码库，而是在一个重要的工作流中找出缓存的生产者和消费者，写明权限，并在一次运行中核实恢复与保存的依据。如果是部署作业，请保持较小的改动范围，以便负责人能够查阅日志并确认是否符合预期。
实际工作中可能出现的问题是：既然保存步骤被跳过了，为什么 CI 还能成功？本文立足于官方行为机制对这一困惑进行了解释，并不包含专门的社区调研或普遍故障率的主张。在引入新功能时，分别核实性能结果与权限结果，有助于在下次遇到缓存问题时做出更准确的归类。