go mod tidy 是 Go Modules 模式下最常用、最重要 的命令之一，核心作用是自动整理项目依赖 ：清理无用依赖、拉取缺失依赖、同步 go.mod 和 go.sum 文件。
它是 Go 项目开发的「依赖清洁工」，几乎所有 Go 项目都离不开它。
一、前置知识
- Go 版本 ：Go 1.11+ 支持 Modules，Go 1.16+ 默认开启 （无需手动设置
GO111MODULE）； - 项目前提 ：你的项目必须是 Go Modules 项目 （根目录有
go.mod文件）； - 核心文件 ：
go.mod：记录项目直接依赖的模块、版本；go.sum：记录依赖的哈希校验值（保证依赖完整性，无需手动修改）。
二、命令作用（一句话总结）
bash
go mod tidy- 扫描项目所有代码，找出真正用到的依赖；
- 拉取项目中缺失的依赖包；
- 删除
go.mod中未使用的依赖； - 更新
go.sum，同步所有依赖的校验值； - 自动处理依赖的间接依赖（递归整理）。
三、使用场景（什么时候用？）
这 4 种场景，直接执行 go mod tidy 即可解决问题：
- 刚克隆别人的 Go 项目，拉取所有依赖；
- 代码中新增/删除了导入包，同步依赖；
go.mod混乱、依赖报错，一键修复；- 提交代码前，清理冗余依赖，保证项目整洁。
四、完整使用步骤
步骤1：初始化 Go Modules（新项目必备）
如果你的项目没有 go.mod，先执行初始化命令（模块名自定义，通常为项目地址/项目名）：
bash
# 格式：go mod init [模块名]
go mod init my-project执行后，根目录会生成空的 go.mod 文件。
步骤2：执行 go mod tidy 整理依赖
直接在项目根目录 （go.mod 所在目录）运行命令：
bash
go mod tidy步骤3：查看效果
执行成功后：
go.mod：只保留项目实际用到的依赖；go.sum：自动生成/更新所有依赖的校验值；- 控制台无报错，依赖全部就绪。
五、进阶用法
1. 查看执行详情（调试用）
bash
go mod tidy -v-v：打印详细日志，能看到正在拉取/删除的依赖，方便排查问题。
2. 忽略本地依赖校验（特殊场景）
bash
go mod tidy -e-e：遇到错误不中断，继续整理其他依赖，适合本地开发调试。
3. 结合代理加速（国内必用）
国内拉取官方依赖很慢，先设置 Go 模块代理，再执行 tidy：
bash
# 阿里云代理（推荐）
go env -w GOPROXY=https://mirrors.aliyun.com/goproxy/,direct
# 执行整理
go mod tidy六、常见问题与解决
问题1：执行报错「cannot find module providing package...」
原因 ：依赖包地址错误/网络无法拉取。
解决：
- 检查代码导入路径是否正确；
- 配置 GOPROXY 代理（见上文）；
- 确认依赖包是公开可访问的。
问题2：执行后依赖被删除，代码报错
原因 ：go mod tidy 扫描到你没有使用 这个依赖，自动清理了。
解决 ：如果是必须依赖，在代码中正常导入使用，重新执行 go mod tidy 即可恢复。
问题3：go.sum 文件冲突（多人协作）
原因 ：多人修改依赖导致 go.sum 不一致。
解决 ：删除 go.sum，重新执行 go mod tidy 自动生成。
七、go mod tidy 与其他命令区别
| 命令 | 作用 | 适用场景 |
|---|---|---|
go mod tidy |
自动整理依赖（增/删/同步） | 日常开发、依赖修复 |
go get |
手动安装/更新指定依赖 | 单独升级某个包版本 |
go mod download |
仅下载依赖，不整理 | 离线构建、CI/CD |
核心区别 ：go mod tidy 是全自动 ，go get 是手动操作。
总结
go mod tidy= Go 项目依赖自动整理工具，无脑用即可；- 核心逻辑：用不到的删掉，缺失的拉来，文件同步好；
- 国内使用必须配代理，否则拉取依赖失败；
- 新项目克隆、代码修改依赖、提交代码前，都建议执行一次。