必须配GOPRIVATE声明私有模块路径前缀，否则go mod tidy会因走公共代理而卡在unknown revision或404；GO111MODULE=on是硬性前提，GOPRIVATE需精确匹配路径（如gitlab.example.com/**），且认证由git层完成，Go仅转发请求。
必须配 GOPRIVATE 告诉 Go “别走代理、别校验 checksum”，否则 go mod tidy 会卡在 unknown revision 或直接 404；而认证本身由系统 git 完成，Go 不读 .netrc、不处理 SSH 密钥，只负责转发请求。
GO111MODULE=on 是硬性前提，不是可选项
哪怕你用的是 Go 1.16+，只要当前目录在 $GOPATH/src 下，go env GO111MODULE 就可能输出 auto，此时 go mod 命令静默降级为 GOPATH 模式，所有私有配置全失效。
- 运行
go env -w GO111MODULE=on全局启用（推荐） - 验证：执行
go env GO111MODULE，输出必须是on，不能是auto或空 - 如果输出
auto，说明你在$GOPATH/src里初始化了项目——直接把项目移到任意其他空目录重试 - CI 环境中务必显式设置，别依赖“默认开启”
GOPRIVATE 必须精确匹配模块路径前缀，不支持域名通配
GOPRIVATE 是路径前缀匹配器，不是白名单。写错一个字符、漏掉 /**、逗号后带空格，都会导致匹配失败，Go 继续走公共代理并报错。
- 模块路径是
gitlab.example.com/group/lib，就得写gitlab.example.com/**（推荐），或gitlab.example.com/*（仅匹配一级子路径） - 错误写法：
*.example.com（Go 不支持）、gitlab.example.com/（缺通配符）、gitlab.example.com/**, github.com/my-team/*（逗号后空格会被截断） - 多域名严格用英文逗号分隔、无空格：
gitlab.example.com/**,gitee.com/my-team/* - 端口不能省略：模块路径含
:8443，GOPRIVATE就得写成gitlab.example.com:8443/**
认证失败不是 Go 的问题，而是 git 层没通
设置了 GOPRIVATE 只是让 Go 放行请求，真正拉代码的是你本地的 git 命令。如果 git clone https://gitlab.example.com/group/lib 失败，go mod download 一定失败。
- HTTPS 场景：用 GitLab Personal Access Token（勾选
read_repository），配~/.netrc，注意权限必须是600，且machine值与模块域名完全一致 - SSH 场景：确保
ssh -T git@gitlab.example.com能通，私钥已加入ssh-agent，并在~/.gitconfig中加 URL 重写：[url "git@gitlab.example.com:"] insteadOf = "https://gitlab.example.com/" - 别在
go.mod里写带 token 的 URL（如https://token:x-oauth-basic@gitlab...），易泄露且 vendor 后仍需运行时认证 - 自签名证书？加
GOINSECURE=gitlab.example.com（仅限开发），生产环境应把内网 CA 加入系统信任链
GOPROXY=direct 和 GONOPROXY 要配合使用
只设 GOPRIVATE 不够。如果你公司全局配置了 GOPROXY=https://nexus.company.com，Go 仍会先尝试走代理——而代理无法携带 .netrc 或 SSH 凭据，必然 401 或超时。
- 临时生效：
GOPROXY=direct go mod tidy - 全局设置：
go env -w GOPROXY=direct（推荐） - 若必须保留代理，可用
GONOPROXY单独指定跳过范围，它优先级高于GOPROXY，且值格式与GOPRIVATE一致 -
GOPRIVATE设置后会自动同步给GONOPROXY和GONOSUMDB，但显式设GOPROXY=direct更可靠
最容易被忽略的是：模块路径、GOPRIVATE 匹配串、.netrc 中的 machine、Git URL 重写中的域名，这四者必须完全一致——差一个点、一个端口、一个斜杠，整个链路就断在某个环节，报错却未必指向真实原因。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
