GitHub Actions 怎样缓存 Go 模块

GitHub Actions 的托管 runner 每次作业都可能从干净环境开始，如果 Go 依赖没有缓存，go mod download 会重复访问网络。最省事的做法是把缓存交给 actions/setup-go：在工作流中加入 cache: true，它会依据仓库里的 go.sum 参与缓存 key 计算。依赖文件没变时复用缓存，依赖变化时自动生成新的缓存范围。

官方地址：https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows

下面用一个最小的 Go CI 工作流说明完整操作。这里的界面图片都是原创的操作示意图，不是 GitHub 页面截图，也不是实际运行证据。

一、先找到需要修改的工作流

进入仓库后，按“Actions → 选择一个工作流 → workflow 文件”找到对应的 YAML 文件；也可以直接在仓库文件树打开 .github/workflows/ci.yml。先确认工作流里已经有 actions/checkout 和 actions/setup-go，缓存设置应放在 setup-go 这一步的 with 区域。

看到 setup-go 后再继续，不要把缓存配置写到 checkout，或者把 cache 错放到 job 顶层。前者不会改变 Go 模块缓存，后者会让 YAML 结构不符合动作的输入格式。

二、在 setup-go 中打开模块缓存

在 actions/setup-go 的 with 下加入 cache: true。例如：

name: Go CI

on:
  push:
    branches: [main] # 只示例主分支推送，按项目需要调整触发条件
  pull_request: # 拉取请求也可以复用依赖缓存

jobs:
  test:
    runs-on: ubuntu-latest # 使用 GitHub 托管 runner 执行测试
    steps:
      - name: Checkout
        uses: actions/checkout@v4 # 先取出包含 go.mod、go.sum 的仓库

      - name: Set up Go
        uses: actions/setup-go@v5 # setup-go 会准备 Go 并处理依赖缓存
        with:
          go-version-file: go.mod # 从 go.mod 读取项目要求的 Go 版本
          cache: true # 按 go.sum 计算缓存依据，命中时恢复模块缓存

      - name: Test
        run: go test ./... # 缓存未命中时仍会正常下载依赖并执行测试

保存后，点击工作流编辑器右上角的 Commit changes，或者按团队流程提交这次 YAML 修改。成功保存的标志是文件仍位于 .github/workflows/，缩进层级没有把 with 和 steps 打平。

三、运行一次并读懂缓存状态

提交工作流后进入“Actions → 对应工作流 → 最新运行 → test job”。第一次运行通常没有现成缓存，setup-go 会继续完成依赖准备；这不代表配置失败。后续运行时，如果 go.sum 没有变化，日志会显示缓存恢复相关提示，然后继续执行 go test ./...。

可以按下面的顺序判断：

• 首次运行：没有命中很正常，作业仍应能下载依赖并结束。
• 依赖未变：通常复用已有缓存，减少重复下载。
• go.sum 变化：缓存依据随依赖文件变化，新的依赖集合会使用新的缓存范围。

缓存只是加速手段，不能替代依赖声明。即使命中失败，也要保证工作流可以重新下载依赖并继续构建。

四、什么时候才需要 actions/cache

如果只是缓存 Go 模块，优先使用 setup-go 的内置能力；只有需要自定义多个路径、拆分恢复与保存动作，或要控制更细的 key 时，才考虑显式使用 actions/cache。手动配置的关键是让 key 关联 go.sum，并把 restore key 设计得足够保守：

      - name: Cache Go modules manually
        uses: actions/cache@v4 # 只有需要自定义缓存路径时再使用这一层
        with:
          path: ~/go/pkg/mod # 缓存 Go 模块下载目录，不放 secrets 或构建凭据
          key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }} # 依赖清单变化就换 key
          restore-keys: |
            ${{ runner.os }}-go- # 允许恢复同平台的近似旧缓存，再由 Go 补齐依赖

不要同时为同一个模块目录启用 setup-go 内置缓存和手动缓存，否则排查命中结果会变复杂。还要避免把 token、密钥或未经信任的构建产物放进缓存；缓存内容会被后续有权限读取该范围的工作流直接恢复。

常见问题

为什么第一次运行没有缓存命中？

第一次没有可恢复的缓存是正常情况。只要测试继续执行，后续运行就有机会使用本次生成的缓存。

修改 go.mod 后要手动删除缓存吗？

通常不需要。setup-go 会使用 go.sum 参与缓存依据；依赖集合变化后，新的 key 会让工作流建立新的缓存范围。

为什么我用了 cache: true 但速度没有明显变化？

先区分依赖下载是否是主要耗时，再看 Actions 日志中的缓存恢复提示。编译、测试、Docker 构建或 runner 排队时间占比很高时，单独缓存 Go 模块不会解决其它阶段的耗时。

总结

GitHub Actions 缓存 Go 模块的最小改动是：在 actions/setup-go 的 with 中加入 cache: true，并让 go.sum 继续作为依赖变化依据。先用内置缓存完成常规 CI，再根据路径和权限需求决定是否使用 actions/cache，这样配置更短，失败时也保留了重新下载依赖的退路。