go clean -modcache 删除 GOPATH/pkg/mod 或 GOROOT/pkg/mod 下所有模块 zip 包、解压源码及校验文件，不删 go.mod、go.sum 和 vendor/；清理后首次构建会重下模块。
go clean -modcache 会删除哪些文件
go clean -modcache 清空的是 Go 安装目录下 GOPATH/pkg/mod（或 GOROOT/pkg/mod，若启用了 GOPROXY=off 且未设 GOPATH）中所有已下载的模块 zip 包、解压后的源码目录和校验文件（cache/download 下的 .info/.zip/.ziphash）。它不会动你项目里的 go.mod 或 go.sum，也不会删 vendor/（如果存在）。
常见误判是以为执行后 go build 会失败——其实不会，下次构建时会按需重新下载，只是首次变慢。真正影响开发节奏的是：CI 环境反复拉包、磁盘空间告急、或怀疑某模块缓存损坏导致 go get 行为异常。
什么时候必须手动清理 modcache
以下情况建议直接运行 go clean -modcache：
- 遇到
invalid version: unknown revision且确认远程 tag 存在，大概率是本地缓存里残留了旧的info文件，没同步最新 commit hash -
go list -m all显示的版本和go.mod声明不一致，尤其在切换分支或回退go.mod后 - 磁盘
/tmp或$HOME/go/pkg/mod占用超 10GB，而项目实际依赖不到 50 个模块 - 启用私有代理（如 Nexus、JFrog）后频繁报
checksum mismatch，且go env GOSUMDB是默认值（sum.golang.org），说明本地缓存校验数据与代理返回不匹配
清理前如何安全备份关键信息
不需要备份整个 pkg/mod，但建议保留两样东西，避免重下时混淆来源：
立即学习“go语言免费学习笔记（深入）”；
- 当前项目的
go.mod和go.sum—— 它们定义了精确依赖树 - 运行
go list -m -json all > deps.json，生成结构化依赖快照，含每个模块的Version、Replace和Indirect标记，比纯文本更可靠 - 若使用私有模块，确认
go env GOPRIVATE已正确设置，否则清理后go get可能因跳过校验而拉错版本
执行清理后，首次 go build 会重建缓存，此时可加 -v 观察模块下载路径：go build -v ./... 中每行开头的 Fetching 就是真实拉取地址。
替代方案：只删不用的模块而非全清
全量清理简单粗暴，但团队协作中可能造成重复下载带宽浪费。更精细的做法是：
- 用
go mod graph | awk '{print $1}' | sort -u > used_modules.txt提取当前项目直接/间接引用的所有模块名 - 对比
ls $GOPATH/pkg/mod/cache/download下的域名目录，手动删掉不在列表中的私有域名缓存（例如git.internal.company.com下已下线的老项目） - 对公共模块，定期运行
go mod tidy -v，它会自动移除go.mod中未引用的require条目，后续go clean -modcache的范围就自然缩小
注意：go mod vendor 生成的 vendor/ 不受 go clean -modcache 影响，但若你依赖 vendor 机制，清理缓存后务必重新运行 go mod vendor 同步变更。
最常被忽略的一点：Windows 用户要注意 %USERPROFILE%\go\pkg\mod 路径下可能有隐藏的 .git 目录（某些模块自带），直接删缓存时别手抖 rm -rf 整个 mod 目录，否则可能误删自己 clone 的模块源码。
