跨平台编译失败主因是GOOS和GOARCH未同时正确设置，或CGO_ENABLED=1时缺失目标平台C工具链；纯Go代码应设CGO_ENABLED=0并显式指定GOOS/GOARCH组合。
Go 环境能跑起来，但跨平台编译失败？大概率不是 Go 本身的问题，而是 GOOS 和 GOARCH 没设对，或者本地构建环境缺失目标平台的交叉编译支持（比如 Windows 下直接 go build 出 Linux 二进制是默认支持的，但反过来不行）。
go version 能跑，但 go build 失败：先查 go env 里这三项
很多用户卡在“明明装好了 Go，go version 正常，一执行 go build 就报错”，其实问题常出在环境变量没生效或被覆盖：
-
GOROOT必须指向真实安装路径（如C:\Program Files\Go或/usr/local/go），不能是空或错误路径 -
GOPATH不影响编译，但若项目用了旧式src目录结构，且没开GO111MODULE=on，它就起作用 —— 建议统一开模块模式，忽略GOPATH语义 - 最关键的其实是
GO111MODULE：必须为on，否则go.mod不生效，依赖下载会静默失败或走老路径
执行 go env 后逐项核对，尤其注意 PowerShell 中用 $env:GO111MODULE 查，CMD 用 echo %GO111MODULE%。别信“安装完就自动配好”——Windows MSI 安装器不保证写入系统级 PATH，Linux/macOS 的 tar 解压更不会自动改 shell 配置。
国内用户必设 GOPROXY，否则 go get 卡死或 403
Go 官方代理 https://proxy.golang.org 在国内基本不可用，不设代理时常见现象：
立即学习“go语言免费学习笔记（深入）”；
-
go get github.com/sirupsen/logrus卡在 “Fetching” 几分钟无响应 -
go mod download报错：Get "https://proxy.golang.org/...": dial tcp 142.250.191.113:443: i/o timeout - 部分包（如
golang.org/x/...）返回 403，因为域名被重定向到 goproxy.cn 但未显式配置
正确做法（任选其一，推荐命令行一次性写入）：
Windows（CMD）：go env -w GOPROXY=https://goproxy.cn,direct
macOS/Linux：go env -w GOPROXY=https://goproxy.cn,direct
注意末尾的 ,direct：表示对私有仓库（如公司内网 Git）跳过代理直连，不加它会导致内部模块拉不到。
跨平台编译：GOOS 和 GOARCH 是唯一控制开关
Go 原生支持交叉编译，不需要额外工具链。但必须显式指定目标平台，否则默认按当前系统生成：
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 从 macOS 编译 Linux 二进制：
GOOS=linux GOARCH=amd64 go build -o app-linux - 从 Windows 编译 ARM64 Linux：
SET GOOS=linux && SET GOARCH=arm64 && go build -o app-arm64（CMD） - 编译 Windows GUI 程序（隐藏控制台）：
GOOS=windows go build -ldflags="-H windowsgui" -o app.exe
常见组合：
GOOS=linux + GOARCH=amd64（主流服务器）
GOOS=darwin + GOARCH=arm64（M1/M2 Mac）
GOOS=windows + GOARCH=386（32 位 Windows，已少见）
注意：GOARM 仅用于 GOARCH=arm（非 arm64），且只在 Go 1.19 之前有效；现在 ARMv7 及以上统一用 arm64。
Windows 上编译 Linux/macOS 二进制：不用 WSL，但要注意 CGO
纯 Go 代码（不调 C 库）可直接跨平台编译，但一旦启用了 cgo（比如用了 net 包中的 DNS 解析、或显式 import "C"），行为就变了：
-
CGO_ENABLED=0：禁用 cgo，强制纯 Go 实现（DNS 走纯 Go 解析，os/user无法读取系统用户信息），此时跨平台编译完全没问题 -
CGO_ENABLED=1（默认）：编译时会调用宿主机的 C 工具链（如 Windows 的 gcc），但目标平台头文件和库不存在 → 直接报错
所以生产服务建议默认加 CGO_ENABLED=0：
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -a -o server
其中 -a 强制重新编译所有依赖（含标准库），确保无残留 cgo 依赖。
真正容易被忽略的是：GOOS/GOARCH 设定后，go test 仍只在本机运行 —— 它不会自动切目标平台测试。交叉编译出的二进制，必须扔到对应系统里手动验证，或用容器（如 docker run --rm -v $(pwd):/app linux/amd64 /app/server）跑。
