Go原生支持多平台编译,但必须每条go build命令前显式设置GOOS和GOARCH(如GOOS=linux GOARCH=amd64),否则默认仅构建当前darwin平台;需禁用CGO_ENABLED=0、输出路径带平台标识、Windows加.exe后缀、ARM按需设GOARM。

在 macOS 上用 Go 做多平台构建,核心就一条:GOOS 和 GOARCH 必须每条 go build 命令前显式设置,不能靠 export 或 shell 环境继承——否则你永远只得到 darwin 二进制。
GOOS/GOARCH 必须写在 go build 命令同一行
Makefile 或终端里写 export GOOS=linux 再跟 go build,第二行根本看不到这个变量。macOS 的 make 不继承上一行的环境变量,bash/zsh 也一样。
- ❌ 错误写法:
export GOOS=windows; go build -o app.exe . - ✅ 正确写法:
GOOS=windows GOARCH=amd64 go build -o app-windows-amd64.exe . - Windows 输出必须带
.exe后缀,否则生成的是无扩展名文件,CI 或用户双击打不开 - ARM64 Mac 用户想构建 Linux ARM64?加
GOARCH=arm64即可,不用额外工具链(除非用了 cgo)
禁用 CGO 是多数 CLI 项目的默认安全选项
macOS 上默认 CGO_ENABLED=1,一旦启用,go build 会尝试链接系统 libc —— 这直接导致 Linux 二进制在 Alpine 容器里报 not found,Windows 构建则直接失败。
- 统一加前缀:
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o dist/app-linux-amd64 . - 副作用:net 包改用纯 Go DNS 解析器(
netgo),不读/etc/resolv.conf;如需系统 DNS,启动时加GODEBUG=netdns=system - CI 流水线里绝不能依赖本地
CGO_ENABLED值,必须每条命令都显式写出
输出路径和文件名必须带平台标识
所有平台二进制塞进同一个 dist/app 路径,下次 make 就覆盖掉上一次的,发布时发错包是常态。
立即学习“go语言免费学习笔记(深入)”;
- 建议命名格式:
app-$(GOOS)-$(GOARCH),例如app-linux-amd64、app-darwin-arm64 - Windows 额外加
.exe:app-windows-amd64.exe,别指望系统自动补 - 构建前加
mkdir -p dist/,否则go build -o dist/xxx会因目录不存在失败 - 如果用 Makefile,每个
build-*target 都该以mkdir -p dist/开头
别硬写六七个 build-* target,用 make 变量+foreach 动态生成
手动列 build-linux-amd64、build-linux-arm64、build-darwin-amd64……新增 freebsd 或 riscv64 时要改三处,漏一个就少一个平台。
- 定义平台列表:
PLATFORMS = linux/amd64 linux/arm64 darwin/amd64 darwin/arm64 windows/amd64 - 用
$(foreach p,$(PLATFORMS),...)循环生成 target 和命令 - 这样加新平台只要改一行
PLATFORMS,无需碰命令逻辑或 help 文本 - 真实项目中,
GOARM=7(ARMv7)、GOAMD64=v3(AVX 指令集)这类参数也要按需注入,不能全靠默认
最容易被忽略的是:即使你写了 go build -o bin/app-linux,只要没设 GOOS=linux,它在 macOS 上跑出来的还是 darwin 二进制——文件名骗不了人,但运行时直接报错或静默失败。


















