# GitHub Actions 缓存大小上限：缓存为什么被清除、恢复慢或未命中

> GitHub 的 Actions 缓存每个仓库 10 GB，超出后删除最久未读取的条目，7 天未使用的条目也会被删除。即使命中，也是往一台新虚拟机上下载。本文讲每种解决办法的代价，以及为什么一个保留磁盘的运行器让大部分缓存都不再需要，每月固定 $39。

GitHub Actions 给每个仓库 10 GB 缓存。仓库超出之后，GitHub 仍然保存新条目，并删除最久未读取的条目，直到回到上限以下；7 天内没有作业读取过的条目也会被删除。一个分支只能读自己的缓存和默认分支的缓存，所以新分支的第一次运行常常不命中。而且命中也还是一次下载：GitHub 托管运行器上的每个作业都在一台新虚拟机上启动，所以要再次下载并解压归档。你可以提高上限，超出 10 GB 的部分每 GB 每月 $0.07，也可以调整缓存键，但下载依然在。

Skipbox 去掉了下载。你的作业在你账号的专属机器上运行，机器在作业之间一直保留，所以 npm、pnpm、Gradle、Go 和 Cargo 的缓存以及 Docker 的层，上一个作业结束后仍在它的磁盘上（S 为 80 GB，而 GitHub 的运行器只有 14 GB）。actions/cache 保存的东西就放在机器旁边，所以恢复只是一次本地读取。只改一行 `runs-on: skipbox`，每月固定 $39，分钟数不限。

- GitHub：每个仓库 10 GB，7 天未使用的条目被删除，每次命中都要重新下载
- Skipbox：包缓存和 Docker 的层留在你机器的磁盘上，缓存空间至少是 GitHub 的 7 倍
- 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-github-actions-cache-size-limit-zh-hans)

## 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/)的更新日志：

| 规则 | GitHub 怎么做 |
|---|---|
| 大小 | 默认每个仓库 10 GB，所有分支和工作流共用 |
| 超出大小 | 保存新条目，然后按最后访问时间从最旧的开始删除条目，直到仓库回到上限以下。每小时清理一次 |
| 未使用的条目 | 删除超过 7 天未读取的条目 |
| 更大的上限 | 在 Pro、Team 或 Enterprise 账号上，管理员可以提高大小和天数。超出 10 GB 的部分每 GB 每月 $0.07，按每小时的峰值计算。达到预算后，缓存变为只读，直到下一个计费周期 |
| 分支 | 一次运行从自己的分支和默认分支恢复缓存；拉取请求的运行还可以从它的基础分支恢复。从不读取同级或子分支 |
| 拉取请求 | 拉取请求的缓存限定在它的合并 ref 上：只有这个拉取请求的重新运行能读取 |
| 条目 | 不能修改。已经存在的键不会再次保存 |
| 命中 | 只有 `key` 完全匹配时 `cache-hit` 才为 `true`；`restore-keys` 匹配时为 `false` |
| 速率 | 每个仓库每分钟最多 200 次上传、1,500 次下载 |

## 缓存为什么被清除

一个 10 GB 装着仓库保存的一切。每个分支、每个拉取请求都保存自己的条目。三个 Node 版本乘以两个操作系统的矩阵，就保存六个。Docker 的 `type=gha` 构建缓存也落在同一个 10 GB 里。一天保存的量加起来超过上限时，每次新的保存都会删掉一个更旧的条目，常常正是下一个作业需要的那个。GitHub 把这叫做缓存抖动。

想看看是什么把它占满了，按大小列出条目：

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

仓库的 Actions › Caches 页面也显示同样的内容，还有每个条目的分支和最后使用时间。

## 恢复为什么慢

在 GitHub 托管的运行器上，缓存命中就是往一台新虚拟机上下载，再解压。耗时随归档增长，所以一个长到好几 GB 的缓存，花的时间可能和它本想省掉的安装一样长。下载卡住时，会被 actions/cache 的分段超时切断，默认 10 分钟（`SEGMENT_DOWNLOAD_TIMEOUT_MINS`）。

