跨平台构建失败主因是本地缓存、CGO启用或模块解析路径不一致；CGO_ENABLED=0可强制静态链接实现跨平台兼容，但需注意os/user等包功能退化，且GOPROXY、GONOSUMDB、GOPRIVATE须统一配置以保障go.sum一致性。
跨平台构建失败，八成是本地缓存、CGO 或模块解析路径不一致导致的，不是 Go 本身不兼容。
go build 在 Linux/macOS/Windows 上行为不一致？先关掉 CGO
CGO_ENABLED=1 时，Go 会动态链接系统库（如 libc、libpthread），不同平台 ABI 不同，同一份 go.mod 在 macOS 编译出的二进制无法在 Linux 运行，反之亦然。CI 构建失败常源于此。
- 生产环境容器部署务必加
CGO_ENABLED=0：它强制静态链接，生成纯 Go 二进制，跨平台零问题 - 若必须用 CGO（如调用 C 库），则构建环境 OS、libc 版本、编译器（gcc/clang）需与目标环境严格一致
-
go env -w CGO_ENABLED=0可设为全局默认，但注意：禁用后os/user、net等包部分功能会退化（如无法读取系统用户数据库）
go mod download 和 go.sum 在不同机器上结果不同？检查 GOPROXY 和 GONOSUMDB
同一 go.mod 在 A 机跑 go mod download 得到的 go.sum，换到 B 机可能校验失败——根本原因是代理或校验策略不统一。
-
GOPROXY必须固定（如https://proxy.golang.org,direct），避免一台走官方 proxy，另一台直连私有 Git 导致 tag 解析结果不同 - 私有模块必须配置
GOPRIVATE=git.example.com，否则 Go 默认仍尝试走 proxy，认证失败就 fallback 到direct，但路径拼接逻辑可能出错 -
GONOSUMDB要和GOPRIVATE保持一致；若只设GOPRIVATE却没设GONOSUMDB，go.sum里会写入空哈希，导致go mod verify失败
本地 replace 在 CI 上失效？别让 replace 进入主分支的 go.mod
replace 是开发期临时方案，CI 环境没有本地路径 ./local/dep，一跑就报 no required module provides package。
- 开发时用
replace没问题，但提交前务必运行go mod tidy清理掉它（或手动删掉go.mod中的replace行） - CI 脚本开头加
go mod edit -dropreplace=all，确保构建不受开发期替换干扰 - 真要锁定版本，直接在
go.mod的require块写死，比如github.com/sirupsen/logrus v1.9.3，再go mod tidy
Windows 路径分隔符引发 import 错误？go mod tidy 不会自动修，得人工对齐
Windows 下用反斜杠 写本地路径（如 replace github.com/x/y => .localy），Linux/macOS 会解析失败；更隐蔽的是，某些编辑器自动把路径转成 file:///C:/... 格式，Go 工具链不认。
- 所有
replace的本地路径必须用正斜杠/，且为相对路径（./local/y），绝对路径（/home/user/y或C:/y）一律禁止 - 跨平台协作时，用
go list -m all检查实际加载路径，确认没出现file://或盘符 - Git 提交前开个 pre-commit hook，用
grep -q 'replace.*[\:]' go.mod拦截非法路径
最易被忽略的是 go.sum 文件本身——它记录的是每个模块 zip 包的哈希，不是源码 commit ID。上游删了 tag、重推了相同版本号的 zip，哈希就变，go mod verify 就会失败。跨平台构建前，先确认 go.sum 是否被意外修改过。
