Appearance
Golang 项目 CI 入门：3 步配置 GitHub Actions 自动化单元测试
自动化测试是保证代码质量的第一道防线，而 GitHub Actions 让这一切变得简单高效。
在 Golang 项目开发中，每次代码变更后手动运行测试既繁琐又容易遗漏。GitHub Actions 提供了强大的 CI/CD 能力，让我们能够轻松实现代码推送或合并请求时自动运行单元测试。本文将手把手教你如何快速配置。
为什么需要自动化测试？
- 及时发现问题：每次提交代码时自动运行测试，第一时间发现回归问题
- 保证代码质量：强制执行
go vet静态分析，避免潜在错误 - 提升协作效率：团队成员无需关心测试环境配置，统一在云端执行
- 节省时间：自动化流程释放了开发者手动测试的时间
准备工作
在开始之前，请确保：
- 你的项目已经托管在 GitHub 上
- 项目根目录包含
go.mod文件（Go Module 项目） - 如果你有私有依赖库，需要准备一个具有读取权限的 GitHub Personal Access Token
第一步：创建测试工作流配置文件
在项目根目录下，创建工作流配置文件：
bash
mkdir -p .github/workflows && touch .github/workflows/test.yaml第二步：编写工作流配置
编辑 .github/workflows/test.yaml 文件，内容如下：
yaml
# This workflow will build a golang project
# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-go
name: test
on:
push:
branches: [ "master", "feature/*", "refactor/*", "perf/*" ]
pull_request:
branches: [ "master" ]
jobs:
build:
runs-on: ubuntu-latest
# 设置环境变量
env:
# 通过访问运行模式环境变量加载配置文件
GENERAL_RUNNING_MODE: workflow
# 如果某个组织全部是私有的，那么不用单独列出每一个库，只需要指定组织即可
# GOPRIVATE: github.com/go-discovery,github.com/go-microservice
ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
steps:
- uses: actions/checkout@v4
- name: Set up Go
uses: actions/setup-go@v4
with:
# 指定Go版本号（取消注释下面这行可以固定版本）
# go-version: '1.22.3'
# 推荐：从go.mod中自动读取Go版本号
go-version-file: 'go.mod'
- name: Configure Git with access token
run: git config --global url.https://[email protected]/.insteadOf https://github.com/
- name: Build
run: go build -v ./...
- name: Static code analysis
run: go vet ./...
- name: Test
run: go test -race -count=1 -v ./...第三步：配置仓库访问令牌
如果你的项目依赖私有库，需要配置访问令牌：
- 访问你的 GitHub 项目仓库
- 进入
Settings→Secrets and variables→Actions - 在
Repository secrets选项卡中，点击New repository secret - 创建一个名为
ACCESS_TOKEN的密钥，值为你的 GitHub Personal Access Token
提示
如果没有私有依赖，可以删除配置中关于 ACCESS_TOKEN 的部分，简化为公开仓库的标准配置。
工作流执行流程
当你完成配置并推送代码后，GitHub Actions 会自动执行以下流程：
触发条件说明
工作流在以下情况会被触发：
- Push 事件：推送到
master、feature/*、refactor/*、perf/*分支 - Pull Request 事件：向
master分支发起 PR
你可以根据项目实际情况调整分支名称和触发条件。
测试命令详解
bash
go test -race -count=1 -v ./...-race：启用竞态检测，发现数据竞争问题-count=1：禁用测试缓存，确保每次都重新运行-v：输出详细日志，便于排查问题./...：测试所有子包
常见问题
1. 如何固定 Go 版本？
注释掉 go-version-file，取消注释 go-version 并指定版本号即可。
2. 私有依赖拉取失败怎么办？
检查以下几点：
- ACCESS_TOKEN 是否正确配置
- 令牌是否具有
repo或read:packages权限 - GOPRIVATE 是否正确设置
3. 如何跳过某些目录的测试？
可以在 go test 命令中排除特定包，例如：
bash
go test -race -count=1 -v $(go list ./... | grep -v /vendor/)4. 工作流运行时间太长怎么办？
可以考虑：
- 使用
actions/cache缓存 Go 模块 - 使用矩阵策略并行测试多个 Go 版本
- 只测试变更影响的包（高级用法）
结语
通过以上三步配置，你的 Golang 项目就拥有了完整的自动化测试能力。每次代码变更时，GitHub Actions 都会自动运行测试，确保代码质量。这是一个投资回报率极高的配置，值得每一个 Go 项目采用。
配置完成后，你可以在 GitHub 仓库的 Actions 选项卡中查看工作流的运行状态和历史记录。
延伸阅读：
