根本原因是用了go run或环境变量未在go build作用域内生效；必须用GOOS=linux GOARCH=amd64 go build（同命令行），禁用CGO_ENABLED=0以避免工具链缺失报错。
GOOS/GOARCH交叉编译为什么总生成本地平台二进制
根本原因就两个：用了go run，或者环境变量没在go build命令作用域内生效。
Go 不支持go run做交叉编译——它永远只编译当前平台。必须用go build，且GOOS和GOARCH要和go build写在同一行，或提前export并确保未被子shell覆盖。
- 正确写法：
GOOS=linux GOARCH=amd64 go build -o app-linux . - 错误写法：
GOOS=linux GOARCH=amd64; go build -o app-linux .（分号导致变量仅对当前 shell 有效，不传给go build） - Mac M1 编译 Linux amd64 时，别漏掉
CGO_ENABLED=0，否则可能因找不到gcc报错：exec: "gcc": executable file not found in $PATH
CGO_ENABLED=0不是万能解，但不用它大概率失败
启用 CGO 时，Go 会调用目标平台的 C 工具链（如gcc、libc头文件）。你在 macOS 上没有 Linux 的libc，自然编译不过。禁用 CGO 是最简单可靠的跨平台方案，但代价是失去net包的系统 DNS 解析、部分 syscall 封装、以及所有依赖 C 库的 Go 包（比如sqlite3带 CGO 的版本）。
- 若项目必须用
cgo（例如调用 OpenSSL 或硬件驱动），就得在对应平台容器里构建，比如用docker run --rm -v $(pwd):/src golang:1.22-bookworm bash -c "cd /src && CGO_ENABLED=1 GOOS=linux GOARCH=arm64 go build -o app ." -
CGO_ENABLED=0下，net包退回到纯 Go 实现的 DNS 解析器，行为略有差异（比如不读/etc/resolv.conf的search域），上线前务必验证域名解析逻辑 - 某些包（如
github.com/mattn/go-sqlite3）需显式加_ "github.com/mattn/go-sqlite3"导入才触发 CGO，检查go list -json ./...输出中的CgoFiles字段可确认是否真用了 CGO
Makefile里怎么安全封装多平台构建
手敲一长串GOOS=xxx GOARCH=yyy go build容易漏参数、拼错平台名，也难复用。用Makefile统一管理，关键是把平台组合抽象成变量，并强制校验CGO_ENABLED状态。
立即学习“go语言免费学习笔记（深入）”；
PLATFORMS = linux/amd64 linux/arm64 darwin/amd64 darwin/arm64 windows/amd64 BINARY_NAME = myapp .PHONY: build-all build-all: $(addprefix build-, $(PLATFORMS)) $(addprefix build-, $(PLATFORMS)): build-%: @echo "Building for $*" @GOOS=$(word 1,$(subst /, ,$*)) \ GOARCH=$(word 2,$(subst /, ,$*)) \ CGO_ENABLED=0 \ go build -ldflags="-s -w" -o bin/$(BINARY_NAME)-$*-$(shell git describe --tags --always 2>/dev/null || echo dev) . .PHONY: build-linux build-linux: @CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o bin/$(BINARY_NAME)-linux-amd64 .
- 注意
git describe嵌入版本号，避免人工打标签遗漏；若无 tag，回退到dev，比空字符串更明确 -
-ldflags="-s -w"去掉符号表和调试信息，Linux/macOS 二进制体积常减 30%~50%，Windows 影响较小但建议保留 - 不要在
Makefile里写export GOOS=...——Make 的每个 recipe 默认新开 shell，export只对当前行有效
CI 中如何避免“本地能跑，CI 报错”的陷阱
CI 环境和本地最大差异在于：干净、无缓存、无交互、权限受限。常见崩点不是语法错误，而是路径、权限、环境变量默认值不同。
-
go mod download必须放在go build前，否则 CI 可能因模块缓存缺失而超时或拉错版本；推荐固定go version（如actions/setup-go@v4指定go-version: '1.22'） - Docker 构建中，如果 base image 是
golang:1.22-alpine，CGO_ENABLED默认为0，但 Alpine 的musl libc和 glibc 行为有差异，DNS 解析、时间 zone 处理可能出问题，测试时别只跑go test，要实际启动服务 curl 一下 - GitHub Actions 的
ubuntu-latest默认是amd64，想编译arm64二进制必须用runs-on: ubuntu-22.04-arm64或改用 QEMU 模拟，后者慢且不稳定，不建议用于正式发布
最常被忽略的是构建产物的清理时机：CI job 末尾没rm -rf bin/，下次构建可能混入旧平台二进制，上传 release 时出错却查不出原因。
