同一份代码在 macOS 和 Linux 上 go build 行为不同，根本原因在于 GOPROXY、GOPRIVATE、git 协议配置及 go.mod 路径解析的隐式环境差异，而非 Go 工具链本身不一致；需统一代理策略、私有域名配置、SSH URL 替换和模块缓存清理。
平台差异报错（比如 macOS 本地能 build，Linux CI 上报 no required module provides package 或 unknown revision）根本不是 Go 本身不一致，而是环境配置、路径解析或代理行为在不同系统上默认不同。问题出在 GOPROXY、GOPRIVATE、git 协议配置、以及 go.mod 查找逻辑的隐式差异。
为什么同一份代码在 macOS 和 Linux 上 go build 行为不同
Go 工具链本身跨平台一致，但以下三处常因系统预设或用户配置产生偏差：
-
GOPROXY值未显式设置时，macOS 用户可能通过 Homebrew 安装了带 proxy 配置的 Go，而 Linux CI 默认是空或https://proxy.golang.org,direct，导致私有模块拉取失败 -
git config --global url."ssh://git@..."通常只在开发者本地（macOS）配置，CI 环境（Linux）没配，go get尝试用 HTTPS 访问私有 GitLab/GitHub Enterprise 时 404 或认证拒绝 - macOS 的
go mod init可能误推导出module /Users/xxx/project（含绝对路径），而 Linux 下该路径无效；更隐蔽的是，macOS Finder 挂载的卷名含空格或 Unicode，导致go list -m all解析replace路径失败
GOOS/GOARCH 不影响依赖解析，但 GOPROXY/GOPRIVATE 必须显式声明
依赖下载和校验发生在构建前，与目标平台无关。真正要统一的是网络策略和源码定位逻辑：
- 所有环境（包括 CI）都应设
GOPROXY=https://proxy.golang.org,direct——direct是关键，它让私有域名跳过代理直接走 git - 私有模块域名必须加入
GOPRIVATE=git.internal.company.com,github.com/internal/*，否则 Go 仍会尝试查 proxy 并失败 - 不要依赖
GO111MODULE=on：2026 年所有 Go 版本默认启用 modules，设它反而可能掩盖go.mod位置错误 - CI 脚本开头加
go env -w GOPROXY=... GOPRIVATE=...，避免依赖全局配置漂移
git 协议不一致导致 unknown revision
这是最典型的平台差异：macOS 本地用 SSH 克隆仓库并配置了 git config url."ssh://git@..."，CI 中只装了 git 但没配 URL 重写，go get 就会用 HTTPS 方式请求，返回 unknown revision。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
立即学习“go语言免费学习笔记（深入）”；
- 统一用 SSH URL 写
replace：例如replace github.com/internal/lib => git@git.internal.company.com:group/lib.git - CI 中必须执行：
git config --global url."ssh://git@git.internal.company.com/".insteadOf "https://git.internal.company.com/" - 确保 CI 的 SSH agent 加载了对应密钥（
ssh-add -l验证），且~/.ssh/config中 Host 别名与 replace 中的 host 一致 - 临时验证方式：
git ls-remote git@git.internal.company.com:group/lib.git—— 在 CI 和本地都跑一遍，结果必须一致
go.sum 校验和不一致的根源是平台级缓存污染
go.sum 记录的是每个模块 zip 包的哈希值，而 zip 包由 Go proxy 生成。如果 macOS 用了国内镜像（如 https://goproxy.cn），Linux CI 用了官方 proxy，同一 tag 可能生成不同 zip（时间戳、文件顺序等细微差异），导致 checksum mismatch。
- 所有环境强制使用同一 proxy：推荐
GOPROXY=https://proxy.golang.org,direct（官方最稳定） - CI 中运行
go clean -modcache开头，清空本地模块缓存，避免复用被污染的旧包 - 不要删
go.sum后再go mod tidy—— 这会重新计算哈希，但可能选到不同 commit（尤其当上游删了 tag） - 检查
go.sum是否混入了平台相关路径：比如某行末尾出现h1:xxx // goos:darwin，说明用了非标准构建，需排查是否引入了 cgo 或 platform-specific replace
真正难调试的不是报错信息本身，而是某个配置项（比如 GOPRIVATE）在本地 shell 里 export 过，却没写进 CI 的 env 配置块里；或者 git config 在 macOS 上对所有用户生效，而 CI 容器每次都是干净 root 用户。平台差异的本质，是环境状态没被声明化、不可重现。
