go clean -modcache 仅清理 $gopath/pkg/mod 缓存，不清理 go.sum、本地 replace 副本或 $gocache 中的编译产物，残留内容易导致 checksum mismatch 或静默拉取错误版本。
为什么 go clean -modcache 不能真正清理干净
它只清 $GOPATH/pkg/mod 缓存，但不会动 go.sum、本地 replace 指向的模块副本、或被 go build 临时写入 $GOCACHE 的编译产物。残留的旧 checksum、失效的 replace 路径、混杂的 vendor 内容，都会让后续 go mod download 行为异常——比如报 checksum mismatch 或静默拉取错误版本。
- 先手动删掉
$GOCACHE（通常在$HOME/Library/Caches/go-buildmacOS /%LOCALAPPDATA%\Go\CacheWindows /$HOME/.cache/go-buildLinux） - 删掉项目根目录下的
vendor/（如果存在且你不用 vendor 模式） - 删掉
go.sum—— 不要保留旧校验和，重构环境就得从零验证 - 运行
go clean -modcache，确认$GOPATH/pkg/mod已空
如何安全重置 go.mod 并避免隐式依赖污染
直接 go mod init 会保留当前目录下所有 .go 文件的 import 路径推断，容易把本该被排除的测试文件、旧工具代码、甚至 vendor 里残留的包也拉进来。更稳妥的做法是先隔离源码再重建。
- 把真正要构建的
main.go和核心业务包挪到新空目录（比如./clean-src/） - 在新目录执行
go mod init example.com/myapp（用真实模块路径，别用mod这种占位符） - 用
go list -m all检查是否只有你显式 import 的包 —— 如果出现意外模块，说明某处 import 了不该存在的路径（比如github.com/xxx/oldutil） - 删掉
replace语句，除非你明确需要本地调试某个 fork；否则它们会锁死版本并绕过官方校验
go mod download 失败时最该查的三件事
不是网络问题，大概率是本地环境残留或模块元数据不一致。尤其当你刚清过缓存又遇到 no required module provides package，基本是 go.sum 和实际下载内容对不上。
- 确认
GO111MODULE=on已设置（go env -w GO111MODULE=on），关掉 GOPATH mode 才能严格走 module 规则 - 检查
go.mod里有没有带// indirect标记却没被任何代码 import 的模块 —— 它们可能是旧依赖残留，用go mod graph | grep定位源头 - 遇到 checksum mismatch？不要
go mod download -dirty，而是删掉对应模块在$GOPATH/pkg/mod/cache/download/下的整个子目录，再重试
重构后验证依赖是否“真干净”的两个命令
光看 go.mod 文件行数没用。真正的干净是：可复现、无副作用、不依赖本地路径。
- 运行
go mod verify—— 必须返回空（无输出），否则说明go.sum与当前模块内容不匹配 - 运行
go list -deps -f '{{.Module.Path}} {{.Module.Version}}' ./... | sort -u—— 输出应全是标准语义化版本（如v1.12.0），不含devel、latest或本地路径（../some-local-pkg）
重构这事，最难的不是删文件，而是识别哪些 import 是历史包袱、哪些 replace 是临时方案却已固化成事实标准。每次 go mod tidy 前，最好先 git status 看一眼 go.mod 和 go.sum 是否真的只变了预期内容。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