大多数配置恢复的东西也比人们以为的少。[setup-node](https://github.com/actions/setup-node) 的 `cache:` 输入保存的是包管理器的下载缓存，而不是 `node_modules`：恢复之后，`npm ci` 还是要把每个包都安装一遍。setup-python 的 pip 缓存也一样：下载的文件回来了，环境还得重新安装。

## 缓存为什么未命中

- **键变了**：用 `hashFiles('**/package-lock.json')` 做键，锁文件每次变化都会未命中。`restore-keys` 能做部分匹配，但这时 `cache-hit` 读出来是 `false`。
- **新分支**：它能读默认分支的缓存，读不到其他功能分支的。如果默认分支从没运行过这个工作流，就没什么可读。
- **被清除了**：上限或 7 天把它带走了。
- **从没保存过**：条目不能修改，所以已经存在的键永远不会再次保存，缓存的内容一直停留在第一次保存时的样子。来自复刻的拉取请求可能根本不允许保存。

**把文件传给同一次运行中的下一个作业**，用的是另一个工具。缓存是给下一次运行用的；同一个工作流中后面的作业需要的构建输出，要通过 `actions/upload-artifact` 和 `actions/download-artifact` 传递。Artifact 有自己的存储，不占那 10 GB，但同样是往一台新虚拟机上下载。

## 每种解决办法在 GitHub 运行器上的代价

- **提高上限**：清除变少了，代价是超出 10 GB 的部分每 GB 每月 $0.07（GitHub 自己的例子：用满 200 GB 是每月 $13.30），而且需要 Pro、Team 或 Enterprise 账号。恢复依然是下载，缓存越大下载越久。
- **少存一点**：缓存 `~/.npm` 或 pnpm store，而不是 `node_modules` 或构建输出。只在默认分支上保存，每个作业用 `actions/cache/restore`，只在一个作业里用 `actions/cache/save`。这要花你的时间，而缓存越小，恢复的也越少。
- **修好缓存键**：以锁文件为键，加上 `restore-keys`，并在推送到默认分支时运行工作流，让新分支有东西可读。
- **一个保留磁盘的自托管运行器**：没有下载，也没有 10 GB 的限制。但机器要你自己运维：更新操作系统、在作业之间清理又不能删掉缓存、坏了还要修。

## 解决办法是一台保留磁盘的机器

缓存之所以存在，是因为机器会忘记。GitHub 托管的运行器每个作业都是一台新虚拟机，所以作业把状态存到 GitHub 的存储里，下次再取回来。在一台一直保留的机器上，这些状态早就在它的磁盘上：包管理器的缓存、工具缓存、Docker 的镜像和构建缓存，甚至构建输出。

在真实项目的 CI 中，差别一目了然，数据来自[我们用这些项目自己的作业跑出的结果](https://skipbox.dev/zh-hans/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-hans/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 上每月 2万分钟，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 应用，并选择仓库。
3. 修改 `runs-on` 并推送。

缓存步骤保持原样即可。第二次运行就会在机器上找到第一次运行的缓存。

## 安全

- 这台机器只属于你的账号。不会运行其他公司的作业。
- 每个作业结束后，运行器的凭据、进程和容器都会被清除。开启“每个作业用新虚拟机”后，每个作业改在一台新机器上运行。
- 没有写入权限的人提交的代码（例如来自复刻的拉取请求）在一台新的虚拟机上运行，它能读取你的缓存，但不能修改。

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

## 用缓存未命中的作业试试

试用免费，为期 7 天 或 3,000 作业分钟，以先到者为准，无需绑卡。把那个作业改为 `runs-on: skipbox`，运行两次，再把第二次运行的恢复和安装步骤与 GitHub 上的并排对比。

## 常见问题

### GitHub Actions 的缓存大小上限是多少？

默认每个仓库 10 GB，所有分支和工作流合计。超出后，GitHub 仍然保存新条目，并按最后访问时间从最旧的开始删除条目，直到仓库回到上限以下。7 天内没有作业读取过的条目，不管大小都会被删除。在 Pro、Team 或 Enterprise 账号上，管理员可以提高上限和天数；超出 10 GB 的存储按每 GB 每月 $0.07 计费，以每小时的峰值计量，一旦达到预算，缓存就变为只读，直到下一个计费周期。

### 为什么我的 GitHub Actions 缓存总是被清除？

因为仓库里的一切共用这 10 GB：每个分支、每个拉取请求、每个矩阵作业、每个操作系统都保存自己的条目，Docker 的 type=gha 缓存也落在同一个地方。一天保存的量加起来超过上限时，每次保存都会删掉一个更旧的条目，下一个作业就找不到它需要的那个。GitHub 把这叫做缓存抖动（cache thrashing）。按大小列出条目（gh cache list --sort size_in_bytes），看看是什么把它占满了。

### 为什么恢复缓存和从头安装花的时间一样长？

因为命中也还是一次下载。GitHub 托管运行器上的每个作业都在一台新虚拟机上启动，所以 actions/cache 每次都要下载并解压归档，缓存越大，耗时越长。setup-node 的缓存恢复的是包管理器的下载缓存，而不是 node_modules，所以恢复之后 npm ci 还是要把每个包都安装一遍。在一个保留磁盘的运行器上，缓存早就在那里，什么都不用下载。

### 为什么 actions/cache 在新分支上不命中？

一次运行可以从自己的分支和默认分支恢复缓存，拉取请求的运行还可以从它的基础分支恢复。它读不到同级分支的缓存。所以一个功能分支的第一次运行，只有在默认分支保存过那个键时才会命中。让工作流在推送到默认分支时运行，这样它会保存；再加上 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-hans/guides/github-actions-cache-size-limit
