checksum mismatch 是 GOSUMDB 校验失败所致，非网络问题；应设 GOSUMDB=off（开发环境）或 GOSUMDB=sum.golang.org+镜像地址（如清华源），并确保 GOPROXY 与 GOSUMDB 协同配置，避免 direct 模式下仍尝试访问不可达的 sum.golang.org。
go mod download 报 checksum mismatch 或 failed to verify module
这是 GOSUMDB 校验失败的典型表现，不是网络连通问题，而是 Go 工具链在下载后比对校验和时发现不匹配。常见于：你用了国内代理（如 https://goproxy.cn），但没关掉默认校验服务器 sum.golang.org，而该服务器无法访问，导致校验流程卡死或 fallback 到不可信路径。
根本解法是明确告诉 Go：“别去 sum.golang.org 核对，我信任这个代理提供的模块”。GOSUMDB=off 最直接，但仅限开发/内网环境；更稳妥的是用可信镜像自带的校验服务，比如清华源支持 sum.golang.org 的镜像：GOSUMDB=sum.golang.org+https://mirrors.tuna.tsinghua.edu.cn/goproxy/sumdb。
-
GOSUMDB=off：禁用所有校验，速度快，适合 CI 构建或私有环境，但放弃完整性保护 -
GOSUMDB=sum.golang.org+https://mirrors.tuna.tsinghua.edu.cn/goproxy/sumdb：保留校验逻辑，只换校验地址，推荐用于日常开发 - 避免混用
GOPROXY=direct和GOSUMDB=off以外的值——direct模式下仍会尝试访问sum.golang.org，反而加剧失败
GOPROXY 配置成 direct 后 still fails with “no matching versions”
设成 GOPROXY=direct 本意是绕过代理直连源站，但实际常报 no matching versions for module 或 unknown revision。这不是配置错误，而是你本地网络根本无法解析或访问目标仓库（比如 golang.org/x/net 的 Git 地址）。
此时 direct 不是“解决方案”，而是“诊断开关”：它帮你确认问题是否真出在代理上。如果 GOPROXY=direct go mod download 依然失败，说明是 DNS、防火墙、Git 协议或 SSH 密钥问题，不是代理本身的问题。
立即学习“go语言免费学习笔记（深入）”；
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 先用
curl -v https://golang.org/x/net/@v/list测试能否访问模块元数据端点 - 若返回 404 或 timeout，说明直连路径不通，
direct无效，必须切回可用代理 - 若返回 200 但
go mod download失败，检查是否启用了GOPRIVATE错误覆盖了公共模块（例如写成了GOPRIVATE=*）
私有模块 403 或 “module not found” 但 GOPRIVATE 已设置
GOPRIVATE 不是“白名单”，而是“跳过代理和校验”的指令。如果仍报 403，大概率是：域名没写全、通配符语法错、或 Git 服务本身拒绝未认证请求。
比如你公司 GitLab 地址是 git.example.com/group/project，但只设了 GOPRIVATE=git.example.com，Go 仍会把 git.example.com/group/project 当作子路径尝试走代理——必须写成 GOPRIVATE=git.example.com/* 才生效。
- 多个私有域用逗号分隔，**不能有空格**：
GOPRIVATE=git.example.com/*,github.com/my-org/* - 通配符只支持
*，不支持**或正则；github.com/my-org不等于github.com/my-org/* - 确认 Git 服务允许 HTTPS 匿名访问，或已配置
git config --global credential.helper store缓存凭据
go mod tidy 卡住不动，但 GOPROXY 和 GOSUMDB 都对
这往往不是代理或校验问题，而是模块缓存损坏或间接依赖触发了私有路径。Go 会递归解析整个依赖树，只要其中任一传递依赖指向一个你没权限访问或已下线的私有模块，go mod tidy 就会静默卡住（无错误输出）。
快速定位方法：加 -v 参数看真实拉取行为：go mod tidy -v。输出里最后一行正在尝试 fetch 的模块，就是破口。
- 用
go list -m all | grep private扫描所有依赖中是否混入私有域名 - 临时用
GOPROXY=direct GOPRIVATE=* go mod download -v强制直连，观察哪个模块 404 - 清理缓存再试：
go clean -modcache，尤其当项目刚从 SVN 迁移或重命名过模块路径时
真正容易被忽略的，是 GOPRIVATE 的通配规则和 GOSUMDB 与 GOPROXY 的协同关系——它们不是独立开关，而是一套校验策略的两个齿轮。配错一个，另一个就可能空转甚至反向拖慢流程。
