学完这篇,你能用一条命令把同一个 Go 程序编译成 Linux、macOS、Windows 的 x86 与 ARM 版本,并产出可直接上传到发布页的压缩包和校验文件。
第一步:把版本信息做成可注入的变量
先在 main 包里声明几个空变量,构建时用 -ldflags 填值,这样程序里 --version 输出的就是真实版本号,而不是写死的字符串。
package main
var (
Version = "dev"
Commit = "none"
BuildTime = "unknown"
)
注意:-X 后面的格式是「包路径.变量名」。变量在 main 包就直接写 main.Version;如果放在 internal/version 包里,就要写完整导入路径,例如 -X github.com/you/app/internal/version.Version=v1.2.0。另外这些变量必须是 string 类型的包级变量,且不能被编译器优化掉。
第二步:跑通一次交叉编译
Go 交叉编译只需要两个环境变量:GOOS(目标系统)和 GOARCH(目标架构)。最关键的第三个是 CGO_ENABLED=0——只要代码里没有必须用 cgo 的依赖(比如 sqlite3),就一定要关掉,否则跨平台会直接失败。
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 \
go build -trimpath -ldflags "-s -w" -o dist/app_linux_arm64 ./cmd/app
几个参数的含义:
-trimpath:去掉二进制里的本机绝对路径,产物更干净、可复现
-s -w:去掉符号表和调试信息,体积通常能小 25%~30%
-o:输出文件名,Windows 目标必须带 .exe 后缀
常用组合:linux/amd64、linux/arm64、darwin/amd64、darwin/arm64(Apple Silicon)、windows/amd64。要出 32 位 ARM(树莓派早期型号)时再加 GOARM=7;要指定 x86 指令集下限用 GOAMD64=v2。
注意:CGO_ENABLED 的默认值取决于本机环境和是否装了 gcc,不要指望它「默认就是 0」。所有跨平台构建命令里都显式写上,才不会在 CI 和本地出现两种结果。
第三步:写个脚本批量出全平台包
手敲五遍命令容易漏,写成脚本:
#!/usr/bin/env bash
set -euo pipefail
APP=app
VERSION=${VERSION:-$(git describe --tags --always --dirty)}
COMMIT=$(git rev-parse --short HEAD)
BUILD_TIME=$(date -u +%Y-%m-%dT%H:%M:%SZ)
LDFLAGS="-s -w -X main.Version=${VERSION} -X main.Commit=${COMMIT} -X main.BuildTime=${BUILD_TIME}"
targets=("linux/amd64" "linux/arm64" "darwin/amd64" "darwin/arm64" "windows/amd64")
rm -rf dist && mkdir -p dist
for t in "${targets[@]}"; do
GOOS=${t%/*}; GOARCH=${t#*/}
out="dist/${APP}_${VERSION}_${GOOS}_${GOARCH}"
[ "$GOOS" = "windows" ] && out="${out}.exe"
echo "==> ${GOOS}/${GOARCH}"
CGO_ENABLED=0 GOOS=$GOOS GOARCH=$GOARCH \
go build -trimpath -ldflags "$LDFLAGS" -o "$out" ./cmd/$APP
done
文件名统一成 应用名_版本_系统_架构,用户下载后一眼就知道该拿哪个。
第四步:验证产物是真的能用
不要只看到「编译成功」就发布,至少做两项检查:
file dist/app_v1.2.0_linux_amd64 # 应显示 ELF 64-bit ... x86-64
ldd dist/app_v1.2.0_linux_amd64 # 应提示 not a dynamic executable
ldd 报「不是动态可执行文件」说明是静态链接,扔到任何 Linux 上都能跑,不会因为目标机器没有 glibc 或版本太旧而报错。
ARM 产物在本机跑不了,用 Docker 模拟验证:
docker run --rm --platform linux/arm64 -v "$PWD/dist:/dist" \
alpine /dist/app_v1.2.0_linux_arm64 --version
注意:关掉 cgo 后,Go 会用纯 Go 的 DNS 解析器,行为与系统解析器略有差异;同时二进制不再依赖系统证书,但如果你在 scratch 镜像里跑,程序做 HTTPS 请求会因为没有 CA 证书失败——记得把 ca-certificates.crt 一起打包。
第五步:生成校验和与压缩包
cd dist && for f in app_*; do
case "$f" in *.exe) zip -q "${f%.exe}.zip" "$f";; *) tar -czf "$f.tar.gz" "$f";; esac
done
sha256sum app_*.tar.gz app_*.zip > checksums.txt
macOS 上没有 sha256sum,用 shasum -a 256。把 checksums.txt 和压缩包一起贴到发布页,用户下载后 sha256sum -c 就能自行核对。
第六步:交给 CI 自动发布
手动跑脚本容易忘,用 GitHub Actions 的矩阵在打 tag 时自动构建:
name: release
on:
push:
tags: ['v*']
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
goos: [linux, darwin, windows]
goarch: [amd64, arm64]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version: '1.22'
- run: |
CGO_ENABLED=0 GOOS=${{ matrix.goos }} GOARCH=${{ matrix.goarch }} \
go build -trimpath -ldflags "-s -w" \
-o dist/app-${{ matrix.goos }}-${{ matrix.goarch }} ./cmd/app
矩阵里有 6 个组合,每个 job 各出一个平台,并行跑完再汇总上传。
注意:setup-go 里写的版本不能低于 go.mod 中声明的 go 版本,否则构建会直接报错退出。项目越大越容易踩这个坑,因为升级 go.mod 时常常忘了改 CI 配置。
小结
- 跨平台构建三件套:
GOOS、GOARCH、CGO_ENABLED=0,三个都要显式写
- 版本号用
-ldflags "-X main.Version=..." 注入,别写死在代码里
-trimpath -s -w 让产物更小、路径干净、可复现
- 发版前用
file 和 ldd 确认架构正确、静态链接
- 用脚本或 CI 矩阵批量出包,配上
sha256 校验文件
- Windows 产物记得
.exe,ARM 产物用 Docker --platform 做冒烟测试