核心卡点是GOOS/GOARCH、CGO_ENABLED、GOPROXY、go.mod/go.sum四者未对齐：必须显式指定构建目标，禁用cgo保证静态链接，国内配goproxy.cn，go.sum需统一平台生成以确保依赖一致性。
Go 项目跨平台迁移不是“换个系统编译就行”，核心卡点在 GOPATH/GOPROXY/CGO 和构建目标三处——其余多数问题都源于这四个变量没对齐。
GOOS/GOARCH 构建目标必须显式指定
默认 go build 只生成当前宿主系统的二进制，Linux 上编译 macOS 二进制会失败，Windows 上编译 Linux 服务也跑不起来。跨平台构建必须用环境变量控制目标平台：
GOOS=linux GOARCH=amd64 go build -o myapp-linux main.goGOOS=darwin GOARCH=arm64 go build -o myapp-mac main.goGOOS=windows GOARCH=386 go build -o myapp-win.exe main.go
注意：CGO_ENABLED=0 必须配合使用（尤其交叉编译到 Linux），否则会因缺失 C 运行时链接失败；macOS 的 arm64 和 amd64 是不同 ABI，不能混用。
GOPROXY 配置不一致导致依赖拉取失败
国内开发者常配 https://goproxy.cn 或 https://proxy.golang.org，但不同平台的 shell 环境加载顺序不同，go env -w GOPROXY=... 写入的是用户级配置，而 CI 环境或 Docker 容器里可能完全没生效：
立即学习“go语言免费学习笔记（深入）”；
- 检查方式：
go env GOPROXY，不是看.bashrc里有没有 export - CI 脚本中务必显式设置：
export GOPROXY=https://goproxy.cn,direct - 私有模块场景下，
GOPRIVATE必须同步配置，否则go mod download会跳过私有域名直接走代理报 404
典型错误：go: github.com/xxx/yyy@v1.2.3: reading github.com/xxx/yyy/go.mod at revision v1.2.3: 404 Not Found —— 就是 GOPROXY 拦截了私有地址。
CGO_ENABLED 在跨平台构建时极易被忽略
只要代码里用了 cgo（比如调用 SQLite、OpenSSL、系统 DNS 解析），交叉编译就必须面对 C 工具链问题：
-
CGO_ENABLED=0：禁用 cgo，所有依赖必须纯 Go 实现（如github.com/mattn/go-sqlite3不可用） -
CGO_ENABLED=1：需匹配目标平台的CC编译器，例如CC_arm64_linux=arm64-linux-gcc - Docker 多阶段构建中，build 阶段开 CGO，alpine 运行阶段关 CGO 是常见折中方案
现象：Linux 上 go build 成功，但 macOS 上运行报 dyld: Library not loaded: @rpath/libxxxx.dylib —— 就是 CGO 动态链接路径没适配。
go.mod 和 go.sum 的平台无关性陷阱
go.mod 本身是平台中立的，但 go.sum 里记录的校验和包含 // indirect 依赖的完整树，一旦某依赖在不同平台解析出不同子版本（比如 Windows 下 golang.org/x/sys 引入了 windows 专属分支），go mod tidy 就可能改写 go.sum：
- 团队协作时，禁止提交由不同 OS 自动生成的
go.sum差异 - CI 流水线统一用 Linux runner 执行
go mod tidy && git diff --quiet go.sum做守门检查 - 本地开发若频繁切平台，建议用
go clean -modcache清理后重拉，避免缓存污染
最隐蔽的问题：某个 indirect 依赖在 macOS 上解析为 v0.11.0，在 Linux 上却是 v0.10.0，表面没报错，但运行时 JSON 序列化行为不一致 —— 这类问题只能靠 go list -m all 对比确认。
