GO111MODULE=off 是模块失效的主因，需显式设为 on；GOPRIVATE 与 GONOSUMDB 必须精确匹配私有域名并同步配置；go clean -modcache 仅清模块缓存，必要时手动清理 $GOPATH/pkg/mod 下载及解压目录。
GO111MODULE=off 导致模块行为完全失效
最常见却最容易被忽略的问题：项目根目录有 go.mod，但执行 go build 时仍走 GOPATH 模式，replace 不生效、go.sum 被跳过、私有库拉取失败。根本原因是环境变量 GO111MODULE 被设为 off 或未显式启用。
验证方式：go env GO111MODULE 必须输出 on；若为 auto，在无 go.mod 的目录下会退化为 off，不可靠。
- CI/CD 中常因 shell 初始化不一致导致该变量缺失，务必在构建脚本开头显式设置：
export GO111MODULE=on - IDE（如 VS Code）可能继承系统默认值，需检查 Go 扩展配置或工作区设置
go version 默认不启用模块模式，升级 Go 版本是硬性前提
GOPRIVATE 配置不匹配私有域名规则
私有仓库依赖报错 module github.com/your-org/internal/pkg: reading github.com/your-org/internal/pkg/@v/list: 404 Not Found，不是网络问题，而是 Go 仍试图走 proxy.golang.org，因为 GOPRIVATE 没覆盖实际域名。
GOPRIVATE 是 glob 模式，不支持正则，且**必须精确匹配导入路径前缀**。例如：
- 导入路径是
git.example.com/team/repo→GOPRIVATE=git.example.com✅ - 导入路径是
git.example.com/team/repo/v2→GOPRIVATE=git.example.com/*✅（通配符需带/*） - 错误写法：
GOPRIVATE=*.example.com❌（不支持*在开头） - 错误写法：
GOPRIVATE=git.example.com/team❌（只匹配前缀，/team后无法再匹配/repo）
多域名用逗号分隔：GOPRIVATE=git.example.com,github.company.internal。
GONOSUMDB 与 GOPRIVATE 必须同时配置
仅设 GOPRIVATE 不足以让私有模块跳过校验——Go 仍会尝试从 sum.golang.org 查询 checksum，超时或 404 会导致 go get 失败。此时需同步设置 GONOSUMDB。
-
GONOSUMDB规则与GOPRIVATE完全一致，必须一模一样 - 漏配
GONOSUMDB时典型报错：failed to load mod file: no sum found for module - 两者都需在 CI 环境、Dockerfile 和本地开发环境统一设置，避免“本地能跑，CI 报错”
go clean -modcache 清理不彻底的残留缓存
执行 go clean -modcache 后仍拉取旧版本？因为 Go 的模块缓存分两层：全局 $GOCACHE（含编译产物）和模块下载缓存（$GOPATH/pkg/mod）。前者不影响依赖解析，后者才是关键。
- 真正要清的是
$GOPATH/pkg/mod目录，go clean -modcache只清这一处，但有时权限或挂载问题导致删除失败 - 更可靠做法：
rm -rf $GOPATH/pkg/mod/cache/download/*（清下载缓存） +rm -rf $GOPATH/pkg/mod/zip/*（清解压副本） - 若使用
go work，还需检查go.work中各子模块的独立pkg/mod缓存路径 - 清理后务必重新运行
go mod tidy，否则go.sum里的旧校验和仍可能触发校验失败
配置类冲突最难调试，因为它不报具体模块名，只表现为“找不到包”或“校验失败”。重点盯住 GO111MODULE、GOPRIVATE、GONOSUMDB 三者的值和作用范围，比查 go mod graph 更优先。
