go mod download 报 module not found 或 checksum mismatch 的根本原因是 GOPROXY 未显式包含 direct 且置于末尾，或 GOPRIVATE、GOSUMDB 配置不匹配导致代理 fallback 失效、私有模块绕过失败、校验直连海外服务器；必须用 go env -w 统一设置并验证三者协同生效。
go mod download 报 module not found 或 checksum mismatch
根本不是代码或网络本身的问题，而是 Go 在代理返回 404 或不可用时，不会自动 fallback 到 direct——它直接报错。关键点在于 GOPROXY 必须显式包含 direct，且必须放在逗号分隔列表的末尾。
常见错误写法：GOPROXY=https://goproxy.cn（缺 direct）、GOPROXY=direct,https://goproxy.cn（direct 在前，无效）。
- 正确写法：
go env -w GOPROXY=https://goproxy.cn,direct - 若用 Nexus/JFrog 等私有代理，同样要加
,direct，否则私有模块一概拉不到 -
go mod download -x可看到每条请求实际走哪个地址，验证是否真走到了direct
GOPRIVATE 没设或设错导致 403 / unknown revision
Go 默认把所有模块当公开处理，GOPRIVATE 不是“可选优化”，而是私有模块拉取的开关。它不解决认证问题，但控制 Go 是否绕过代理和校验——没它，go get 根本不会尝试走 Git 协议。
典型错误：设成 example.com，但模块路径是 git.example.com/internal/lib——不匹配，失效。
立即学习“go语言免费学习笔记（深入）”；
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 必须精确匹配域名，含端口也要写全，如
git.example.com:8443 - 支持
*前缀通配，如github.com/my-org/*，但*.example.com不匹配example.com - 多个域名用英文逗号分隔，严禁空格：
go env -w GOPRIVATE=git.internal.company,github.com/my-team/* - 设完后运行
go env GOPRIVATE确认输出，再试go list -m all
GOSUMDB 和 GONOSUMDB 混用引发校验失败
GOPROXY 配好了，GOPRIVATE 也对了，但 go build 还卡在 verifying ... checksum mismatch？大概率是 GOSUMDB 没关或没配对。
国内镜像（如 goproxy.cn）不提供 sumdb 服务，Go 仍会直连 sum.golang.org，而这个地址在国内基本不可达。
- 开发/测试环境最简方案：
go env -w GOSUMDB=off - 生产环境需保留校验：部署内网
sum.golang.org镜像（如 goproxy 的-sum模式），再设GOSUMDB=https://goproxy.internal/sum - 若只排除部分私有域名校验，用
GONOSUMDB，且值必须与GONOPROXY完全一致（不是GOPRIVATE）
VS Code / CI 环境里 GOPROXY 不生效
本地终端能 go mod download 成功，但 VS Code 插件安装失败、CI 构建卡住——大概率是 IDE 或构建环境没继承你的 shell 环境变量。
VS Code 默认启动终端可能读取自己的配置，CI 脚本常以 clean shell 启动，go env 输出和你预期不符。
- 在 VS Code 终端里直接执行
go env -w GOPROXY=...，别只在系统 shell 设 - CI 脚本开头显式设置：
go env -w GOPROXY=https://goproxy.cn,direct GOSUMDB=off - CI 中启用
vendor不等于跳过校验：go build仍会访问远程 sumdb，必须同时设GOSUMDB=off - 排查时优先跑
go env | grep -i proxy\|sum\|private，确认当前上下文真实生效的值
GOPROXY、GOPRIVATE、GOSUMDB 三者之间的逻辑关系没对齐——比如 GOPRIVATE 覆盖了域名，但 GOSUMDB 还在强行校验；或者 GOPROXY 包含 direct，但 CI 环境压根没加载这行配置。动手前先看 go env，比猜更省时间。 
