# GitHub Actions 的 Docker 層快取：為什麼每次建置都從冷啟動開始，以及怎麼保留層

> 每個 GitHub Actions 作業都從一台沒有 Docker 建置快取、也沒有拉取過的映像檔的新 VM 開始，而 setup-buildx-action 預設的 builder 一開始也是空的。buildx 的 cache-to 和 cache-from（gha、registry、local）會以下載的方式把層帶回來，而且在 GitHub 的 10 GB 之內。在磁碟上保留 Docker 建置快取的 Runner，這些都不需要，每月固定 $39。

每次 GitHub Actions 執行都會失去 Docker 的層快取，是因為 GitHub 託管 Runner 上的每個作業都從一台新的 VM 開始：沒有建置快取，也沒有拉取過的映像檔。docker/setup-buildx-action 預設的 builder（`docker-container`）也在每個作業開始時是空的，結束時就被移除。常見的解法是用 buildx 匯出快取。`cache-to: type=gha,mode=max` 和 `cache-from: type=gha` 把層留在 GitHub 的 Actions 快取裡，每個儲存庫 10 GB，和其他所有快取共用；`type=registry` 把它們留在你的 registry；`type=local` 則留在你用 actions/cache 儲存的目錄裡。每一種都是把重建變成每次執行的一次上傳和一次下載。

Skipbox 把層留在建置執行的地方。你的作業在帳號的專屬機器上執行，這台機器在作業之間保留 Docker 的映像檔、層和建置快取，S 的磁碟有 80 GB，GitHub 的 Runner 是 14 GB。`docker build` 和 `docker compose build` 會重複使用上一次建置的層，compose 拉取過的映像檔也已經在磁碟上。setup-buildx-action 照原樣使用，它的 builder 同樣找得到這些層。改一行 `runs-on: skipbox`，每月固定 $39，分鐘數不限。

- GitHub：每個作業一台新的 VM，所以每次執行都沒有層、沒有映像檔，buildx builder 也是空的
- Skipbox：Docker 的建置快取和映像檔留在你機器的磁碟上，所以沒變動的層不用重建，也不用下載
- 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-docker-layer-cache-github-actions-zh-hant)

## 為什麼每次建置都從冷啟動開始

