concourse/golang-builder

Go CI编译镜像技术文档

一、镜像概述

本镜像专为项目CI/CD流水线设计，主要用于在自动化构建流程中编译Go语言应用程序。通过预配置Go编译环境，简化CI流水线中的构建步骤，提高Go项目的编译效率和一致性。

二、核心功能与特性

核心功能

• 内置完整Go语言编译环境，无需额外安装依赖
• 支持标准Go项目构建流程（go build、go test、go mod等）
• 兼容主流CI/CD平台（GitHub Actions、GitLab CI、Jenkins等）

特性

• 轻量级：基于精简基础镜像，减少镜像拉取时间
• 版本化：通过镜像标签区分不同Go版本（如latest对应最新稳定版，1.21对应Go 1.21.x）
• 灵活配置：支持通过环境变量自定义编译参数（如Go模块代理、构建输出路径等）

三、使用场景与适用范围

使用场景

• CI/CD流水线中的构建阶段：在代码提交后自动触发Go项目编译
• 本地快速验证：通过Docker容器模拟CI环境，提前验证编译流程
• 多版本兼容测试：通过不同标签镜像测试项目在不同Go版本下的兼容性

适用范围

• Go语言开发的应用程序项目（包括可执行程序、库文件）
• 采用go mod或传统GOPATH管理依赖的Go项目
• 主流CI/CD平台（GitHub Actions、GitLab CI、Bitbucket Pipelines、Jenkins等）

四、使用方法

4.1 本地测试（docker run）

通过docker run命令可快速验证镜像功能，示例如下：

bash
# 挂载本地Go项目目录并执行编译
docker run --rm -v /path/to/your/go/project:/app -w /app docker.xuanyuan.run/go-ci-compiler:1.21 \
  sh -c "go mod download && go build -o app.bin ./cmd/main.go"

参数说明：

• -v /path/to/your/go/project:/app：将本地项目目录挂载到容器内/app路径
• -w /app：设置工作目录为/app（项目根目录）
• go-ci-compiler:1.21：指定使用Go 1.21版本的镜像
• 后续命令：先下载依赖（go mod download），再编译输出可执行文件app.bin

4.2 CI流水线配置示例

4.2.1 GitHub Actions配置

在项目根目录创建.github/workflows/build.yml：

yaml
name: Go Build
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Build with Go CI image
        uses: docker://go-ci-compiler:1.21
        with:
          args: sh -c "go mod download && go build -o app-linux ./cmd/main.go"

4.2.2 GitLab CI配置

在项目根目录创建.gitlab-ci.yml：

yaml
stages:
  - build

go-build:
  stage: build
  image: docker.xuanyuan.run/go-ci-compiler:1.21
  script:
    - go mod download
    - go build -o app-linux ./cmd/main.go
  artifacts:
    paths:
      - app-linux

五、配置参数与环境变量

环境变量

自定义编译参数

可通过命令行参数或环境变量调整编译行为，示例：

bash
# 自定义Go模块代理
docker run --rm -e GOPROXY=https://goproxy.cn -v /path/to/project:/app -w /app docker.xuanyuan.run/go-ci-compiler:1.21 go build

六、注意事项

• 镜像标签与Go版本对应：使用特定标签（如1.21）确保编译环境版本一致性，避免因Go版本差异导致构建失败
• 依赖缓存：在CI配置中建议缓存$GOPATH/pkg/mod目录，减少重复下载依赖时间
• 多平台编译：如需交叉编译（如Linux→Windows），可结合GOOS和GOARCH环境变量（例如GOOS=windows GOARCH=amd64 go build）