go.mod 和 go.sum 必须提交到 Git，二者构成依赖版本契约：go.mod 声明所需版本，go.sum 校验内容完整性；禁止忽略、删除或滥用 replace、@latest；需统一 GOPROXY/GOPRIVATE 配置并强制 CI 验证。
go.mod 和 go.sum 必须提交到 Git
多人协作时，go.mod 和 go.sum 不提交 = 依赖不一致的根源。这两个文件不是“生成物”，而是版本契约：前者声明你**要求什么版本**，后者校验你**实际拿到的内容是否被篡改**。
常见错误现象：go build 在本地成功，CI 构建失败；A 同学运行 go test 通过，B 同学报错说某个函数不存在。
- 所有团队成员必须把
go.mod和go.sum提交进主干分支（如main或develop） - 禁止在
.gitignore中忽略它们，也不允许“临时删掉再重新生成” -
go.sum中哈希值一旦变化，说明依赖内容变了——必须确认是预期更新，而非网络污染或代理劫持
升级依赖必须走统一流程，禁用 latest
直接执行 go get -u 或 go get some/module@latest 是团队协作中最危险的操作。它会绕过语义化版本约束，导致不同人拉到不同 commit，且无法回溯。
正确做法是显式指定版本号，并由专人或 CI 自动触发：
立即学习“go语言免费学习笔记（深入）”；
- 升级命令统一为
go get example.com/pkg@v1.4.2，而非@latest - 升级后立即运行
go mod tidy清理冗余依赖、补全缺失项 - CI 流程中加入
go mod verify，验证go.sum是否与当前go.mod匹配 - 建议在 PR 模板中强制要求填写升级原因（如“修复 CVE-2025-xxxx”或“适配新 API”）
多模块项目中 replace 指令只用于开发，严禁合入主干
单仓库多模块结构下，replace 是调试利器，但也是版本漂移的温床。它的存在会让 go build 绕过远程模块版本，直接读取本地路径——这在本地开发没问题，一合入主干就破坏了构建可复现性。
典型错误场景：某模块 A 正在联调模块 B 的未发布功能，开发者在根 go.mod 中写：replace github.com/org/b => ./modules/b，然后直接 push。
- CI 构建时因路径不存在而失败，或因 GOPROXY 设置跳过本地路径导致拉取旧版 必须在上线前删除所有
- 推荐用 CI 脚本自动检查：
grep -q "replace" go.mod && echo "ERROR: replace found" && exit 1 - 若需跨模块快速验证，可用临时分支 + 预发布版本（如
v0.3.0-rc1），而非依赖本地路径
replace 行，并用 require github.com/org/b v0.3.0 替代
GOPROXY 和 GOPRIVATE 必须全局对齐
不同成员配置不同代理，会导致同一 go.mod 在不同机器上解析出不同依赖树。比如有人用 https://proxy.golang.org，有人直连 direct，私有模块又没设 GOPRIVATE ——结果就是部分人能下载，部分人报 module github.com/internal/foo: reading https://proxy.golang.org/...: 404 Not Found。
解决方案是标准化环境变量：
- 团队文档明确要求设置：
GOPROXY=https://proxy.golang.org,direct - 所有私有模块域名必须加入
GOPRIVATE，例如：GOPRIVATE=git.company.com,github.com/internal - CI 环境也需同步配置，避免“本地能过，CI 失败”
- 注意：Windows 用户容易漏掉
set或 PowerShell 的语法差异，建议提供一键脚本
版本统筹最难的不是技术操作，而是让所有人遵守同一条规则——尤其当某次紧急修复让人想“先本地跑通再说”。只要有一处偏离，go.mod 就不再是契约，而成了摆设。
