# GitHub Actions 中的 Docker 层缓存：为什么每次构建都是冷启动，怎样把层留下来

> 每个 GitHub Actions 作业都在一台新虚拟机上启动，没有 Docker 构建缓存，也没有拉取过的镜像，setup-buildx-action 默认的构建器也从空白开始。buildx 的 cache-to 和 cache-from（gha、registry、local）是靠下载把层找回来，还得挤在 GitHub 的 10 GB 里。一个把 Docker 构建缓存留在磁盘上的运行器，这些都不需要，每月固定 $39。

每次 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：每个作业一台新虚拟机，所以每次运行都没有层、没有镜像，buildx 构建器也是空的
- Skipbox：Docker 的构建缓存和镜像留在你机器的磁盘上，没变的层既不重新构建也不重新下载
- 4 vCPU 每月 2万分钟：GitHub 上 $222，Skipbox 上 $39

**固定价格的 GitHub Actions，分钟数不限** Skipbox 在你的专属机器上运行 GitHub Actions 作业：每月 $39，无论运行多少分钟。Docker 层和依赖缓存在作业之间保留，所以下一个作业能立即开始。

4 vCPU 运行器，每月 2万分钟: GitHub $222 → Skipbox $39. 每月节省 $183.

切换只需改一行：`runs-on: skipbox`。

[开始 7 天免费试用](https://app.skipbox.dev/sign-in?ref=g-docker-layer-cache-github-actions-zh-hans)

## 为什么每次构建都是冷启动

- **每个作业一台新虚拟机**：GitHub 的[运行器参考文档](https://docs.github.com/en/actions/reference/runners/github-hosted-runners)说，每个 GitHub 托管的运行器都是一台由 GitHub 托管的新虚拟机（VM）。上一个作业构建或拉取的东西都不在上面。
- **一个空的构建器**：[docker/setup-buildx-action](https://github.com/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 的[缓存后端](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` | 你镜像仓库中的一个单独的缓存镜像 | 从镜像仓库拉取缓存，再推送新的 | 需要有推送权限的镜像仓库登录；还有镜像仓库的存储和流量 |
| `type=inline` | 镜像本身里面 | 拉取镜像来读取它的缓存 | 只支持 `mode=min`：中间阶段的层不会保留 |
| `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/)，让最少变化的层排在前面：先复制锁文件并安装依赖，再复制源代码。否则每次提交都会让安装那一层失效，任何缓存都救不回来。

默认的 `mode=min` 只保留最终镜像的层。`mode=max` 保留每个阶段的层，所以多阶段构建命中更多，上传也更多。

一个典型的 `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
```

**缓存挂载留不下来**：`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 和几个服务的集成测试，因为虚拟机是新的，每个作业都要拉取所有镜像。在 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。
- **磁盘**：作业结束后磁盘快满时才会删除东西。先删悬空镜像，再删最久未用的构建缓存。

```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 上每月 2万分钟，GitHub 收 $222；Skipbox S 是 $39，少花 $183。

## 切换只需改一行

1. 使用 GitHub 登录 Skipbox。
2. 安装 Skipbox GitHub 应用，并选择仓库。
3. 修改 `runs-on` 并推送。

第一个作业构建每一层。第二个作业就在机器上找到它们。

## 安全

- 这台机器只属于你的账号。不会运行其他公司的作业。
- 每个作业结束后，运行器的凭据、进程和容器都会被清除，`~/.docker/config.json` 也一样，所以镜像仓库的登录不会带到下一个作业。开启“每个作业用新虚拟机”后，每个作业改在一台新机器上运行。
- 没有写入权限的人提交的代码（例如来自复刻的拉取请求）在一台新的一次性机器上运行，从不在你的机器上运行。

详情见[作业如何隔离](https://docs.skipbox.dev/zh-hans/isolation)。

## 用你的 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 · https://skipbox.dev/zh-hans/guides/docker-layer-cache-github-actions
