go mod tidy跨平台构建前报错，根本原因是其仅同步import与require，不验证CGO或平台兼容性；需确保GO_PRIVATE配置私有仓库、replace路径有效、CGO_ENABLED=0、GOOS/GOARCH拼写正确，并提交go.mod与go.sum。
go mod tidy 为什么总在跨平台构建前报错
因为 go mod tidy 不管你打算在哪跑，它只认当前环境能解析的路径和版本。跨平台编译时常见报错如 unknown revision 或 module not found，本质是 Go 工具链找不到依赖模块源——比如你本地开发用 macOS，但依赖里写了 github.com/org/private-repo，而没配 GO_PRIVATE，Go 就默认走代理，结果认证失败或跳过私有域名。
- 先确认所有被 import 的包是否真实可访问：用
go list -m all看实际加载路径，检查是否有=> ./local/path这类 replace 覆盖，或指向已删分支的 commit - 私有仓库必须设
GO_PRIVATE=*.company.com（支持 glob），否则go get和go mod tidy都会绕过认证直连 proxy - 本地多模块协同开发时，主模块的
go.mod必须显式replace到子模块绝对路径（如replace github.com/foo/bar => ../bar），相对路径在 CI 中容易失效 -
go mod tidy成功 ≠ 构建成功：它只同步 import 和 require，不验证 CGO 或平台兼容性，别把它当构建前置校验
CGO_ENABLED=0 不是可选项，是跨平台构建的默认开关
只要你的代码没调用 C 函数（比如没碰 net 包里的系统 DNS、没连 SQLite、没调 OpenSSL），就该默认关掉 CGO。开了 CGO_ENABLED=1 再交叉编译，等于主动给自己装雷。
- 错误现象：
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 app-linux main.go - 例外只有两类：真要用 cgo 依赖（如
sqlite3、libgit2），或必须用系统 resolver（net.DefaultResolver）；此时别在宿主机硬刚，改用docker build或xgo - Windows 构建记得加
.exe后缀：否则生成的文件无执行权限，双击打不开
GOOS/GOARCH 拼写错误比网络超时更致命
go tool dist list 输出才是唯一权威清单，手敲 linux/amd64 没问题，但写成 linux/x86_64 或 win32 就直接失败，且错误提示极其模糊——只会报 build failed，不告诉你哪错了。
- macOS M1 开发者最容易踩坑：目标服务器是 x86_64，就不能用
GOARCH=arm64，哪怕你本地芯片是 arm64 - Windows CMD 语法不同：
SET GOOS=linux && SET GOARCH=amd64 && go build -o app，不能像 bash 那样写成一行环境变量前缀 - Linux 上用
file app-linux验证输出是否含ELF 64-bit LSB executable, x86-64，避免误判 -
-ldflags="-s -w"只减体积，不影响平台兼容性；真正决定能不能跑的是CGO_ENABLED和GOOS/GOARCH组合
go.sum 和 go.mod 提交遗漏是 CI 失败最常见原因
很多人以为 go.mod 是“初始化用的”，go.sum 是“校验用的”，其实它们是构建事实的唯一来源。没提交，别人 clone 后 go build 就可能拉到不同版本依赖，甚至编译失败。
-
go.mod和go.sum必须进 Git，且禁止在.gitignore里 exclude 它们 -
vendor/目录现在应彻底删除：它和模块模式冲突，且增大仓库体积，CI 环境下反而拖慢构建 - CI 脚本里建议加一句
go mod verify，防止有人手改go.sum后忘提交 - 如果用了临时
replace，上线前务必清理：用go mod edit -dropreplace=xxx，或切发布分支时用干净go.mod
