私有模块下载失败90%因GOPRIVATE未正确配置，需显式声明内网域名（如gitlab.example.cn）并确保路径、协议、大小写与仓库URL完全一致，否则Go工具链会错误走GOPROXY导致401/403/timeout。
私有模块下载失败 90% 是 GOPRIVATE 没配对
Go 工具链默认把所有模块路径都扔给 GOPROXY，一旦你引用了 gitlab.example.cn/team/lib 这类内网地址，而 GOPRIVATE 没覆盖它，就会走代理 → 401/403/timeout。不是 Git 不通，是 Go 根本没让 Git 上场。
必须显式声明哪些路径属于私有域：
-
go env -w GOPRIVATE=gitlab.example.cn,github.com/my-org/*（支持通配符） - 多个域名用英文逗号分隔，不能有空格
- 验证：运行
go env GOPRIVATE，输出应为设定值，不是空或none - 注意大小写：如果仓库 URL 是
GitLab.example.cn，但GOPRIVATE写成gitlab.example.cn，仍可能不匹配（取决于 Git 服务配置）
认证失败不是密码问题，是 Git 协议和凭据没对齐
Go 调用 git 命令拉取私有模块，所以认证成败完全取决于本地 git 是否能成功 clone 该地址。常见断点：
- SSH 方式：确保
git clone git@gitlab.example.cn:team/lib.git能通；ssh -T git@gitlab.example.cn返回欢迎信息；~/.ssh/config中 Host 别名未导致路径解析错乱 - HTTPS + Token：URL 必须带 token，如
https://TOKEN:x-oauth-basic@gitlab.example.cn/team/lib；且已执行git config --global credential.helper store并首次手动输入过凭据 - 避免混合协议：go.mod 中写
gitlab.example.cn/team/lib，但 Git 凭据里存的是https://gitlab.example.cn—— 域名必须完全一致
GOPROXY=direct 不是解法，而是临时诊断手段
把 GOPROXY 设成 direct 确实能让私有模块“跑起来”，但它绕过了所有缓存、校验和审计能力，等于裸奔。真正要落地，得闭环：
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
- 内网必须部署可控代理（如
athens），设GOPROXY=http://athens.internal:3000，再配合GOPRIVATE让私有模块直连、公共模块走缓存 -
GOSUMDB不能简单设off：更稳妥的是GOSUMDB=sum.golang.org+https://sum.golang.org+ 内网 DNS 将sum.golang.org解析到私有校验服务，否则go mod verify失效 - 所有节点的
go env输出中，GOPROXY、GOPRIVATE、GOSUMDB三项必须一致，靠/etc/profile.d/golang.sh或组策略统一注入，别信“我本地改好了”
go.mod 里写错路径，比网络不通还难排查
模块路径不是随便写的字符串，它必须和 Git 仓库的克隆地址、HTTP 服务暴露的路径、以及 GOPRIVATE 的匹配规则三者对齐。典型错位：
- GitLab 项目实际 URL 是
https://gitlab.example.cn/group/subgroup/repo，但go.mod写成gitlab.example.cn/repo→ 报unknown revision - 仓库启用了子组（subgroup），但模块路径漏掉中间层级，
go get会 404 - 使用 SSH 克隆时，
go.mod中路径必须与git@后面的 host + path 完全一致，例如gitlab.example.cn/group/repo对应git@gitlab.example.cn:group/repo.git - CI 构建时，若用容器镜像，需确认镜像内预置的 Git 配置、SSH key 或凭据是否与宿主机一致
真正卡住的点往往不在网络或权限，而在路径字符串的细微偏差、环境变量的继承范围、以及 Git 协议与 Go 模块路径之间的映射关系——这些地方一错，错误信息全是“not found”或“unauthorized”，但真实原因藏在路径匹配逻辑里。
