Go模块加载问题应优先使用go list -m -u -graph和go mod edit -print诊断，前者揭示模块树与版本冲突，后者显示真实生效的replace/exclude；配合go mod download -v、go mod verify及GODEBUG=gomodcache=1可精准定位缓存、校验与代理问题。
Go 模块加载问题通常表现为 go build 或 go run 报错找不到包、版本冲突、replace 不生效，或 go list -m all 输出与预期不符。调试核心不是“打日志”，而是用好 Go 自带的模块诊断命令和环境变量。
看清楚当前模块树和依赖版本用 go list -m -u -graph
这个命令能直观暴露模块嵌套关系、升级建议和实际加载路径。比 go mod graph 更易读，且带版本号和更新提示。
常见错误现象：明明 go.mod 里写了 require example.com/lib v1.2.0，但运行时却加载了 v1.1.0 —— 很可能是某个间接依赖强制拉低了版本。
- 加
-u显示可升级版本（含[newest]标记） - 加
-json可配合jq过滤，比如查某模块是否被多个路径引入：go list -m -u -json all | jq 'select(.Path == "github.com/sirupsen/logrus")'
- 不加
-u时，若某模块显示为indirect，说明它未被主模块直接 require，而是由其他依赖带入
强制触发模块下载和校验用 go mod download -v 和 go mod verify
当 go build 卡在 “Downloading” 或报 checksum mismatch，说明本地缓存或 proxy 返回的模块内容与 go.sum 不符。此时不能只删 go.sum 重生成。
立即学习“go语言免费学习笔记（深入）”；
-
go mod download -v会打印每个模块的来源（direct/proxy.golang.org/insecure）、校验和比对结果，快速定位哪一环出问题 -
go mod verify单独校验所有已下载模块是否匹配go.sum，失败时会明确指出哪个模块哈希不一致 - 若用私有仓库，确保
GOPRIVATE=*.corp.example.com已设置，否则 Go 仍会尝试走 proxy 并校验失败
排查 replace 和 exclude 是否生效用 go mod edit -print
go.mod 文件里的 replace 和 exclude 是静态声明，但实际加载时可能被 vendor、GOFLAGS=-mod=readonly 或多层 replace 覆盖。直接看文件不如看 Go 解析后的结果。
-
go mod edit -print输出 Go 当前解析出的完整模块图（含生效的 replace 目标路径和版本），不含注释，是真实加载依据 - 如果发现
replace old.com/lib => ./local-lib没出现，检查是否漏了go mod tidy，或者./local-lib下没有go.mod（replace 到本地路径必须是有效模块） -
exclude只影响go list -m all和构建时的版本选择，不影响go get；若想彻底禁用某模块，用replace指向空目录更可靠
启用模块加载详细日志用 GODEBUG=gomodcache=1
这是最底层的调试开关，会打印每一个模块的查找路径、缓存命中/未命中、checksum 计算过程，适合定位“为什么没走 replace”或“为什么从 proxy 下载而非本地 cache”。
- 执行前先清空模块缓存避免干扰：
go clean -modcache - 典型输出片段：
GODEBUG=gomodcache=1 go list -m github.com/gorilla/mux gomodcache: find github.com/gorilla/mux@v1.8.0 in /Users/me/go/pkg/mod/cache/download/github.com/gorilla/mux/@v/v1.8.0.info gomodcache: read /Users/me/go/pkg/mod/cache/download/github.com/gorilla/mux/@v/v1.8.0.info: &{Version:v1.8.0 Path:github.com/gorilla/mux Origin:{URL:}} - 注意：该日志不显示
replace的重写逻辑，仅反映缓存层行为；要确认 replace 是否参与解析，仍需结合go mod edit -print
真正卡住的时候，别急着改 go.mod，先跑一遍 go list -m -u -graph 和 go mod edit -print —— 90% 的“模块加载异常”其实是版本约束链比你想象的更复杂，而 Go 的解析规则是确定的，只是没被看见。
