必须从go mod init起同步配置私有仓库，核心是设置GOPRIVATE=gitlab.example.com/*（通配符不可省），并配套设置GONOPROXY和GONOSUMDB为相同值，同时确保Git凭据或SSH认证可用，否则go mod tidy将失败。
Go 语言私有仓库配置在企业级开发中不是“学完再配”，而是从第一个 go mod init 就必须同步落地的事。不配，go mod tidy 会卡死或报 unknown revision；配错，后续所有 CI/CD、多人协作、模块发布都会反复出问题。
设置 GOPRIVATE 是绕过代理的第一步
Go 默认把所有模块都当作可公开访问的，会优先走 https://proxy.golang.org，而私有路径（如 gitlab.example.com/team/lib）根本不在它的索引里。不设 GOPRIVATE，Go 就不会尝试用 Git 直连拉取。
- 必须用
go env -w GOPRIVATE=gitlab.example.com/*（通配符不能省），多个域名用逗号分隔，例如gitlab.example.com/*,gitee.internal.net/* - 别写成
GOPRIVATE=gitlab.example.com—— 缺少/*会导致子路径（如gitlab.example.com/team/utils）不被识别为私有 - 设完后执行
go env GOPRIVATE确认输出是否符合预期，避免 shell 配置未生效
GONOPROXY 和 GONOSUMDB 要配合 GOPRIVATE 使用
GOPRIVATE 只控制“是否跳过代理”，但 Go 还会在拉取后校验模块哈希——如果私有模块没进官方 sum.golang.org，就会报 verifying ...: checksum mismatch。
- 补上
go env -w GONOSUMDB=gitlab.example.com/*，否则go mod download仍会尝试查 sumdb 并失败 -
GONOPROXY和GONOSUMDB的值建议与GOPRIVATE完全一致，避免漏配；不一致时，GONOPROXY仅影响代理路由，GONOSUMDB才真正关闭校验 - 不要设
GOSUMDB=off—— 它是全局关闭，存在安全风险；GONOSUMDB才是按域名粒度精准关闭
Git 认证失败是私有仓库最常卡住的环节
设置了 GOPRIVATE 后，Go 会改用 Git 协议直连，此时能否成功克隆，完全取决于本地 Git 是否能认证通过。错误现象通常是：go mod tidy 卡住几秒后报 fatal: could not read Username for 'https://gitlab.example.com': No such device or address 或 SSH 报 Permission denied (publickey)。
立即学习“go语言免费学习笔记（深入）”；
- HTTPS 场景：确保
git config --global credential.helper store已启用，并且第一次手动git clone https://gitlab.example.com/team/lib登录过，凭据已缓存 - SSH 场景：检查
~/.ssh/id_rsa.pub是否已添加到 GitLab 账户；确认git clone git@gitlab.example.com:team/lib.git能成功；注意 Go 解析 URL 时会把gitlab.example.com/team/lib自动转为git@gitlab.example.com:team/lib.git，所以 SSH Config 中 Host 别名必须匹配该域名 - 别依赖
.netrc：Go 不读.netrc，只认 Git 自身的凭据系统或 SSH agent
Nexus / Artifactory 代理场景下，URL 末尾斜杠是硬性要求
如果企业用了 Nexus 搭建 Go 代理，GO_PROXY 值写错一个字符就会 404。Go 客户端拼接请求路径时不做额外处理，直接字符串连接。
- 正确写法：
go env -w GO_PROXY="http://nexus.internal:8081/repository/golang-proxy/"—— 注意结尾/必须存在 - 错误写法：
.../golang-proxy（缺斜杠）→ 请求变成http://nexus.internal:8081/repository/golang-proxygithub.com/...，404 - 如果 Nexus 开启了 Realm 认证，仅设
GO_PROXY不够，还需配置 Git 凭据或使用GO_PRIVATE+ 凭据文件，否则返回 401 HTML 页面而非模块数据
真正容易被忽略的是：这些环境变量一旦写入 go env，就对整个机器生效，不同项目无法差异化配置。多人共用开发机或 CI 环境时，必须确保 GOPRIVATE 范围足够精确，避免把本该走代理的内部开源模块也绕过去了。
