Skipbox

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 的缓存的更新日志:

缓存为什么被清除

一个 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 倍。作业按标签选择规格:

私有仓库的 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
  1. 使用 GitHub 登录 Skipbox。
  2. 安装 Skipbox GitHub 应用,并选择仓库。
  3. 修改 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日

缓存始终预热,CI/CD 更快

固定价格的预热运行器

机器由 Skipbox 托管。你只需改一行。满负荷使用时,费用是 GitHub 的 1/12。价格固定,全天运行也不加钱。缓存空间是 GitHub 的 7 倍。

  • 无需绑卡
  • 使用 GitHub 登录
  • 随时取消