go mod tidy 仅同步 go.mod 和 go.sum,移除未引用模块声明,但不清理 $gopath/pkg/mod 缓存;真正释放磁盘空间需用 go clean -modcache,它彻底删除缓存目录下所有模块文件,包括 .zip、解压源码及校验文件。

go mod tidy 只删 go.mod 里的 require,不碰磁盘上的模块文件
它只负责同步 go.mod 和 go.sum,移除未被 import 引用、也非传递依赖的模块声明。但 $GOPATH/pkg/mod 里那些已下载却不再需要的 zip 包、解压源码、校验文件(如 .info、.ziphash)全留着——它们不会自动消失。
常见误判是:运行完 go mod tidy 后 go list -m all 显示的模块数变少了,就以为磁盘空间也释放了。其实只是 go.mod 干净了,缓存目录可能还躺着几十个旧版本。
- 执行前先确认当前目录有
go.mod,否则命令无效 - 它会保留
// indirect标记的模块——哪怕你没直接 import,只要被其他依赖链引用,就不会删 - 构建标签(如
// +build linux)屏蔽的 import 不会被扫描,对应依赖也不会被移除
go clean -modcache 是唯一能清空 $GOPATH/pkg/mod 的命令
go clean -modcache 会彻底删除 $GOPATH/pkg/mod(或 $GOROOT/pkg/mod,当 GOPROXY=off 且未设 GOPATH 时)下的所有内容:每个模块的 .zip、解压后的源码目录、cache/download/ 下的 .info 和 .ziphash 文件。但它不碰项目里的 go.mod、go.sum,也不删 vendor/。
清理后首次 go build 会慢,因为要重下所有依赖;但这是真正释放磁盘空间的唯一可靠方式。如果你发现 $(go env GOPATH)/pkg/mod 占用超 10GB,而 go list -m all | wc -l 不到 50 行,基本就是缓存积压了。
- CI 环境建议每次构建前加这句,避免跨构建污染
- 执行后可通过
go build -v ./观察每行开头的Fetching,确认拉取地址是否符合预期(比如走私有代理) - 别手动
rm -rf $(go env GOPATH)/pkg/mod—— 它可能残留锁文件或破坏校验一致性
如何精准清理,而不是全量重下
全清 -modcache 简单,但团队协作中会造成重复下载带宽浪费。更精细的做法是只删“当前项目根本不用”的模块缓存。
先提取当前实际依赖列表:
go mod graph | awk '{print $1}' | sort -u > used_modules.txt
再对比缓存目录里的域名结构(比如 $(go env GOPATH)/pkg/mod/cache/download/github.com/ 或私有域名),手动删掉不在 used_modules.txt 中的子目录。公共模块可配合 go mod tidy -v 后再清,因为 tidy 会先剔除 go.mod 中冗余项,缩小后续清理范围。
- 私有模块务必确认
go env GOPRIVATE已设置,否则清理后go get可能跳过校验拉错版本 - 别删
cache/download/外层目录(如github.com),只删其下具体模块路径,避免误伤其他项目依赖 - 执行前建议跑一次
go list -m -json all > deps.json,保留结构化快照,方便回溯
清理后仍拉错版本?检查 GOPROXY 和 GOSUMDB 配置
清理模块缓存不等于重置代理和校验策略。如果清理后 go build 拉到的版本和 go.mod 声明不一致,大概率是 GOPROXY 或 GOSUMDB 配置残留导致。
典型现象:启用 Nexus 私有代理后频繁报 checksum mismatch,但 go env GOSUMDB 还是默认的 sum.golang.org —— 说明本地缓存的校验数据与代理返回不匹配。
- 临时验证:运行
GOPROXY=direct GOSUMDB=off go mod download,绕过代理和校验强制重拉 - 长期建议:设
export GOPROXY=https://goproxy.cn,direct,逗号分隔多个代理,direct保证私有模块回源 - 重装 Go 后记得检查
go env GOSUMDB,若曾设为off或私有地址,需手动恢复为sum.golang.org
GOPROXY、GOSUMDB、GOPRIVATE 这三个环境变量,比缓存本身更容易被忽略。golang免费学习笔记(深入):立即使用
在学习笔记中,你将探索golang的核心概念和高级技巧!











