go mod tidy是Go项目依赖管理的核心命令，它扫描所有.go文件补全缺失依赖、删除未引用依赖、标记间接依赖并同步更新go.sum；必须在CI和pre-commit中强制执行，避免版本漂移与校验失败。
Go 项目里依赖管理不是“加完就完事”，而是要靠 go.mod 文件 + 一整套命令协同控制，否则很快会出现版本漂移、本地能跑线上炸、CI 失败等问题。
go mod init 必须指定合法模块路径
执行 go mod init 是起点，但路径写错会导致后续所有 import 出问题。模块路径不是随便起的别名，它必须满足：
• 是一个可解析的域名前缀（如 github.com/yourname/project），不能含空格或下划线
• 最好与未来代码托管地址一致，否则迁移时要改大量 import 语句
• 不要放在 $GOPATH/src 下初始化，否则可能 fallback 到 GOPATH mode（即使设置了 GO111MODULE=on 也可能被干扰）
• 如果已有 import 语句但没 go.mod，go mod init 会自动扫描并写入依赖，但不会下载——得靠 go build 或 go mod download 触发拉取
go mod tidy 是日常维护的核心命令
go mod tidy 不只是“整理依赖”，它实际做三件事：
• 扫描全部 .go 文件，补全缺失的 require 行
• 删除 go.mod 中未被任何代码引用的依赖（包括间接依赖）
• 自动标记间接依赖为 // indirect，并更新 go.sum
常见误用：
• 在 CI 流程里跳过 go mod tidy，只跑 go build → 可能漏掉新引入但未提交的依赖
• 手动编辑 go.mod 后不运行 go mod tidy → go.sum 校验和不匹配，go build 会报错
• 用 go get 更新依赖后不跟 go mod tidy → 旧版本残留，go list -m all 显示混乱
replace 和 exclude 要谨慎使用
replace 看似方便，但容易埋坑：
• 仅在 go.mod 所在模块生效，子模块不继承；跨 repo 协作时别人拉代码会因路径不存在而失败
• 替换到本地路径（如 replace github.com/a/b => ../b）后，CI 构建机上该路径不存在 → 构建中断
• 替换到私有 Git 地址时，需确保所有构建环境都配置了对应 SSH 密钥或 tokenexclude 更少用，它直接屏蔽某个版本，但若其他依赖强制要求该版本，MVS 算法会报冲突错误，不如用 replace 或升级上游依赖来得直接
立即学习“go语言免费学习笔记（深入）”；
go.sum 不是“校验文件”而是“信任锚点”
go.sum 记录每个模块版本的哈希值，作用不是“防止篡改”，而是保证：同一 go.mod 在任何机器上拉到的代码字节完全一致。
• 绝对不要手动修改 go.sum，哪怕只是删掉一行
• 如果 go build 报 checksum mismatch，说明缓存或代理返回了被污染的包，应先运行 go clean -modcache 再重试
• GOSUMDB=off 只应在离线或私有环境临时启用，生产环境禁用——它会让 Go 跳过校验，失去完整性保障
真正难的不是写对一条 go get 命令，而是让整个团队始终基于同一份 go.mod 和 go.sum 工作。只要有人绕过 go mod tidy 直接改代码再提交，或者用不同 Go 版本生成 go.sum，问题就会悄悄积累。最稳妥的做法：把 go mod tidy 加进 pre-commit hook，且 CI 流程第一步就是校验 go.mod 和 go.sum 是否干净。
