GitHub Actions 快取容量上限:為什麼你的快取被移除、還原很慢,或沒有命中
GitHub Actions 給每個儲存庫 10 GB 的快取。儲存庫一超過它,GitHub 仍然會儲存新的項目,然後刪除最久沒被讀取的項目,直到回到上限以下,而 7 天內沒有作業讀取的項目也會被刪除。分支只能讀取自己和預設分支的快取,所以新分支的第一次執行常常沒有命中。而且命中仍然是一次下載:GitHub 託管 Runner 上的每個作業都從一台新的 VM 開始,所以又要下載並解開封存檔。你可以提高上限(超過 10 GB 的部分每 GB 每月 US$0.07),也可以調整你的 key,但下載還是在。
Skipbox 拿掉了下載。你的作業在帳號的專屬機器上執行,這台機器在作業之間保留下來,所以 npm、pnpm、Gradle、Go 和 Cargo 的快取以及 Docker 的層,都還在上一個作業留下的磁碟上(S 有 80 GB,GitHub 的 Runner 是 14 GB)。actions/cache 儲存的東西留在機器旁邊,所以還原就是一次本機讀取。改一行 runs-on: skipbox,每月固定 $39,分鐘數不限。
GitHub 的快取規則
依 GitHub 的相依套件快取參考文件、Actions 計費,以及它關於超過 10 GB 的快取的 changelog:
| 規則 | GitHub 怎麼做 |
|---|---|
| 容量 | 預設每個儲存庫 10 GB,所有分支和工作流程共用 |
| 超過容量 | 儲存新的項目,然後依最後存取時間由舊到新刪除項目,直到儲存庫回到上限以下。每小時執行一次移除 |
| 沒用到的項目 | 刪除超過 7 天沒被讀取的項目 |
| 更大的上限 | 在 Pro、Team 或 Enterprise 帳號上,管理員可以提高容量和天數。超過 10 GB 的部分每 GB 每月 US$0.07,以每小時的峰值計算。達到預算時,快取會變成唯讀,直到下一個計費週期 |
| 分支 | 一次執行從它的分支和預設分支還原快取;Pull Request 的執行還可以從它的基礎分支還原。絕不會從同層或子分支還原 |
| Pull Request | Pull Request 的快取限於它的 merge ref:只有那個 Pull Request 的重新執行能讀取 |
| 項目 | 無法修改。已經存在的 key 不會再被儲存 |
| 命中 | 只有 key 完全相符時,cache-hit 才是 true;restore-keys 的比對結果是 false |
| 速率 | 每個儲存庫每分鐘最多 200 次上傳和 1,500 次下載 |
為什麼快取會被移除
一個 10 GB 要裝下儲存庫儲存的所有東西。每個分支和每個 Pull Request 都會儲存自己的項目。三個 Node 版本乘上兩個作業系統的矩陣,就儲存六個。Docker 的 type=gha 建置快取也放在同一個 10 GB 裡。一天內儲存的量加起來超過上限時,每次新的儲存都會刪掉一個較舊的項目,而那常常正是下一個作業需要的。GitHub 稱之為快取顛簸(cache thrashing)。
要看是什麼塞滿了它,依大小列出項目:
gh cache list --sort size_in_bytes --limit 20
儲存庫的 Actions › Caches 頁面也會顯示同樣的內容,以及每個項目的分支和最後使用時間。
為什麼還原很慢
在 GitHub 託管 Runner 上,快取命中就是一次下載到新 VM 上,再解開。它的時間隨封存檔變長,所以長到好幾 GB 的快取,花的時間可能和它原本要省掉的安裝一樣久。卡住的下載會被 actions/cache 的分段逾時切斷,預設 10 分鐘(SEGMENT_DOWNLOAD_TIMEOUT_MINS)。
大多數設定還原的東西也比大家以為的少。setup-node 的 cache: 輸入儲存的是套件管理器的下載快取,不是 node_modules:還原之後,npm ci 仍然要安裝每個套件。setup-python 的 pip 快取也一樣:下載的檔案回來了,環境還是要重新安裝。
為什麼快取沒有命中
- key 變了。 用
hashFiles('**/package-lock.json')的 key,每次 lockfile 變動都不會命中。restore-keys會給出部分比對,這時cache-hit讀到的是false。 - 新的分支。 它可以讀取預設分支的快取,但不能讀取另一個功能分支的。如果預設分支從來沒跑過這個工作流程,就沒有東西可讀。
- 被移除了。 上限或 7 天的規則把它拿走了。
- 從來沒有儲存。 項目無法修改,所以已經存在的 key 永遠不會再被儲存,快取的內容也就一直停在第一次儲存時那麼舊。來自 fork 的 Pull Request 可能根本不被允許儲存。
把檔案傳給同一次執行中的下一個作業,是另一種工具。快取是給下一次執行用的;同一個工作流程裡後面的作業需要的建置輸出,要透過 actions/upload-artifact 和 actions/download-artifact 傳遞。Artifact 有自己的儲存空間,和那 10 GB 分開,而它們也是一次下載到新 VM 上。
每種修正在 GitHub 的 Runner 上的代價
- 提高上限。 移除變少,超過 10 GB 的部分每 GB 每月 US$0.07(GitHub 自己的例子:200 GB 全部用滿是每月 US$13.30),限 Pro、Team 或 Enterprise 帳號。還原仍然是下載,而快取越大,下載越久。
- 少存一點。 快取
~/.npm或 pnpm store,不要快取node_modules或建置輸出。只在預設分支上儲存,每個作業用actions/cache/restore,只在一個作業用actions/cache/save。這要花你的時間,而且快取越小,還原的東西也越少。 - 修好 key。 以 lockfile 作為 key,加上
restore-keys,並讓工作流程在推送到預設分支時執行,讓新分支有東西可讀。 - 保留磁碟的自架 Runner。 沒有下載,也沒有 10 GB 的限制。機器要你自己維運:作業系統更新、在作業之間清理環境又不刪掉快取,以及壞掉時修好它。
解法就是一台保留磁碟的機器
快取之所以存在,是因為機器會忘記。GitHub 託管 Runner 每個作業都是一台新的 VM,所以作業要把狀態存到 GitHub 的儲存空間,下次再取回來。在持續存在的機器上,這些狀態本來就在它的磁碟上:套件管理器的快取、工具快取、Docker 的映像檔和建置快取,甚至建置輸出。
差異在真實專案的 CI 上看得出來,依我們用它們自己的作業執行的結果:
- astro(Node.js、Turborepo): GitHub 上 528 秒,Skipbox 專屬機器上 30 秒,因為它保留了 turbo 的快取,所以預熱後的執行會重播 40 個建置任務,而不是重新執行。
- helix(Rust): 工具鏈和快取的步驟在專屬機器上花 9–10 秒,在 GitHub 上是 41–46 秒。
- tauri(Rust): GitHub 上 246 秒,專屬機器上 53 秒,
target/在作業之間保留下來。
Skipbox 把快取留在你的機器上
每個方案都附有一台你帳號專屬、在作業之間保留下來的機器:
- 套件快取留在磁碟上:
~/.npm、pnpm store、每個工具的~/.cache,以及 Go、Gradle、Cargo 和 Maven 的快取,還有setup-*安裝的工具。沒有東西需要還原。 - Docker 的映像檔、層和建置快取也會留下來。
docker build會重複使用上一次建置的層(Docker 層快取)。 - **actions/cache、setup-* 和 rust-cache 不用改。** 它們儲存的東西留在機器旁邊,而不是在 GitHub 的儲存空間裡,空間比 GitHub 每個儲存庫 10 GB 更多,還原也是在本機讀取。
- 磁碟上沒有 7 天的期限。 在作業之後磁碟快滿之前,什麼都不會被刪除;快滿時會先刪除最久沒用的東西。
S 方案的快取空間至少是 GitHub 的 7 倍。作業依標籤選擇規格:
| 標籤 | 機器 | 磁碟 | 方案 |
|---|---|---|---|
skipbox | 4 vCPU · 16 GB | 80 GB | S,每月 $39 |
skipbox-8x16 | 8 vCPU · 16 GB | 160 GB | M,每月 $79 |
skipbox-16x32 | 16 vCPU · 32 GB | 320 GB | L,每月 $149 |
私有儲存庫的 ubuntu-latest 只有 2 顆 CPU、8 GB 和 14 GB 的 SSD。在 Skipbox 上分鐘數不限。4 vCPU 每月 20,000 分鐘,GitHub 收 $222;Skipbox S 是 $39,少了 $183。
換過去只要改一行
jobs:
test:
runs-on: skipbox # was ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci && npm test
- 使用 GitHub 登入 Skipbox。
- 安裝 Skipbox GitHub App,並選擇儲存庫。
- 修改
runs-on並推送。
快取步驟維持原樣就好。第二次執行就會在機器上找到第一次執行的快取。
安全性
- 機器只屬於你的帳號。其他公司的作業不會在上面執行。
- 每個作業結束後,Runner 的憑證、程序和容器都會被清除。開啟「每個作業都用新 VM」,每個作業就會改用一台全新的機器。
- 沒有寫入權限的人提交的程式碼(例如來自 fork 的 Pull Request),會在全新的 VM 上執行,可以讀取你的快取但不能修改。
詳情請見作業如何隔離。
用快取沒命中的作業試試看
試用免費,為期 7 天或 3,000 作業分鐘,以先到者為準,不需信用卡。把那個作業改成 runs-on: skipbox,執行兩次,再把第二次執行的還原和安裝步驟與 GitHub 上的並排比較。
常見問題
GitHub Actions 的快取容量上限是多少?
預設每個儲存庫 10 GB,所有分支和工作流程加起來。超過之後,GitHub 仍然會儲存新的項目,然後依最後存取時間由舊到新刪除項目,直到儲存庫回到上限以下。7 天內沒有任何作業讀取的項目,不論容量多少都會被刪除。在 Pro、Team 或 Enterprise 帳號上,管理員可以提高上限和天數;超過 10 GB 的儲存空間每 GB 每月收 US$0.07,以每小時的峰值計算,一旦達到預算,快取就會變成唯讀,直到下一個計費週期。
為什麼我的 GitHub Actions 快取這麼常被移除?
因為儲存庫裡的所有東西共用同一個 10 GB:每個分支、每個 Pull Request、每個矩陣作業和每個作業系統,都會儲存自己的項目,Docker 的 type=gha 快取也放在同一個地方。一天內儲存的量加起來超過上限時,每次儲存都會刪掉一個較舊的項目,下一個作業就會錯過它需要的那一個。GitHub 稱之為快取顛簸(cache thrashing)。依大小列出項目(gh cache list --sort size_in_bytes),就能看出是什麼塞滿了它。
為什麼還原快取花的時間和從頭安裝一樣久?
因為命中仍然是一次下載。GitHub 託管 Runner 上的每個作業都從一台新的 VM 開始,所以 actions/cache 每次都要下載並解開封存檔,快取越大花的時間越久。setup-node 的快取帶回來的是套件管理器的下載快取,不是 node_modules,所以還原之後 npm ci 仍然要安裝每個套件。在保留磁碟的 Runner 上,快取本來就在,不用下載任何東西。
為什麼 actions/cache 在新分支上沒有命中?
一次執行可以從它自己的分支和預設分支還原快取,Pull Request 的執行還可以從它的基礎分支還原。它無法讀取同層其他分支的快取。所以功能分支的第一次執行,只有在預設分支儲存過那個 key 時才會命中。讓工作流程在推送到預設分支時執行,讓它儲存快取,並加上 restore-keys 做部分比對;只有 key 完全相符時,cache-hit 才會是 true。
Skipbox 保留多少 Actions 快取?
比 GitHub 每個儲存庫 10 GB 更多,而且就在你的機器旁邊,不在 GitHub 的儲存空間裡。在雲端機器上,作業用 actions/cache、setup-* 和 rust-cache 儲存的東西,會留在機器自己的磁碟上,最多占磁碟的一半(S 是 80 GB,M 是 160 GB,L 是 320 GB);在 Skipbox 主機上,主機的快取每個儲存庫保留 20 GB。不論哪一種,項目都在最後一次使用後保留 7 天,分支規則和 GitHub 相同。套件快取和 Docker 的層不經過它:它們直接留在磁碟上。
什麼會清除 Skipbox 機器上的快取?
作業之間什麼都不刪:快取留在機器上,只有作業之後磁碟快滿時,才會先刪除最久沒用的東西。機器在重設時回到乾淨狀態:你按下「重設機器」時、它的映像檔更新時(至少每月一次)、作業後健康檢查失敗時,以及作業達到 6 小時上限時。方案結束時,機器會連同它的磁碟一起刪除。
試用要花多少錢?
不用錢。試用為期 7 天或 3,000 作業分鐘,以先到者為準,不需信用卡。把快取沒命中或還原很慢的作業改成 runs-on: skipbox,執行兩次,再把第二次執行的還原和安裝步驟與 GitHub 上的比較。
更新於 2026年11月16日