私有仓库Go模块下载失败主因是GOPRIVATE配置不完整或git认证未打通；需确保GOPRIVATE精确匹配模块路径（大小写敏感、含通配符）、git能直连仓库，并配套设置GOPROXY=direct与GOSUMDB=off。
私有仓库的 Go 模块依赖下载失败，90% 是因为 GOPRIVATE 配置不完整或系统 git 认证没打通——Go 本身不处理登录，只把拉取动作交给本地 git 命令；而 GOPRIVATE 不是“指定地址”，而是“告诉 Go 别代理、别校验”的开关，漏配子路径或带空格都会静默失效。
为什么 go get 私有模块总报 unknown revision 或 404
根本原因不是网络不通，而是 Go 在代理模式下默认拒绝直连私有域名。它会先尝试走 GOPROXY（比如 proxy.golang.org）查版本列表，结果返回 403 或超时，然后才 fallback 到直连——但此时若 GOPRIVATE 没覆盖到实际 module path，仍会跳过认证环节，导致 git clone 失败。
-
GOPRIVATE必须包含完整前缀，例如模块路径是gitlab.example.com/team/lib，则GOPRIVATE至少得是gitlab.example.com/**；写成gitlab.example.com/或*.example.com都无效 - 多个域名用英文逗号分隔，**严禁空格**：
go env -w GOPRIVATE="gitlab.example.com/**,gitee.com/my-team/*" - 如果模块路径含大写字母（如
GitLab.example.com），GOPRIVATE中必须大小写完全一致——Go 匹配是区分大小写的 -
GO111MODULE=on必须生效，否则整个模块机制退化，GOPRIVATE形同虚设
git 认证失败：HTTPS Token 和 SSH 密钥怎么选
设置了 GOPRIVATE 只是让 Go 跳过代理，真正执行 git clone 的是系统级 git。所以你在终端能 git clone https://gitlab.example.com/team/lib 成功，go get 才可能成功。
- HTTPS 方式推荐用
git config注入 token：git config --global url."https://<token>:x-oauth-basic@gitlab.example.com/".insteadOf "https://gitlab.example.com/"</token>，注意token要 URL 编码（如含/或@） - SSH 方式需确保
~/.ssh/id_rsa已添加到 ssh-agent，且私有仓库 URL 使用git@gitlab.example.com:team/lib.git格式；go mod init时 module path 仍应写成gitlab.example.com/team/lib（与 URL 域名一致即可） - 不要混用：如果
git config配了 HTTPS，但仓库 URL 实际是 SSH，git clone会失败，Go 不会自动降级或提示
go mod download all 看似全量下载，其实有盲区
go mod download all 确实会拉取 go list -m all 输出的所有模块，但它不处理三类情况：被 replace 指向远程 URL 的模块、exclude 掉的模块、以及 build tags 分支里未被当前环境触发的间接依赖。
立即学习“go语言免费学习笔记（深入）”；
- 运行前先确认
go list -m all | grep 'your-private-domain'能列出目标模块；如果没出现，说明go.mod里没真正引用，或import被 build tag 屏蔽了 - 如果有
replace example.com/a => https://github.com/x/a v1.2.0，go mod download all会跳过它——因为 Go 认为这是个重定向，要等go build时才去抓 - 离线构建前，务必加
-v参数跑一次go build -a -v，观察输出里是否还有新出现的Fetching日志；有就说明还有漏网依赖
GOSUMDB=off 和 GOPROXY=direct 必须配套使用
即使所有模块都已缓存，Go 构建时仍可能因 checksum 校验失败而中断——尤其当私有模块没有发布到官方 checksum 数据库时。这时仅设 GOPROXY=direct 不够，还必须关掉校验。
- 正确组合：
go env -w GOPROXY=direct GOSUMDB=off；单独设GOPROXY=direct会让 Go 去sum.golang.org查校验和，而私有模块必然查不到 -
GOSUMDB=off不影响安全性：只要go.sum文件在版本控制中，团队成员之间就能复现相同依赖；关校验只是跳过对未托管模块的在线验证 - CI 环境中建议显式导出：
GOPROXY=direct GOSUMDB=off go build，避免继承全局配置引发歧义
最容易被忽略的是 module path 和仓库 URL 的一致性——哪怕只差一个 www. 或大小写，Go 就会当成两个不同模块，导致缓存不命中、重复下载、甚至构建时找不到包。配置完务必用 go list -m -f '{{.Path}} {{.Version}}' your-private-module 验证路径是否精确匹配。
