GitHub Actions 中的 Docker 层缓存:为什么每次构建都是冷启动,怎样把层留下来
每次 GitHub Actions 运行都会丢失 Docker 的层缓存,因为 GitHub 托管运行器上的每个作业都在一台新虚拟机上启动:没有构建缓存,没有拉取过的镜像。docker/setup-buildx-action 默认的构建器(docker-container)也在每个作业中从空白开始,作业结束时被删除。常见的解决办法是用 buildx 导出缓存。cache-to: type=gha,mode=max 和 cache-from: type=gha 把层存在 GitHub 的 Actions 缓存中,每个仓库 10 GB,和其他所有缓存共用;type=registry 存在你的镜像仓库中;type=local 存在一个用 actions/cache 保存的目录中。每一种都把重新构建变成了每次运行的一次上传和一次下载。
Skipbox 把层留在构建运行的地方。你的作业在你账号的专属机器上运行,它在作业之间保留 Docker 的镜像、层和构建缓存,S 的磁盘为 80 GB,而 GitHub 的运行器只有 14 GB。docker build 和 docker compose build 复用上一次构建的层,compose 拉取过的镜像已经在磁盘上。setup-buildx-action 照原样使用,它的构建器同样能找到这些层。只改一行 runs-on: skipbox,每月固定 $39,分钟数不限。
为什么每次构建都是冷启动
- 每个作业一台新虚拟机:GitHub 的运行器参考文档说,每个 GitHub 托管的运行器都是一台由 GitHub 托管的新虚拟机(VM)。上一个作业构建或拉取的东西都不在上面。
- 一个空的构建器:docker/setup-buildx-action 默认用
docker-container驱动创建并启动一个构建器,它的cleanup(默认开启)会在作业结束时删除这个构建器。 - 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 | 你镜像仓库中的一个单独的缓存镜像 | 从镜像仓库拉取缓存,再推送新的 | 需要有推送权限的镜像仓库登录;还有镜像仓库的存储和流量 |
type=inline | 镜像本身里面 | 拉取镜像来读取它的缓存 | 只支持 mode=min:中间阶段的层不会保留 |
type=local + actions/cache | 一个用 actions/cache 保存的目录 | 下载并解压整个目录,然后再上传 | 不设 reset=true(Buildx 0.35.0 及以后)就会随每次运行增长;计入 10 GB |
不管选哪个后端,都要调整 Dockerfile 的顺序,让最少变化的层排在前面:先复制锁文件并安装依赖,再复制源代码。否则每次提交都会让安装那一层失效,任何缓存都救不回来。
默认的 mode=min 只保留最终镜像的层。mode=max 保留每个阶段的层,所以多阶段构建命中更多,上传也更多。
一个典型的 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
缓存挂载留不下来:RUN --mount=type=cache(构建内部包管理器的缓存)默认不会保存在 GitHub Actions 缓存中;Docker 的文档推荐用 buildkit-cache-dance 把它搬进搬出 actions/cache,每次运行又多一次下载和上传。
docker compose 每个作业都拉取所有镜像
用 docker compose up 启动 Postgres、Redis 和几个服务的集成测试,因为虚拟机是新的,每个作业都要拉取所有镜像。在 GitHub 托管的运行器上,办法都只是把下载换个地方:
- 用
docker save把镜像存成 tar 文件,用 actions/cache 缓存,在下一个作业里docker load。它计入 10 GB,载入本身也要花时间。 - 用 buildx 和上面的某个缓存后端构建服务镜像,基础镜像却仍然要拉取。
解决办法是一台保留 Docker 缓存的机器
上面的每个后端之所以存在,都是因为构建器会忘记。一个在作业之间保留下来的 Docker 守护进程,自己的磁盘上已经有上一次构建的层、它的缓存挂载和它拉取过的每一个镜像。没有东西要导出,没有东西要导入,也没有 10 GB 要和别人分。
Skipbox 把 Docker 的缓存留在你的机器上
每个套餐都附带你账号的专属机器,在作业之间一直保留:
docker build和docker compose build复用上一次构建的层,工作流不用改。- 镜像留在磁盘上:
docker compose up找到上次拉取的镜像;docker compose pull只获取有变化的层。 - 缓存挂载也保留下来,和 Docker 的构建缓存在一起,所以
RUN --mount=type=cache不用任何额外步骤就能保住包管理器的缓存。 - docker/setup-buildx-action 照原样使用:它的构建器从你的仓库上一次构建留在机器上的层开始,
cache-from和cache-to也可以删掉。我们自己在一台 4 vCPU 的机器上运行了一个公开项目的 CI(2026 年 11 月 19 日,各运行一次):构建镜像的步骤第一次用了 177 秒,重新运行用了 4 秒,31 个步骤为 CACHED。 - 磁盘:作业结束后磁盘快满时才会删除东西。先删悬空镜像,再删最久未用的构建缓存。
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 上每月 2万分钟,GitHub 收 $222;Skipbox S 是 $39,少花 $183。
切换只需改一行
- 使用 GitHub 登录 Skipbox。
- 安装 Skipbox GitHub 应用,并选择仓库。
- 修改
runs-on并推送。
第一个作业构建每一层。第二个作业就在机器上找到它们。
安全
- 这台机器只属于你的账号。不会运行其他公司的作业。
- 每个作业结束后,运行器的凭据、进程和容器都会被清除,
~/.docker/config.json也一样,所以镜像仓库的登录不会带到下一个作业。开启“每个作业用新虚拟机”后,每个作业改在一台新机器上运行。 - 没有写入权限的人提交的代码(例如来自复刻的拉取请求)在一台新的一次性机器上运行,从不在你的机器上运行。
详情见作业如何隔离。
用你的 Docker 构建试试
试用免费,为期 7 天 或 3,000 作业分钟,以先到者为准,无需绑卡。把你的 Docker 构建改为 runs-on: skipbox,运行两次,再把第二次运行的构建步骤与 GitHub 上的并排对比。
常见问题
为什么每次 GitHub Actions 运行,Docker 层缓存都会丢失?
因为 GitHub 托管运行器上的每个作业都在一台新虚拟机上启动,没有构建缓存,也没有上一次运行留下的镜像。docker/setup-buildx-action 让情况更甚:它默认创建一个 docker-container 构建器,从空白开始,作业结束时被删除。所以除非用 cache-to 导出缓存、用 cache-from 导入,或者在一台保留 Docker 构建缓存的机器上运行,否则每一层都要重新构建。
怎样在 GitHub Actions 中缓存 Docker 层?
在 GitHub 托管的运行器上,用 buildx 的缓存导出器:在 docker/build-push-action 中设置 cache-from: type=gha 和 cache-to: type=gha,mode=max,把层存进 GitHub 的 Actions 缓存(每个仓库 10 GB,和其他所有缓存共用)。type=registry 把它们作为一个单独的镜像存进你的镜像仓库,type=local 存进一个用 actions/cache 保存的目录。使用 type=gha 时给每个镜像单独的 scope,因为默认的 scope 会被每次构建覆盖。在一台保留磁盘的机器上,docker build 不用任何导出器就能复用层。
用了 buildx 和 cache-to type=gha,为什么还是慢?
因为层还是要来回搬运。用 mode=max 时,每次运行都要上传每个阶段的每个新层,之后的运行再下载它需要的层。这份缓存和其他所有东西共用 GitHub 每个仓库 10 GB 的额度,所以会被清除,而且请求太多时,GitHub 的缓存 API 会对构建限流。一个磁盘上已经有这些层的构建器,两个方向都省了。
怎样让 docker compose 不在每个作业里都拉取同样的镜像?
在 GitHub 托管的运行器上做不到,只能把下载换个地方:用 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 也照原样使用:它的构建器从你的仓库上一次构建留在机器上的层开始。cache-from 和 cache-to 可以删掉。
试用要花多少钱?
不花钱。试用为期 7 天 或 3,000 作业分钟,以先到者为准,无需绑卡。把你的 Docker 构建改为 runs-on: skipbox,运行两次,再把第二次运行的构建步骤与 GitHub 上的对比。
更新于 2026年11月19日