go clean -modcache是清空本地模块缓存的唯一标准命令，删除$gomodcache下所有已下载的模块源码、.zip包和校验数据，不影响go.mod、go.sum及vendor/目录。
go clean -modcache 是清空本地模块缓存的唯一标准命令
它删的是 $GOMODCACHE（默认为 $GOPATH/pkg/mod）下所有已下载的模块源码、.zip 包和校验数据，不是 go.mod 或 go.sum，也不动 vendor/ 目录。执行后首次 go build 会重下依赖，但项目逻辑完全不受影响。
常见错误现象：
-
cannot find module providing package xxx—— 实际是缓存损坏或版本错乱，不是路径问题 -
checksum mismatch且反复出现 —— 本地缓存的.info文件和远程不一致 -
go list -m all显示的版本和go.mod对不上 —— 缓存没刷新，工具链读了旧快照
实操建议：
- 先确认
GO111MODULE=on，否则go clean -modcache静默无效 - 别在发布前临时跑，重下载耗时不可控；CI 环境中建议固定用干净缓存 +
go mod download预热 - 想彻底清，就直接运行：
go clean -modcache；想留部分模块，手动删更安全：rm -rf $GOMODCACHE/github.com/xxx@v1.2.3和$GOMODCACHE/cache/download/github.com/xxx - 清理完立刻跑
go mod verify，确保后续拉取的模块仍匹配go.sum
为什么 go mod tidy 不能代替 go clean -modcache
go mod tidy 只改 go.mod 和 go.sum，它不会碰磁盘上已存在的模块文件。即使你删光了 go.mod 里的所有 require，$GOPATH/pkg/mod 里几百 MB 的旧版本依然原封不动。
常见误判场景：
- 执行
go mod tidy后du -sh $GOPATH/pkg/mod没变小 → 正常，tidy 不负责磁盘清理 - 换机器后
go build很慢，以为是网络问题 → 实际是go mod tidy触发了全量重下，因为新环境modcache为空 - 怀疑某模块被污染，只跑
tidy就去测试 → 缓存里的坏 zip 还在，问题复现
实操建议：
- 要释放磁盘空间或排除缓存干扰，必须用
go clean -modcache - 想最小化重下载范围，可先
go mod tidy -v看哪些模块被保留，再针对性删$GOMODCACHE下未列出的目录 -
go mod vendor后再清理modcache完全安全，vendor 是独立副本
清理后构建变慢是正常现象，不是命令失败
go clean -modcache 后第一次 go build 必然变慢，因为所有模块都要重新下载、解压、校验、编译。这不是命令出错，而是缓存重建的必经阶段。
容易踩的坑：
- 看到
Fetching github.com/xxx日志就中断构建 → 中断后缓存不完整，下次还可能报checksum mismatch - 在 CI 中未设
GOPROXY，又清了缓存 → 所有模块直连 GitHub，超时风险陡增 - 清理后没验证
go mod verify，就合并 PR → 后续拉取的模块可能绕过校验，引入不一致
实操建议：
- 加
-v参数观察真实拉取路径：go build -v ./...，每行开头的Fetching就是实际地址 - 私有模块务必提前配好
go env GOPRIVATE=*.internal.company.com，否则清理后go get可能跳过校验 - 若磁盘空间紧张，清理前可用
go list -m -json all > deps.json快照当前依赖树，避免重下时混淆来源
别把 go clean -cache 和 go clean -modcache 搞混
go clean -cache 删的是 $GOCACHE（默认 $HOME/Library/Caches/go-build）下的 .a 编译中间产物；go clean -modcache 删的是 $GOMODCACHE 下的模块源码。两者完全无关，混用等于白干。
典型错误操作：
- 遇到
cannot find module却跑go clean -cache→ 无济于事，模块根本不在$GOCACHE里 - 想释放
pkg/mod空间却只跑go clean（无参数）→ 只删当前包的.a文件，对模块缓存零影响 - 设了
GOCACHE=off还指望-cache有效 → 命令直接跳过，什么也不做
实操建议：
- 查路径用
go env GOCACHE和go env GOMODCACHE，别猜 - 真要彻底清
$GOCACHE，得用：rm -rf $(go env GOCACHE)/*（注意末尾/*，别漏） - 清理
modcache前，检查go env GOPROXY是否生效，避免重下时卡死
go.mod 已删某模块，但 pkg/mod 里还躺着 v0.1.0 和 v0.2.0 两个版本，而 go list -m all 只显示 v0.2.0。这种残留不会报错，但会悄悄占用空间、干扰调试，只能靠定期 go clean -modcache 或脚本扫描清理。golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
