go.mod 和 go.sum 必须一起提交，前者声明所需模块，后者记录实际下载包的哈希值以确保构建一致性；单独提交 go.mod 会导致版本漂移和校验失败。
go.mod 和 go.sum 必须一起提交到 Git
只提交 go.mod 而忽略 go.sum 是团队协作中最常见的失控行为。前者声明“我想要哪些模块”，后者记录“我实际拿到的每个字节哈希值”。没有 go.sum，同一行 require github.com/sirupsen/logrus v1.9.0 在不同机器上可能拉到 v1.9.0、v1.9.3 甚至被中间代理篡改的包。
常见错误现象：
- 本地
go build成功，CI 报错checksum mismatch - 同事
go mod download后生成新go.sum提交，你git pull后运行go test直接失败
正确做法：
-
go.sum必须和go.mod同时git add并提交 - CI 流程中必须执行
go mod verify，失败即中断构建 - 禁止设置
GOSUMDB=off或删掉go.sum来“绕过校验”
用 go get @vX.Y.Z 显式指定版本，别碰 -u
go get -u 会触发最小版本选择（MVS）算法自动升级所有直接依赖到最新兼容 minor 版本，极易引入破坏性变更——比如 golang.org/x/net 从 v0.14.x 升到 v0.17.x 可能导致 HTTP/2 行为变化。
立即学习“go语言免费学习笔记（深入）”；
真正可控的升级方式是精确指定版本：
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 升级单个依赖：
go get github.com/gin-gonic/gin@v1.9.1 - 降级回已知稳定版：
go get github.com/sirupsen/logrus@v1.8.1 - 查看可用版本：
go list -m -versions github.com/sirupsen/logrus - 升级后立刻检查
go.mod是否写入了目标版本，并确认go.sum新增对应条目
注意：@latest 不等于“最新 patch”，它可能跨 minor，生产环境应禁用。
go mod tidy 不是“整理工具”，而是依赖解析器
go mod tidy 的作用不是“清理冗余”，而是让 go.mod 与代码中的 import 语句严格对齐：补全间接依赖、移除未引用的 require、并按 MVS 规则重新计算所有依赖版本。它可能悄悄把你的 v1.9.0 升成 v1.9.3——只要某个间接依赖强制要求 v1.9.3。
所以不能把它当“一键修复”命令：
- 运行前先
go list -m all | grep target-lib看当前解析出的实际版本 - 如果发现版本被意外提升，说明有其他依赖在拉高版本，需用
go mod graph | grep target-lib定位来源 - 必要时用
replace或exclude干预（但exclude仅限临时应急） - 每次
go mod tidy后都必须检查go.mod和go.sum变更，不能无脑提交
私有模块和 GOPROXY 配置不一致会导致版本漂移
当项目依赖私有仓库（如 git.internal.company.com/mylib）时，若部分开发者没配 GOPRIVATE，Go 会尝试走公共代理（如 proxy.golang.org）下载，结果 404 后 fallback 到 git clone，而 clone 的 commit hash 可能和别人不一致——go.sum 就对不上。
统一配置是硬性前提：
- 所有成员必须设置
GOPRIVATE=git.internal.company.com,github.com/myorg/private - CI 环境也要在构建前 export 该变量
- 配合
GOPROXY=https://goproxy.cn,direct加速公共包，同时保留私有库直连 - 验证是否生效：
go env GOPRIVATE和go env GOPROXY必须输出一致结果
版本同步这件事，表面看是文件提交问题，实质是整个工具链行为的一致性。哪怕只有一台机器的 GOPROXY 配错了，或某次 go mod tidy 没核对 go.sum 变更，就足以让团队陷入“为什么我本地能跑”的泥潭。
