Go 项目 GitHub Actions 怎么设质量门禁：go vet、go test 与构建分阶段拦截

一个 Go 项目刚接入 GitHub Actions 时，最常见的配置只有两行：拉取代码，然后跑 go test ./...。它当然比什么都没有强，但 PR 失败后，维护者往往还得翻完一长串日志才能判断：是依赖没下载成功、静态检查没通过、测试执行失败，还是代码根本构建不出来。把这些判断逻辑拆分开，并不会让流水线变得臃肿；几个边界清晰的门禁反而能让问题停在最靠前、最容易修复的位置。

一次 PR 卡在 CI，先把失败位置变得可见

之前做代码评审的时候，有个提交只改了一个 handler 的错误分支逻辑。开发机上单独跑过这个包的测试，结果合并请求的 CI 一直显示失败。日志最前面混着模块下载、编译和测试的各类输出，真正的报错提示被埋在后面。把工作流拆成带独立名字的小阶段之后，页面直接就能看到“vet 失败”或者“build 失败”，评审人不用读完所有输出内容，就能直接判断该找谁处理。

这么做的目标不是让 CI 替代人工代码评审。它只是把每次提交必须满足的底线规则固定下来：依赖能正常解析、静态检查没有明显问题、测试能完整跑完、所有包都能正常构建。后续想要加集成测试、镜像构建或者发布流程，也能在这条基础链路之外继续扩展。

触发范围和权限先收紧，流水线才不会四处冒泡

质量门禁建议先覆盖主分支的推送动作和所有合并请求。只做代码检查的工作流不需要上传发布产物，也没必要拥有写仓库、写工单或者部署的权限。GitHub 工作流的权限一旦显式声明，没列出的权限都会被自动置为无权限；因此把 contents 保持为只读状态，比完全依赖仓库默认配置要清晰得多。

name: go-quality-gate

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-go@v6
        with:
          go-version-file: go.mod
          cache: true
      - name: download modules
        run: go mod download
      - name: vet
        run: go vet ./...
      - name: test
        run: go test ./...
      - name: build
        run: go build ./...

这份配置里故意不放部署密钥、镜像推送和自动发布逻辑。质量检查和发布是两类风险等级完全不同的工作：前者可以对每个 PR 反复运行，后者通常应该等版本标签生成、环境审批或者人工确认之后再触发。先别急着把所有动作都塞进同一个 job，能明确读懂失败原因的检查链，才是后续所有自动化能力的可靠地基。

go.mod 是版本事实，别在工作流里另写一套数字

团队里经常遇到版本漂移的问题：go.mod 里的 Go 版本已经升级，工作流里还硬写着旧版本；本地开发环境和 CI 环境的差异就会变成各种偶发失败。actions/setup-go 支持读取 go.mod、go.work 或者其他工具版本文件。单模块项目里，go-version-file: go.mod 已经足够直接明了；多模块仓库只要把对应文件的路径写清楚，就不用让缓存和版本解析都靠猜。

setup-go 的缓存默认是开启的，会围绕依赖文件生成缓存键。它能减少重复下载的耗时，但不能把缓存当成正确性的保证：修改了 go.sum、切换子模块或者遇到私有依赖访问问题的时候，还是要先核对版本文件和模块下载日志。缓存命中只会让流程更快，不代表依赖配置本身一定正确。

三个门禁各自拦什么，不要用一个失败结果代替全部判断

go test 并不是 go build 的替身。测试通常覆盖了大部分常用包，但带自定义构建标签的工具目录、只在特定平台编译的代码或者完全没有测试文件的包，仍可能在完整构建阶段暴露问题。反过来，构建通过也不代表边界行为没有出现回归。把两条命令都单独保留，成本很低，能拿到的排查信息却完整很多。

门禁失败后怎么处理：先复现同一条命令，再看上下游

CI 刚失败的时候不用急着在网页上反复点重跑。先把失败阶段对应的原始命令拿回本地执行，比如 go vet ./... 或者 go test ./...。如果本地没复现出来，再核对 Go 版本、操作系统差异、环境变量和工作目录配置。按照这个顺序排查，能快速把“代码本身问题”和“流水线环境问题”分开，避免靠加超时或者删缓存碰运气。

模块下载失败也不等于外网一定不稳定。先看日志里的模块路径是不是来自预期来源、go.sum 有没有跟着依赖调整同步提交、私有仓库是不是配置了最小权限的读取凭据。质量门禁里不要把长期有效的高权限令牌直接写进 YAML 文件；需要访问私有资源的时候，再按照仓库的密钥策略单独配置就好。

把 PR 状态当成反馈，不要把通知变成噪声

对于基础质量门禁来说，PR 页面上的 job 状态已经是最直接的反馈。团队可以约定：红色状态必须先修复到通过才能合并；如果临时需要忽略，必须在评审记录里明确说明原因。比起每次失败都往群里推送一条泛泛的通知，清晰的阶段名、失败命令和可复现的日志作用大得多。

当项目后续新增多个 job 时，还是建议保留一个清晰的汇总状态，比如 go-quality-gate。这样分支保护规则只需要盯住一个稳定的检查名，不会因为内部 job 重命名就失去约束。后续需要产物或者覆盖率报告的时候，再新增独立 job 即可；别让上传报告这类偶发不稳定的环节，遮住最关键的测试结果。

准备接入发布前，先完成这份最小复盘

1. 用一个空提交或者小改动确认推送和 pull request 动作都会正常触发质量门禁。
2. 故意制造一次可以快速恢复的测试失败，确认页面能显示明确的阶段名和对应日志位置。
3. 检查工作流只保留 contents: read，没有多余的写权限或者长期生效的高权限令牌。
4. 改动 go.mod 之后确认 CI 自动读取了相同的版本配置，而不是工作流里硬写的旧数字。
5. 最后再把这条检查设为合并前的必需状态；发布、镜像构建和部署逻辑交给后续的独立流水线处理。

相关问题

为什么还要单独跑 go vet？

单独命名能让失败日志更容易定位，也方便团队把静态问题和测试回归分开处理。具体的检查能力会随 Go 工具链版本变化，始终以当前工具的实际输出为准即可。

go test ./... 和 go build ./... 能合成一步吗？

可以写到同一段脚本里，但拆成两个独立步骤能保留更清晰的失败信号。刚接入 CI 的项目，这种可读性的价值通常比少写几行 YAML 更高。

质量门禁需要 contents: write 吗？

不需要。只拉取代码并运行 Go 命令时，contents: read 就足够了。只有工作流真的要提交内容、创建发布物或者调用其他写操作的时候，再按具体动作新增对应权限即可。

多模块仓库怎么选 Go 版本文件？

明确指定各模块或者工作区的版本文件与依赖路径，不要假定根目录下只有一个 go.mod。缓存路径也要跟着实际模块结构同步调整。

先让每次提交停在正确的门口

一个可靠的 Go CI 起点不需要复杂编排：触发范围明确、权限够用但不溢出、版本从项目自带文件读取，依赖、静态检查、测试和构建环节各自有独立命名。这样 PR 出问题的时候，开发者看到的不是一团混杂的输出，而是下一步该跑哪条命令、该检查哪份文件。等这条链路跑稳定之后，再把发布和部署作为另一条受控流程接上去就好。

关于 Go 工作流的版本设置、依赖缓存与构建测试，可继续阅读 GitHub 的 Go 构建与测试说明、setup-go 使用说明，以及 工作流权限语法。