开发工具 Actions 缓存 Go 模块 怎样处理

在持续集成里，Go 项目每次执行 go mod download 都重新访问依赖源，构建时间就会被网络和模块数量拖长。开发工具 Actions 的处理思路是把模块缓存交给 actions/setup-go 管理：单模块仓库通常使用根目录的 go.mod 或 go.sum，多模块仓库则明确写出依赖文件路径。

本文只解决 Actions 缓存 Go 模块这一件事。官方 Go 工作流地址：https://docs.github.com/en/actions/tutorials/build-and-test-code/go；setup-go 的官方地址：https://github.com/actions/setup-go。下面的界面图都是原创静态说明图，不是 GitHub 页面截图，也不是实际运行证据。

最小配置是：在 actions/setup-go 中保持 cache: true，再用 cache-dependency-path 指向真正会改变依赖的 go.sum。缓存未命中只表示需要重新填充缓存，不等于构建失败。

先准备模块文件和工作流入口

先看仓库结构。如果只有一个根模块，通常能看到 go.mod 和 go.sum；如果是 monorepo，可能存在 service/go.sum、tools/go.sum 等多份文件。缓存键必须能随着这些依赖文件变化，否则依赖更新后仍可能恢复旧缓存。

打开仓库的 .github/workflows，找到负责测试或构建的 YAML 文件，再定位 actions/setup-go 步骤。建议先把 Go 版本写成项目明确支持的版本，缓存问题和版本下载问题分开处理，排查会更容易。

从 setup-go 步骤打开 Go 模块缓存

setup-go 已提供 Go 模块和构建缓存的简化入口。单模块项目可以这样写；示例中的注释说明每个字段的作用，配置本身仍是有效的 YAML。

steps:
  # 先把仓库内容放到 runner，setup-go 才能读取依赖文件
  - uses: actions/checkout@v4

  # setup-go 默认开启缓存；显式写出路径便于团队维护
  - name: Set up Go
    uses: actions/setup-go@v7
    with:
      go-version: '1.25'
      cache: true
      # go.sum 变化时，缓存键随依赖清单变化
      cache-dependency-path: go.sum

  # 缓存恢复后再下载缺少的模块，并继续测试
  - name: Download modules
    run: go mod download
  - name: Test
    run: go test ./...

关键点有两个：checkout 要先于 setup-go，否则工作区里还没有可供计算的依赖文件；cache-dependency-path 要指向实际存在且能反映依赖变化的文件。不要把一个不存在的示例路径直接复制进生产工作流。

多模块仓库怎样填写依赖路径

如果一个仓库里有多个 Go 模块，可以使用 glob 覆盖它们：

- name: Set up Go for a multi-module repository
  uses: actions/setup-go@v7
  with:
    go-version: '1.25'
    cache: true
    # 让每个模块的 go.sum 都参与缓存键计算
    cache-dependency-path: '**/go.sum'

也可以把路径逐行列出，适合模块边界固定、希望配置更直观的仓库：

cache-dependency-path: |
  # 核心服务的依赖清单
  service/go.sum
  # 工具模块的依赖清单
  tools/go.sum

如果工作流还按不同 GOOS 或 GOARCH 构建，可以把记录目标平台的文件也纳入依赖路径，让不同目标使用不同缓存。不要为了“让缓存更勤快地失效”把所有源码文件都加入，频繁产生新缓存会增加存储和传输开销。

在运行结果中核对缓存是否命中

配置提交后，先看 setup-go 步骤是否完成，再看它暴露的 cache-hit 输出。为了让状态更容易读，可以把输出写入环境变量：

- name: Set up Go
  id: setup-go
  uses: actions/setup-go@v7
  with:
    go-version: '1.25'
    cache: true
    cache-dependency-path: go.sum

- name: Show cache status
  run: |
    # 输出 setup-go 的命中状态，便于在运行摘要中排查
    echo "Go cache hit: ${{ steps.setup-go.outputs.cache-hit }}"
    # 输出模块缓存位置，不把它误认为仓库目录
    echo "Module cache: ${{ steps.setup-go.outputs.GOMODCACHE }}"

- name: Download modules
  run: |
    # 命中时补齐缺失模块，未命中时填充新的缓存内容
    go mod download

可以按三项检查：第一，cache-hit 是否为 true；第二，GOMODCACHE 是否指向 Go 的模块缓存目录；第三，后续下载和构建步骤是否正常结束。第一次运行没有命中是正常的，通常要等一次成功工作流把缓存填好。

缓存不命中时按配置层排查

1. 检查路径：确认 cache-dependency-path 与仓库真实目录一致，glob 能覆盖所有模块，并且 checkout 已经完成。
2. 检查缓存键变化：依赖变更后，命中旧缓存并不一定是错误；setup-go 会根据依赖文件和运行环境寻找可用缓存，缺少内容时仍会下载。
3. 检查环境边界：操作系统、架构和 Go 版本不同，缓存不应被当成完全相同的构建产物；矩阵任务要避免用同一个自定义键混用它们。
4. 检查权限与分支：工作流需要有读取仓库内容的权限；拉取请求可访问的缓存范围受 Actions 的分支隔离规则约束。

如果只是缓存未命中但 go mod download 和测试成功，先把它看成性能问题处理，不要把工作流改成失败。只有当下载、校验或构建本身报错时，才继续查看依赖源、校验和以及 Go 版本。

速查表

相关问题

为什么写了 cache 还是每次下载模块？

先区分“缓存恢复”和“下载缺失模块”。缓存可能只恢复了部分内容，go mod download 仍会补齐缺少的模块；如果每次都是完整 miss，再检查依赖路径、Go 版本、操作系统和分支访问边界。

单模块项目应该写 go.mod 还是 go.sum？

以项目实际依赖文件为准。若希望依赖清单变化直接影响缓存键，可以显式指定 go.sum；多模块项目则应覆盖所有模块的依赖文件。

能不能用 actions/cache 自己缓存 GOMODCACHE？

可以，但要自己维护缓存路径、键、恢复键和跨平台差异。只是缓存 Go 模块时，优先使用 setup-go 的内置能力，配置面更小，只有需要特殊共享策略时再改用独立缓存步骤。