go mod tidy 是 Go 模块（Go Modules）核心命令之一，其核心作用是自动整理项目的依赖关系，让 go.mod 和 go.sum 文件与项目实际代码中的依赖需求保持一致，是管理 Go 项目依赖的高频基础操作。
核心功能拆解
1. 清理无用依赖
- 移除
go.mod中声明但项目代码（包括导入、测试代码）未实际使用的依赖模块（及对应版本）； - 清理
go.sum中无任何依赖引用的校验和条目，减少冗余。
2. 补充缺失依赖
- 扫描项目代码中
import导入但未在go.mod中声明的依赖； - 自动下载这些缺失依赖的最小兼容版本（优先遵循语义化版本，无显式版本时取最新稳定版），并将其添加到
go.mod和go.sum中。
3. 校验依赖一致性
- 验证
go.sum中记录的依赖校验和与实际下载的依赖文件是否匹配，防止依赖被篡改； - 确保
go.mod中require、replace、exclude等指令的逻辑自洽。
典型使用场景
- 新项目初始化后：写完代码首次执行
go mod tidy，自动识别并下载所有导入的依赖； - 删除 / 修改导入语句后：清理不再使用的依赖，避免
go.mod臃肿； - 协作开发时：拉取他人代码后执行，快速同步缺失的依赖（替代手动
go get）； - 修复依赖冲突：部分场景下可自动修正因依赖版本不兼容导致的轻微冲突（复杂冲突仍需手动调整）。
关键细节
- 版本选择规则：补充依赖时，默认选择满足项目需求的「最低兼容版本」（若需指定版本，需手动
go get <module>@<version>后再执行tidy）； - 不会修改手动指定的版本：若你已显式在
go.mod中声明某个依赖的版本（如require github.com/gin-gonic/gin v1.9.1），tidy不会擅自升级 / 降级，仅确保该版本被保留； - 生成 / 更新文件：执行后会更新
go.mod（依赖列表）和go.sum（依赖校验和），同时下载依赖到本地模块缓存（默认$GOPATH/pkg/mod）； - 离线模式：若需在无网络环境执行，可加
-mod=readonly标记（go mod tidy -mod=readonly），仅检查依赖一致性，不下载缺失依赖（缺失则报错）。
示例对比
执行前（冗余 + 缺失依赖）
go.mod 内容：
module myproject
go 1.21
require (
github.com/gin-gonic/gin v1.9.1 // 实际代码已删除导入（冗余）
github.com/google/uuid v1.3.0 // 代码中未导入（冗余）
)
代码中实际导入：import "github.com/shopspring/decimal"（未在 go.mod 中声明）
执行 go mod tidy 后
go.mod 自动更新：
module myproject go 1.21 require github.com/shopspring/decimal v1.3.1 // 自动添加缺失依赖（最新兼容版）
- 冗余的
gin、uuid被移除； - 缺失的
decimal被添加，且自动下载对应版本； go.sum仅保留decimal的校验和。
注意事项
go mod tidy不会删除本地模块缓存（$GOPATH/pkg/mod），仅修改go.mod/go.sum；- 若项目依赖私有模块（如企业内网仓库），需提前配置
GOPRIVATE环境变量，否则tidy可能无法拉取依赖； - 对于多模块项目（monorepo），需在每个模块目录下分别执行，或使用
go work管理。
总结：go mod tidy 是 Go 项目依赖管理的「一键校准工具」，确保依赖声明与实际代码需求完全匹配，是日常开发中不可或缺的操作。