跨平台编译失败的根本原因是构建环境不一致：GOROOT/GOPATH路径差异导致模块解析错乱，CGO_ENABLED=1引发动态链接失败，必须显式设置GOOS/GOARCH并禁用CGO，使用官方Go二进制且统一GOROOT路径。
跨平台编译时依赖能正常拉取，但二进制在目标机器上启动失败——根本不是网络或权限问题，而是构建环境里 GOROOT 和 GOPATH 的路径不一致导致模块解析错乱。直接在目标平台装 Go 官方二进制 + 显式设置 GOOS/GOARCH，才是唯一可控路径。
GOOS/GOARCH 编译前必须关掉 CGO
默认 CGO_ENABLED=1 会让 go build 链接宿主机的 libc，结果 macOS 上编译出的 Linux 二进制，运行时报 cannot execute binary file: Exec format error 或更隐蔽的 undefined symbol: __cxa_thread_atexit_impl——这不是架构不匹配，是动态链接失败。
- 静态编译命令必须显式设
CGO_ENABLED=0：CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o myapp - 若项目真需调用 C（如 SQLite、openssl），则必须在目标平台交叉编译，或用 musl 工具链；不能依赖宿主机 libc
-
go env -w CGO_ENABLED=0全局关闭有风险，建议只在构建脚本里临时设置
go.mod 和 go.sum 必须纳入版本控制
没 go.mod 的项目，go build 会按 GOPATH 模式查找依赖，不同机器上 go list -m all 输出可能漂移——尤其当本地 $GOPATH/src 里已有旧版模块时，这不是 bug，是 GOPATH 模式的设计逻辑。
- 新项目第一件事：
go mod init example.com/myapp（域名合法即可，不需真实存在） - 老项目补
go.mod：go mod init+go mod tidy，然后确认go.sum生成完整校验和 -
.gitignore必须保留go.mod和go.sum，但排除bin/、pkg/ - CI 环境里加
GO111MODULE=on，避免某些旧镜像默认关模块
系统包管理器安装的 Go 不适合跨平台构建
apt/brew/choco 安装的 Go 版本通常滞后 1–2 个 minor 版本，且 GOROOT 路径不可控（比如 brew 把 Go 装在 /opt/homebrew/opt/go/libexec），导致 go env GOROOT 输出不一致，VS Code 的 go.goroot 配置容易失效，gopls 启动失败。
- 正确做法：从
golang.google.cn/dl/下载对应平台最新稳定版压缩包（如go1.22.6.darwin-arm64.tar.gz） - 解压到固定路径：
/usr/local/go（macOS/Linux）或C:\Go（Windows） -
PATH中只加$GOROOT/bin，不要混入$GOPATH/bin——后者仅用于go install工具，与项目构建无关
真正麻烦的从来不是命令怎么写，而是构建环境是否干净、GOROOT 是否统一、CGO_ENABLED 是否被忽略——这些细节一旦漏掉，错误现象就藏在运行时，而不是编译期。
