GitHub Actions 缓存大小上限:缓存为什么被清除、恢复慢或未命中
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 的缓存规则
根据 GitHub 的依赖缓存参考文档、Actions 计费,以及关于超出 10 GB 的缓存的更新日志:
| 规则 | 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 把这叫做缓存抖动。
想看看是什么把它占满了,按大小列出条目:
gh cache list --sort size_in_bytes --limit 20
仓库的 Actions › Caches 页面也显示同样的内容,还有每个条目的分支和最后使用时间。
恢复为什么慢
在 GitHub 托管的运行器上,缓存命中就是往一台新虚拟机上下载,再解压。耗时随归档增长,所以一个长到好几 GB 的缓存,花的时间可能和它本想省掉的安装一样长。下载卡住时,会被 actions/cache 的分段超时切断,默认 10 分钟(SEGMENT_DOWNLOAD_TIMEOUT_MINS)。
大多数配置恢复的东西也比人们以为的少。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 中,差别一目了然,数据来自我们用这些项目自己的作业跑出的结果:
- 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 层缓存)。 - **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。
切换只需改一行
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
- 使用 GitHub 登录 Skipbox。
- 安装 Skipbox GitHub 应用,并选择仓库。
- 修改
runs-on并推送。
缓存步骤保持原样即可。第二次运行就会在机器上找到第一次运行的缓存。
安全
- 这台机器只属于你的账号。不会运行其他公司的作业。
- 每个作业结束后,运行器的凭据、进程和容器都会被清除。开启“每个作业用新虚拟机”后,每个作业改在一台新机器上运行。
- 没有写入权限的人提交的代码(例如来自复刻的拉取请求)在一台新的虚拟机上运行,它能读取你的缓存,但不能修改。
详情见作业如何隔离。
用缓存未命中的作业试试
试用免费,为期 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日