# GitHub Actions 快取容量上限：為什麼你的快取被移除、還原很慢，或沒有命中

> GitHub 的 Actions 快取每個儲存庫只有 10 GB，超過之後會刪除最久沒被讀取的項目，7 天沒用到的項目也會被刪掉。就算命中，也是一次下載到新 VM 上。每種修正的代價，以及為什麼保留磁碟的 Runner 讓大部分快取都變得不必要，每月固定 $39。

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：每個儲存庫 10 GB，7 天沒用到的項目會被刪除，每次命中都要重新下載
- Skipbox：套件快取和 Docker 的層留在你機器的磁碟上，快取空間至少是 GitHub 的 7 倍
- 4 vCPU 每月 20,000 分鐘：GitHub 上要 $222，Skipbox 上是 $39

**GitHub Actions 固定價格，分鐘數不限** Skipbox 在你的專屬機器上執行 GitHub Actions 作業：每月 $39，不論執行多少分鐘。Docker 層和相依套件快取在作業之間保留，下一個作業馬上就能開始。

4 vCPU Runner，每月 20,000 分鐘: GitHub $222 → Skipbox $39. 每月省下 $183.

換過來只要改一行：`runs-on: skipbox`。

[開始 7 天免費試用](https://app.skipbox.dev/sign-in?ref=g-github-actions-cache-size-limit-zh-hant)

## GitHub 的快取規則

依 GitHub 的[相依套件快取參考文件](https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching)、[Actions 計費](https://docs.github.com/en/billing/concepts/product-billing/github-actions)，以及它關於[超過 10 GB 的快取](https://github.blog/changelog/2025-11-20-github-actions-cache-size-can-now-exceed-10-gb-per-repository/)的 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）。

要看是什麼塞滿了它，依大小列出項目：

```bash
gh cache list --sort size_in_bytes --limit 20
```

儲存庫的 Actions › Caches 頁面也會顯示同樣的內容，以及每個項目的分支和最後使用時間。

## 為什麼還原很慢

在 GitHub 託管 Runner 上，快取命中就是一次下載到新 VM 上，再解開。它的時間隨封存檔變長，所以長到好幾 GB 的快取，花的時間可能和它原本要省掉的安裝一樣久。卡住的下載會被 actions/cache 的分段逾時切斷，預設 10 分鐘（`SEGMENT_DOWNLOAD_TIMEOUT_MINS`）。

大多數設定還原的東西也比大家以為的少。[setup-node](https://github.com/actions/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 上看得出來，依[我們用它們自己的作業執行的結果](https://skipbox.dev/zh-hant/guides/rust-cache-slow-rust-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 層快取](https://skipbox.dev/zh-hant/guides/docker-layer-cache-github-actions)）。
- **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。

## 換過去只要改一行

```yaml
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
```

1. 使用 GitHub 登入 Skipbox。
2. 安裝 Skipbox GitHub App，並選擇儲存庫。
3. 修改 `runs-on` 並推送。

快取步驟維持原樣就好。第二次執行就會在機器上找到第一次執行的快取。

## 安全性

- 機器只屬於你的帳號。其他公司的作業不會在上面執行。
- 每個作業結束後，Runner 的憑證、程序和容器都會被清除。開啟「每個作業都用新 VM」，每個作業就會改用一台全新的機器。
- 沒有寫入權限的人提交的程式碼（例如來自 fork 的 Pull Request），會在全新的 VM 上執行，可以讀取你的快取但不能修改。

詳情請見[作業如何隔離](https://docs.skipbox.dev/zh-hant/isolation)。

## 用快取沒命中的作業試試看

試用免費，為期 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 · https://skipbox.dev/zh-hant/guides/github-actions-cache-size-limit
