GitHub Actions 的 Docker 層快取:為什麼每次建置都從冷啟動開始,以及怎麼保留層
每次 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,分鐘數不限。
為什麼每次建置都從冷啟動開始
- 每個作業一台新的 VM。 GitHub 的 Runner 參考文件說,每個 GitHub 託管 Runner 都是一台由 GitHub 託管的新虛擬機器(VM)。上一個作業建置或拉取的東西都不在上面。
- 一個空的 builder。 docker/setup-buildx-action 預設會以
docker-containerdriver 建立並啟動一個 builder,而它的cleanup(預設開啟)會在作業結束時移除這個 builder。 - 14 GB 的磁碟。 私有儲存庫的
ubuntu-latest只有 2 顆 CPU、8 GB 和 14 GB 的 SSD。一個大型映像檔、它的建置快取,再加上一個要解開的快取封存檔,就可能把空間用完(「no space left on device」)。
buildx 的快取後端,以及各自的代價
依 Docker 的快取後端和用 GitHub Actions 管理快取:
| 後端 | 層存在哪裡 | 每次執行要付出什麼 | 限制 |
|---|---|---|---|
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(Buildx 0.35.0 以上),否則每次執行都會變大;算進 10 GB |
不論選哪個後端,都要安排好 Dockerfile 的順序,讓最少變動的層放在最前面:先複製 lockfile 並安裝相依套件,再複製原始碼。否則每個 commit 都會讓安裝那一層失效,什麼快取都救不回來。
mode=min 是預設值,只保留最終映像檔的層。mode=max 保留每個 stage 的層,所以多階段建置的命中更多,上傳的也更多。
典型的 type=gha 設定,每個映像檔有自己的 scope:
- 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,用來把它搬進搬出 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 映像檔,再刪除最久沒用的建置快取。
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。
換過去只要改一行
- 使用 GitHub 登入 Skipbox。
- 安裝 Skipbox GitHub App,並選擇儲存庫。
- 修改
runs-on並推送。
第一個作業會建置每一層。第二個作業就會在機器上找到它們。
安全性
- 機器只屬於你的帳號。其他公司的作業不會在上面執行。
- 每個作業結束後,Runner 的憑證、程序和容器都會被清除,
~/.docker/config.json也是,所以 registry 的登入資訊不會延續到下一個作業。開啟「每個作業都用新 VM」,每個作業就會改用一台全新的機器。 - 沒有寫入權限的人提交的程式碼(例如來自 fork 的 Pull Request),會在全新、用完即丟的機器上執行,絕不會在你的機器上。
詳情請見作業如何隔離。
用你的 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日