go mod tidy 仅补全缺失 require 和删除未使用依赖，不解决版本兼容性、弃用模块或间接依赖升级问题，易引发线上故障。
go mod tidy 不能解决所有依赖漂移问题
很多人以为执行 go mod tidy 就算完成了依赖生命周期管控，其实它只做两件事：补全缺失的 require、删掉未使用的依赖。但它不检查版本兼容性、不识别已弃用模块、也不阻止间接依赖悄悄升级——这些才是持续演进中真正引发线上故障的源头。
常见错误现象包括：go build 成功但运行时报 undefined: somefunc，或单元测试突然失败，根源往往是某个子依赖在没声明的情况下升了主版本（比如 github.com/some/lib v1.5.0 → v2.0.0），而 Go Modules 默认不自动适配 v2+ 的路径变更。
- 每次 PR 合并前必须跑
go list -m all | grep -E "(v[2-9]|-beta|-rc)"，主动筛查非 v1 主版本依赖 - 对关键基础库（如
golang.org/x/net、golang.org/x/sys）加// +build ignore注释并人工核对变更日志 - 禁止直接
go get github.com/xxx@latest，一律用go get github.com/xxx@v1.x.y显式指定语义化版本
replace 指令不是临时补丁，而是版本锚点
replace 常被当成“先顶一下”的权宜之计，但在大型项目里，它实际承担着版本锚点功能：把某模块锁定到特定 commit 或 fork 分支，防止上游意外发布破坏性更新影响整个依赖树。
使用场景很明确：你正在等待某个 PR 合并，但下游服务已上线，就必须用 replace 指向你的修复分支；或者某个官方模块长期不维护，社区 fork 出稳定版，你也得靠 replace 切过去。
立即学习“go语言免费学习笔记（深入）”；
-
replace只在当前模块生效，子模块不会继承，所以每个需要该替换的模块都得单独写 - 别用
replace指向本地路径（如./local-fix），CI 环境会找不到——改用 Git URL + commit hash，例如：replace github.com/old/lib => github.com/yourfork/lib v0.0.0-20260722143021-abc1234 - 所有
replace必须配注释说明原因和预期恢复时间，否则半年后没人记得为什么锁在这里
go.sum 不是校验文件，而是依赖指纹快照
go.sum 文件记录的是每个模块及其所有子依赖的 SHA256 校验和，它的作用不是“防篡改”，而是确保你在任何机器上 go build 时拉下来的代码和上次完全一致。一旦有人手动删掉它再 go mod tidy，就等于放弃指纹快照，后续构建可能引入不同 commit 的同版本模块。
容易踩的坑是把它当成可忽略的生成文件，甚至加进 .gitignore。实际上，只要 go.mod 变更，go.sum 就必须同步提交，否则团队成员 go build 时会报错：verifying github.com/xxx/yyy@v1.2.3: checksum mismatch。
- CI 流程中必须校验
go.sum是否与go.mod匹配，可用go mod verify - 若因网络问题导致
go.sum更新失败，不要手动编辑，应先清理模块缓存：go clean -modcache，再重试go mod tidy - 私有模块若走 SSH 或 Token 认证，需确保
go.sum中记录的是解析后的最终 URL（如git.company.com/xxx/yyy），而非原始 import 路径
依赖生命周期结束的信号很具体
一个 Go 模块是否该被移除，不取决于“看起来没用了”，而要看三个硬指标：源码中无 import 引用、go list -deps ./... | grep module-name 返回空、且最近 90 天内无 commit 修改过它相关的接口或配置。
很多团队卡在“不敢删”，怕漏掉隐藏依赖。其实 Go 的静态分析足够可靠：用 go mod graph | grep module-name 查它是否出现在依赖图里；再用 go list -f '{{.Imports}}' ./... | grep module-name 确认没有隐式引用。
- 删除前先在
go.mod中加// DEPRECATED: will be removed after YYYY-MM-DD注释，并设置截止日期 - 如果该模块被多个子模块共用，删除动作必须原子化：一次 PR 同步更新所有引用方的
go.mod，避免中间状态导致部分服务编译失败 - 最后一步不是
go mod tidy，而是手动删掉go.sum中对应行——工具不会自动清理已废弃模块的校验和
replace 该不该留、某个 v2 版本值不值得升、以及哪一行 go.sum 校验和背后藏着多少次深夜回滚。这些决策没法自动化，只能靠每次 go list -m -u 输出里多盯两眼。 
