科技 · 实用指南
GitHub Actions 缓存无法恢复？先核对键、版本、分支范围与访问模式
缓存条目存在，不代表当前运行能够读取。删除缓存或更换运行器前，先逐项对照创建缓存与读取缓存的两次运行。
GitHub Actions 显示缓存未命中，并不能单独证明缓存从未保存、运行器故障或键发生变化。缓存版本、分支或 PR 引用范围、恢复键顺序、访问模式与条目是否仍存在，都会影响结果。
最稳妥的方法是建立两次运行的对照记录：一次成功创建缓存，一次未能恢复。逐项比较实际计算的键、路径与压缩输入、引用、事件、仓库、权限、查询结果和保存结果。
本指南分别处理精确未命中、部分恢复、PR 范围隔离与条目淘汰。先保存证据，再决定是否调整键或运行器，避免删除有用缓存或放宽不可信代码的权限。
先建立创建方与读取方的对照记录
选择一次成功保存的运行和一次原本应复用它的运行。两边记录仓库、工作流文件与提交、事件、github.ref、github.ref_name、适用的基础与来源引用、运行器系统和架构、action 版本、实际主键、全部恢复键、缓存路径、lookup-only、fail-on-cache-miss，以及最终恢复或保存日志。
不能只比较 YAML 模板。表达式在 push、pull_request、矩阵任务和可复用工作流中可能产生不同值。从日志取实际结果，或增加只输出非秘密身份字段的诊断步骤。不要打印令牌、环境秘密、凭据或私有文件内容。
把可见键与缓存版本分开核对
缓存版本包含路径与压缩工具相关元数据。两次运行即使显示相同键，路径输入、平台、压缩条件或 action 实现差异仍可能导致不兼容的版本。键相同并不排除真实未命中。
核对表达式展开后的路径输入，包括顺序、通配符、波浪号或工作区路径及系统差异，同时记录运行器镜像和 action 版本。不要用时间戳键掩盖疑似版本问题：不断产生新条目会使原始证据更难比较。
把引用范围当作可见性规则
pull_request 运行产生的缓存归属于 PR 合并引用，可以被该 PR 重跑使用，但基础分支或另一个 PR 无法恢复它。分支可以使用当前分支及规则允许的默认分支缓存，不能随意读取子分支或兄弟分支。
同时记录两次运行的事件与实际引用。如果同一键在 push 命中、在 pull_request 未命中，先比较范围，再调整运行器或路径。社区提问只能证明有人报告这一现象，不能证明原因；应按 GitHub 官方访问规则核对真实引用。
正确区分 cache-hit 与恢复结果
主键精确命中时 cache-hit 才是 true。主键未命中而恢复键找到前缀匹配时，数据仍可能恢复，但输出为 false。把 false 一概当作未恢复任何数据，可能导致不必要的重复操作。
一起保存恢复日志、匹配到的键和原始输出字符串。README 的 Outputs 部分将未命中输出记为空字符串，不要把所有非 true 值都当作 false。结合日志区分精确命中、部分恢复与没有恢复数据；部分恢复后仍可能需要安装依赖以适应依赖变更。 Stack Overflow 的提问者在后续答复中报告，把条件中的布尔值 true 改为字符串 'true' 后解决了自己的判断问题。这只是该工作流的报告，不能推广为所有缓存未命中的原因。
独立核查访问模式与仓库上下文
记录实际 ACTIONS_CACHE_MODE、工作流及 job 的 cache-mode、可复用工作流的权限上限，以及跳过操作的日志。read 只允许恢复；write 允许恢复和保存；write-only 只允许保存；none 两者都不允许。禁止读取而跳过恢复也可能显示未命中，不能据此证明条目不存在。
不要把所有 PR 都归为同一种限制。默认分支的低信任触发器限制，与 pull_request 合并引用隔离是不同规则。将仓库、事件、实际引用与生效模式一起核对。运行成功仍可能包含保存被拒或跳过的记录；保留警告并维持安全默认值，使用合适的可信创建方，而非给不可信代码增加写权限。
先证明条目仍存在
历史保存成功日志只能证明当时存在。存储限制、不活跃保留期限、手动删除及存储频繁淘汰都可能移除条目。用有权限的账号查看仓库缓存列表或 API，核对键、引用、创建时间、最近访问时间和大小。
不要把删除所有缓存当成诊断步骤。若条目不存在，保存原运行日志和清单查询结果，再受控创建一个替代条目。若它位于不同引用或版本不兼容，删除只会丢失证据，不能改变可见性规则。
根据结果只做一个可验证的调整
键相同但未命中时，先确认允许读取，再比较版本与引用。部分恢复时检查下游条件，同时按需同步依赖。PR 范围不匹配时使用合适的可信创建方或接受隔离。条目不存在时只运行一次受控创建并检查清单。不要为了命中而扩大不可信访问。
若各身份字段均一致且条目对预期引用可见，带着两次运行记录升级排查。提供运行链接、安全的实际输入、action 版本、运行器镜像、条目清单和最小复现工作流，让维护者调查真实缺陷，而不必要求你删除证据或暴露秘密。
