制品库同步延迟导致 go mod download 失败，主因是代理缓存未刷新或上游 tag 未轮询抓取，表现为 unknown revision；需手动 resync、调整 polling interval 或轮询 @v/list 接口验证，严禁改 goproxy=direct 违背安全策略。
制品库同步延迟导致 go mod download 失败
企业级制品库（如 Nexus、JFrog Artifactory）常因缓存策略或同步任务滞后，导致新发布的模块版本在 go mod download 时查不到。现象是：本地 go get 或 go mod tidy 报错 unknown revision 或 module not found，但制品库 UI 上已显示该版本存在。
根本原因不是网络不通，而是制品库的 Go 仓库代理缓存未及时刷新，或上游源（如 GitHub）的 tag 尚未被制品库轮询抓取。Go 客户端默认只读一次元数据（index.json），不主动重试。
- 临时验证：用
curl -v https://your-artifactory/artifactory/go/your-module/@v/list直接请求制品库的 version list 接口，看返回是否包含目标版本 - 若返回为空或旧版本，说明同步未完成——需登录制品库后台手动触发 “Resync” 或调整上游源的 polling interval（通常默认 6 小时）
- 避免依赖“刚发布就构建”：CI 流程中，在
go mod download前加一段等待逻辑（如sleep 60），或轮询@v/list接口直到目标版本出现 - 不要改
GOPROXY为direct：这会绕过制品库，直连公网，违背内网安全策略
私有模块被 GOPROXY 错误代理拦截
当 GOPROXY 设为 https://goproxy.cn,direct 且未配置 GOPRIVATE 时，Go 工具链会把所有以 company.com 开头的模块路径当作公共模块，先发请求到 goproxy.cn 查询，再 fallback 到 direct。但很多企业制品库要求认证，direct 模式下又无法带 token，最终失败。
错误现象是：go mod download 卡住数秒后报 401 Unauthorized 或 404 Not Found，而 curl -H "Authorization: Bearer xxx" https://your-artifactory/... 能正常返回。
- 必须设置
GOPRIVATE=*.company.com（通配符支持子域），让 Go 跳过代理直接走direct并使用系统凭据 - 若制品库走 HTTP Basic Auth，需配置
netrc文件（Linux/macOS 在~/.netrc，Windows 在%USERPROFILE%/_netrc），内容为：machine your-artifactory login username password xxx - 验证是否生效：运行
go env GOPRIVATE确认输出含目标域名；再执行go list -m all | grep company，看路径是否解析为https://your-artifactory/...而非https://goproxy.cn/...
多团队共用制品库时版本覆盖冲突
不同团队向同一制品库路径（如 company.com/utils）发布不同语义化版本（v1.2.0 vs v1.3.0），但未强制校验 go.sum 中的 checksum。结果是：A 团队构建成功，B 团队拉取时因缓存了旧 checksum，报 verifying github.com/company/utils@v1.3.0: checksum mismatch。
这不是 Go 工具链 bug，而是制品库允许覆盖同名版本（尤其当未启用 immutable releases），导致 go.sum 记录的哈希与当前实际内容不一致。
- 制品库侧必须启用 “Immutable Releases” 或 “Block Redeploy” 功能，禁止覆盖已存在版本的二进制
- 客户端侧禁用
GOSUMDB=off：它虽能跳过校验，但彻底失去完整性保护；更稳妥的是用GOSUMDB=sum.golang.org+replace=your-sum-server指向企业自建 checksum server - CI 中增加校验步骤：
go mod verify应作为构建前必检项，失败即中止，避免问题流入镜像 - 开发机本地若反复遇到 mismatch，优先执行
go clean -modcache，而非删go.sum——后者会丢失所有校验锚点
CI 构建环境未继承 GOPRIVATE 或 netrc 配置
本地 go build 成功，但 CI（如 Jenkins、GitLab Runner）里失败，错误信息和 private module 相关。本质是 CI agent 启动的 shell 未加载用户级环境变量或凭据文件。
常见陷阱：在 .bashrc 里设 GOPRIVATE，但 CI 用 non-login shell 执行脚本，根本读不到；或 netrc 权限设为 644（应为 600），CI 进程拒绝读取。
- CI 脚本开头显式导出：
export GOPRIVATE="*.company.com"，不依赖 shell 配置文件 -
netrc文件必须由 CI pipeline 任务生成（而非挂载宿主机文件），并严格设权限：chmod 600 ~/.netrc - 避免用
replace替代制品库访问：它在 CI 中指向本地路径会直接失败，且掩盖真实权限问题 - 调试时加一句
go env | grep -E "(GOPRIVATE|GOPROXY)"和ls -l ~/.netrc，确认配置真实生效
