Golang模块缓存清理方法及安全操作指南
goclean-modcache只删除$GOPATH/pkg/mod(或GOPROXY未设时的$HOME/go/pkg/mod)下的所有已下载模块、校验和文件(sum.db)、解压源码及zip缓存,不触碰项目内的go.mod、go.sum或vendor/目录。
go clean -modcache 只删除 $GOPATH/pkg/mod(或 GOPROXY 未设时的 $HOME/go/pkg/mod)下的所有已下载模块、校验和文件(sum.db)、解压源码及 zip 缓存,不触碰项目内的 go.mod、go.sum 或 vendor/ 目录。

执行 go clean -modcache 会删掉哪些文件
它只清除 $GOPATH/pkg/mod(或 GOPATH 未设置时的 $HOME/go/pkg/mod)下的所有已下载模块,包括校验和文件(sum.db)、解压源码、zip 缓存。不会碰你项目里的 go.mod、go.sum 或本地 vendor/ 目录。
常见错误现象:运行后 go build 变慢、CI 第一次拉包耗时飙升——这不是删错了,是缓存清空后的正常回源行为。
- 如果你用的是 Go 1.18+ 且设置了
GOPROXY=direct,清理后所有依赖都会重新从原始仓库 clone,网络差时容易卡在verifying github.com/xxx@v1.2.3 go mod download不会自动重建缓存,得等下次go build或手动跑一遍才补全- Windows 下若某模块正被 IDE(如 VS Code 的 gopls)锁住,
go clean -modcache可能报错并跳过该目录,但不影响其他模块
什么时候必须用 go clean -modcache
不是“定期清理有益”,而是遇到特定问题才需要它。多数时候缓存损坏比磁盘占用更值得警惕。
- 出现
invalid version: unknown revision,但git ls-remote能看到对应 tag——大概率是本地缓存里存了旧的 commit hash 映射,删了重下就恢复 go list -m all列出的版本和go.mod里写的不一致,且go mod tidy无法修正- 升级 Go 版本后,某些模块编译失败,错误指向
internal/module类路径,说明缓存里混了不同 Go 版本生成的构建产物
go clean -modcache 和 go mod vendor 冲突吗
不冲突,但行为逻辑相反:前者删远端缓存,后者把远端模块拷进本地 vendor/。清理完再 go mod vendor 是安全的,但要注意:
vendor/不受-modcache影响,删了它也不会动 vendor 里的代码- 如果项目启用了
GO111MODULE=on且没设-mod=vendor,清理缓存后go build默认仍走pkg/mod,不会自动 fallback 到 vendor - 想验证 vendor 是否完整,用
go list -mod=vendor -f '{{.Dir}}' std比单纯看目录存在更可靠
替代方案:不删整个缓存,只清理特定模块
全局清缓存太粗暴。Go 本身不提供按模块清理命令,但可以手动删子目录,更精准也更安全。
比如要清理 github.com/sirupsen/logrus 的所有版本缓存:
rm -rf $GOPATH/pkg/mod/github.com/sirupsen/logrus@*
注意路径里的 @ 是字面量,不是通配符占位符;macOS 上用 rm -rf $HOME/go/pkg/mod/github.com/sirupsen/logrus@*。
- 删之前先
go list -m github.com/sirupsen/logrus确认当前解析到的版本,避免删错活跃版本 - Windows PowerShell 用户别用
Remove-Item直接删@v1.9.0这种带点的目录名,容易因特殊字符报错,建议进资源管理器手动删或改用 WSL - 删完立刻
go mod download github.com/sirupsen/logrus补单个模块,比等go build触发全量恢复快得多
缓存路径本身不加密、不压缩,但模块目录名含哈希值,人工识别成本高;真要批量清理,与其写脚本遍历,不如接受“清完重下”是 Go 模块机制设计的一部分。


































