必须一起提交；go.mod和go.sum需同时纳入版本控制，缺失go.sum会导致构建失败或运行时不一致，CI应强制运行go mod verify阻断问题合并，且v2+升级须路径、导入、模块声明同步变更。
多人协作时 go.mod 和 go.sum 必须一起提交
分支合并前若只提交 go.mod 而忽略 go.sum，会导致其他开发者拉取分支后 go build 失败或运行时行为不一致。Go 不会自动重新生成 go.sum，它只校验已存在的哈希值；缺失条目会触发 go mod download 时校验失败，报错如 main module requires main module version not found in go.sum。
团队应将 go.sum 纳入强制 CI 检查项：在 PR 流程中运行 go mod verify，失败即阻断合并。Git 提交模板里也应明确提示“修改依赖必同步提交 go.mod 与 go.sum”。
主干分支（main）必须是唯一可信的版本源
禁止在 feature 分支上独立升级依赖并长期不合入 main。否则会出现“同一模块在不同分支中锁定不同版本”，合并时 go.mod 冲突难解，且 go.sum 中哈希无法对齐。
- 所有依赖升级操作（包括
go get、go mod tidy）应在main分支上完成，并通过独立 PR 提交 - feature 分支需定期
git rebase main或git merge main，同步最新的go.mod/go.sum - CI 中对非
main分支应禁用go mod tidy -v类自动写入命令，防止意外污染
用 go list -m all + git diff 定位版本漂移
当发现某分支构建失败但 main 正常，大概率是该分支的 go.mod 未及时同步，或本地误执行了 go get -u 导致间接依赖版本升级。
立即学习“go语言免费学习笔记（深入）”；
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
快速诊断步骤：
- 在出问题分支执行
go list -m all > deps-before.txt - 切到
main分支执行同样命令，得deps-after.txt -
diff deps-before.txt deps-after.txt查看哪些模块版本不一致 - 重点检查
[behind]标记项（来自go list -m -u），确认是否遗漏了 main 上已升级的模块
v2+ 升级必须走独立分支 + 显式路径变更
主版本升级不是“更新版本号”，而是代码结构、导入路径、模块声明三者同步变更。若在 feature 分支上单独做 v2 升级（比如改 module example.com/lib/v2 并更新 import），而 main 还在用 v1，合并时会直接破坏所有依赖 v1 的代码。
正确做法：
- 新建专用分支（如
feat/lib-v2-migration），在该分支上完成全部迁移：模块路径修改、所有import替换、go get拉取 v2、go mod tidy、全量测试通过 - 该分支仅合入
main，且必须确保合入后main上所有子模块/服务仍可构建——这意味着 v1 和 v2 需短期共存（靠路径隔离），不能一刀切换 - 禁止在任意 feature 分支上对同一模块同时 require v1 和 v2，Go 构建器会拒绝解析
最易被忽略的点是：v2 升级后，go.sum 里新增的 /v2 路径条目和旧 v1 条目完全独立，但开发者常以为“升级完就结束了”，忘了通知下游服务同步改 import 路径——这会导致编译错误，且错误信息里不会提示“你该升级了”，只会说 cannot find package。
