科技 · 實用指南
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 版本、執行器映像、快取清單與最小重現工作流程，讓維護者調查缺陷，而不必刪除證據或暴露秘密。