- **每個作業一台新的 VM。** GitHub 的 [Runner 參考文件](https://docs.github.com/en/actions/reference/runners/github-hosted-runners)說，每個 GitHub 託管 Runner 都是一台由 GitHub 託管的新虛擬機器（VM）。上一個作業建置或拉取的東西都不在上面。
- **一個空的 builder。** [docker/setup-buildx-action](https://github.com/docker/setup-buildx-action) 預設會以 `docker-container` driver 建立並啟動一個 builder，而它的 `cleanup`（預設開啟）會在作業結束時移除這個 builder。
- **14 GB 的磁碟。** 私有儲存庫的 `ubuntu-latest` 只有 2 顆 CPU、8 GB 和 14 GB 的 SSD。一個大型映像檔、它的建置快取，再加上一個要解開的快取封存檔，就可能把空間用完（「no space left on device」）。

## buildx 的快取後端，以及各自的代價

依 Docker 的[快取後端](https://docs.docker.com/build/cache/backends/)和[用 GitHub Actions 管理快取](https://docs.docker.com/build/ci/github-actions/cache/)：

| 後端 | 層存在哪裡 | 每次執行要付出什麼 | 限制 |
|---|---|---|---|
| `type=gha` | GitHub 的 Actions 快取 | 上傳新的層，下載需要的層 | 每個儲存庫 10 GB，和其他所有快取共用，最舊的先移除；預設的 scope `buildkit` 每次建置都會被覆寫；GitHub 的快取 API 會限流 |
| `type=registry` | 你 registry 中一個獨立的快取映像檔 | 從 registry 拉取快取，再推送新的 | 需要有推送權限的 registry 登入；registry 的儲存空間和流量 |
| `type=inline` | 映像檔本身裡面 | 拉取映像檔來讀取它的快取 | 只能 `mode=min`：中間 stage 的層不會保留 |
| `type=local` + actions/cache | 用 actions/cache 儲存的目錄 | 下載並解開整個目錄，再上傳 | 除非 [`reset=true`](https://docs.docker.com/build/cache/backends/local/)（Buildx 0.35.0 以上），否則每次執行都會變大；算進 10 GB |

不論選哪個後端，都要[安排好 Dockerfile 的順序](https://docs.docker.com/build/cache/optimize/)，讓最少變動的層放在最前面：先複製 lockfile 並安裝相依套件，再複製原始碼。否則每個 commit 都會讓安裝那一層失效，什麼快取都救不回來。

`mode=min` 是預設值，只保留最終映像檔的層。`mode=max` 保留每個 stage 的層，所以多階段建置的命中更多，上傳的也更多。

典型的 `type=gha` 設定，每個映像檔有自己的 scope：

```yaml
- uses: docker/setup-buildx-action@v4
- uses: docker/build-push-action@v7
  with:
    context: .
    tags: app:ci
    load: true
    cache-from: type=gha,scope=app
    cache-to: type=gha,scope=app,mode=max
```

**Cache mount 不會留下來。** `RUN --mount=type=cache`（建置中套件管理器的快取）預設不會保留在 GitHub Actions 快取裡；Docker 的文件指向 [buildkit-cache-dance](https://github.com/reproducible-containers/buildkit-cache-dance)，用來把它搬進搬出 actions/cache，每次執行又多一次下載和上傳。

## docker compose 每個作業都拉取所有映像檔

用 `docker compose up` 啟動 Postgres、Redis 和幾個服務的整合測試，每個作業都要拉取所有映像檔，因為 VM 是新的。在 GitHub 託管 Runner 上，這些選項只是把下載移到別處：

- 用 `docker save` 把映像檔存成 tar 檔，用 actions/cache 快取，再在下一個作業 `docker load`。這算進 10 GB，載入本身也要花時間。
- 用 buildx 和上面的某個快取後端建置服務映像檔，但基礎映像檔還是要拉取。

## 解法就是一台保留 Docker 快取的機器

上面的每一種後端之所以存在，都是因為 builder 會忘記。在作業之間持續存在的 Docker daemon，自己的磁碟上就已經有上一次建置的層、它的 cache mount，以及它拉取過的每個映像檔。沒有東西要匯出、沒有東西要匯入，也沒有要共用的 10 GB。

## Skipbox 把 Docker 的快取留在你的機器上

每個方案都附有一台你帳號專屬、在作業之間保留下來的機器：

- **`docker build` 和 `docker compose build`** 會重複使用上一次建置的層，工作流程不用改。
- **映像檔留在磁碟上。** `docker compose up` 會找到上次拉取的映像檔；`docker compose pull` 只抓取有變動的層。
- **Cache mount 會留下來**，跟著 Docker 的建置快取一起，所以 `RUN --mount=type=cache` 不用額外步驟就能保留套件管理器的快取。
- **docker/setup-buildx-action 照原樣使用。** 它的 builder 從你的儲存庫上一次建置留在機器上的層開始，`cache-from` 和 `cache-to` 也可以拿掉。我們自己在一台 4 vCPU 的機器上執行了一個公開專案的 CI（2026 年 11 月 19 日，各執行一次）：建置映像檔的步驟第一次花了 177 秒，重新執行花了 4 秒，31 個步驟為 CACHED。
- **磁碟：** 在作業之後磁碟快滿之前，什麼都不會被刪除。快滿時會先刪除 dangling 映像檔，再刪除最久沒用的建置快取。

```yaml
jobs:
  build:
    runs-on: skipbox # was ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v4
      - uses: docker/build-push-action@v7
        with:
          context: .
          tags: app:ci
          load: true
```

作業依標籤選擇規格：

| 標籤 | 機器 | 磁碟 | 方案 |
|---|---|---|---|
| `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 |

分鐘數不限。4 vCPU 每月 20,000 分鐘，GitHub 收 $222；Skipbox S 是 $39，少了 $183。

## 換過去只要改一行

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

第一個作業會建置每一層。第二個作業就會在機器上找到它們。

## 安全性

- 機器只屬於你的帳號。其他公司的作業不會在上面執行。
- 每個作業結束後，Runner 的憑證、程序和容器都會被清除，`~/.docker/config.json` 也是，所以 registry 的登入資訊不會延續到下一個作業。開啟「每個作業都用新 VM」，每個作業就會改用一台全新的機器。
- 沒有寫入權限的人提交的程式碼（例如來自 fork 的 Pull Request），會在全新、用完即丟的機器上執行，絕不會在你的機器上。

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

## 用你的 Docker 建置試試看

試用免費，為期 7 天或 3,000 作業分鐘，以先到者為準，不需信用卡。把你的 Docker 建置改成 `runs-on: skipbox`，執行兩次，再把第二次執行的建置步驟和 GitHub 上的並排比較。

## 常見問題

### 為什麼每次 GitHub Actions 執行都會失去 Docker 層快取？

因為 GitHub 託管 Runner 上的每個作業都從一台新的 VM 開始，沒有建置快取，也沒有上一次執行的映像檔。docker/setup-buildx-action 讓情況更明顯：它預設會建立一個 docker-container builder，一開始是空的，作業結束時就被移除。所以除非你用 cache-to 匯出快取、用 cache-from 匯入，或是在保留 Docker 建置快取的機器上執行，否則每一層都要重建。

### 在 GitHub Actions 上怎麼快取 Docker 層？

在 GitHub 託管 Runner 上，用 buildx 的快取匯出器：在 docker/build-push-action 中設定 cache-from: type=gha 和 cache-to: type=gha,mode=max，會把層存在 GitHub 的 Actions 快取裡（每個儲存庫 10 GB，和其他所有快取共用）。type=registry 把它們存成 registry 裡的一個獨立映像檔，type=local 則存在你用 actions/cache 儲存的目錄裡。用 type=gha 時，請給每個映像檔自己的 scope，因為預設的 scope 每次建置都會被覆寫。在保留磁碟的機器上，docker build 不用任何匯出器就會重複使用層。

### 為什麼用了 cache-to type=gha 的 buildx 還是很慢？

因為層還是要傳輸。用 mode=max 時，每次執行都會上傳每個 stage 的每個新層，之後的執行再下載它需要的層。這個快取和其他所有東西共用 GitHub 每個儲存庫 10 GB 的額度，所以會被移除，而 GitHub 的快取 API 也會對請求太多的建置限流。磁碟上已經有層的 builder，兩個方向都能跳過。

### 怎麼讓 docker compose 不要每個作業都拉同樣的映像檔？

在 GitHub 託管 Runner 上做不到，只能把下載移到別處：用 docker save 把映像檔存成 tar 檔，用 actions/cache 快取，再在下一個作業 docker load。這算進同樣的 10 GB，而且每次執行都是一次下載加一次載入。在保留磁碟的機器上，compose 上次拉取的映像檔已經在那裡，docker compose pull 只會抓取有變動的層。

### 要在 Skipbox 上保留 Docker 的快取，需要修改工作流程嗎？

只要改 runs-on：你的專屬機器在作業之間保留 Docker 的映像檔、層和建置快取。docker build 和 docker compose build 會重複使用它們，docker/setup-buildx-action 也照原樣使用：它的 builder 從你的儲存庫上一次建置留在機器上的層開始。cache-from 和 cache-to 可以拿掉。

### 試用要花多少錢？

不用錢。試用為期 7 天或 3,000 作業分鐘，以先到者為準，不需信用卡。把你的 Docker 建置改成 runs-on: skipbox，執行兩次，再把第二次執行的建置步驟和 GitHub 上的比較。

更新於 2026-11-19 · https://skipbox.dev/zh-hant/guides/docker-layer-cache-github-actions
