go mod tidy 不拉新依赖但构建报 missing module，通常是模块缓存残留旧元数据导致工具链误判依赖已存在；应先验证 go.mod 路径合规，再执行 go clean -modcache 和 go mod download 重建缓存。
go mod tidy 不拉新依赖，但构建报 missing module
这通常不是 go mod tidy 失效，而是缓存里残留了旧的模块元数据（比如 .info 文件没更新），导致 Go 工具链“以为”依赖已就位，实际却找不到对应源码或校验失败。
- 先确认当前目录有
go.mod且路径不含中文、空格或符号；pwd看一眼再执行命令 - 运行
go mod verify—— 如果报错invalid version: unknown revision或checksum mismatch，基本可断定缓存损坏 - 不要直接
go get补包，先清缓存：go clean -modcache - 再跑
go mod download，观察输出是否真实开始拉取；加-v可看具体 URL 来源
切换 GOPROXY 后构建失败，提示 checksum mismatch
私有代理和公共代理返回的同版本模块 zip 包可能内容不同（比如签名方式、时间戳），但 go.sum 只记录了最初拉取时的校验和。缓存混存会导致校验不通过。
- 必须清掉
$GOMODCACHE：执行go clean -modcache - 检查
go env GOPROXY是否生效，尤其注意direct是否在末尾（如https://goproxy.cn,direct） - 若用私有代理，确保
go env GOPRIVATE已设（如go env -w GOPRIVATE=git.internal.company.com），否则 Go 会跳过校验直接走 proxy - 清理后首次
go build会慢，但后续就稳定了
改了 replace 路径，但 go build 还是用旧代码
replace 生效的前提是模块缓存未被绕过。如果本地 pkg/mod 里已有该模块的原始版本，Go 可能优先用它，而不是你指定的本地路径。
- 确认
go.mod中replace语法正确，例如：replace github.com/foo/bar => ./local/bar - 执行
go mod edit -print验证替换是否被解析（输出里应出现replace行） - 删掉
$GOMODCACHE/github.com/foo/bar@vX.Y.Z对应目录（或直接go clean -modcache） - 加
-mod=readonly构建：go build -mod=readonly -o ./app .，防止意外触发网络下载覆盖本地路径
CGO_ENABLED 切换后链接失败，undefined reference
这不是模块缓存问题，而是构建缓存（$GOCACHE）里混存了不同 CGO 模式下的 .a 文件。链接器找不到 C 符号，但错误信息常不明确。
立即学习“go语言免费学习笔记（深入）”；
- 运行
go clean -cache清构建缓存，不是-modcache - 检查当前环境变量：
echo $CGO_ENABLED，确保和你要构建的目标一致 - 如果同时要支持 CGO 和非 CGO 构建，建议分开目录或加前缀构建，避免缓存污染
-
go build -x输出中若看到cached字样，说明缓存被复用；没看到则说明已重建
-modcache 却忘了 -cache，或者清完没重跑 go mod download 就直接构建。 
