go.mod与go.sum必须一起提交，缺一不可；go.sum是依赖完整性与安全校验的强制契约，缺失将导致构建失败、校验不通过或静默降级，尤其在灾备切换、多环境部署时高频触发checksum mismatch错误。
go.mod + go.sum 必须一起提交，缺一不可
只提交 go.mod 而忽略 go.sum，等于交出一把没锁芯的钥匙——构建时 Go 会尝试重新计算哈希，但网络、代理、校验数据库（GOSUMDB）状态稍有差异，就可能拉到内容一致但哈希不同的归档，导致 go build 直接失败或静默降级。
常见错误现象：verifying github.com/some/pkg@v1.2.3: checksum mismatch，尤其在灾备切换后首次构建时高频出现。
-
go.sum不是“可选日志”，它是构建可重现性的强制契约；每一行都对应一个模块+版本+哈希三元组 - 禁止手动编辑
go.sum；哪怕只是删掉某一行，go mod verify就会退出码 1 - CI/CD 流水线中，应在
go mod download后立即跑go mod verify，失败即中断，不留给构建环节兜底
灾备环境必须复用同一套 GOPROXY 和 GOSUMDB 配置
不同 region 的构建节点若使用不同代理（比如一个走 https://goproxy.cn，另一个走 https://proxy.golang.org），即使 go.mod 版本相同，也可能因上游镜像同步延迟或内容裁剪策略差异，下载到哈希不同的归档包。
真实案例：杭州机房用 GOPROXY=https://goproxy.cn 构建成功，深圳灾备节点用默认 proxy.golang.org 却校验失败，查实是后者对某些私有域名模块做了拦截重写。
立即学习“go语言免费学习笔记（深入）”；
- 所有构建环境（包括本地 dev、CI runner、灾备集群节点）统一设置
GOPROXY和GOSUMDB，写死在 shell 初始化文件或 CI 配置中 - 禁用
GOSUMDB=off—— 这等于主动放弃校验，灾备场景下不可接受 - 若用自建 proxy，确保其缓存策略支持
ETag和完整/@v/v1.2.3.info元数据，避免哈希计算依据缺失
多模块项目中，每个子模块都要独立 go mod tidy 并保留自己的 go.sum
主模块 go mod tidy 不会递归处理子目录下的其他 go.mod。如果子模块（如 ./service/user）更新了依赖但没运行 go mod tidy，它的 go.sum 就不会更新，而主模块构建时仍会读取该文件——结果就是校验失败或版本错配。
典型报错：missing go.sum entry for github.com/yourorg/shared@v0.3.1，但 go list -m all 显示该版本明明存在。
- CI 构建前加检查脚本：遍历所有含
go.mod的子目录，执行cd $dir && go mod tidy && cd - - 子模块的
go.sum不合并、不删除；每个模块的依赖状态必须自治 - 用
go mod graph | grep shared确认跨模块引用路径，避免 replace 指令漏删或残留（灾备发布前必须清理）
部署包必须包含 go.mod 和 go.sum，且禁止在构建后修改
有些团队把构建产物打成 tar 包时，只打包 bin/ 和配置，认为依赖已“编译进去”就无需源信息。但灾备回滚或紧急 patch 时，若缺失这两份文件，就无法复现原始构建环境，连 go mod download 都可能拉错版本。
更隐蔽的问题：Docker 构建中 COPY . . 覆盖了之前 RUN go mod download 下载的依赖缓存，但没带 go.sum，导致后续 go mod verify 失败。
- 交付物清单里明确列出
go.mod、go.sum、go version输出三者 - Dockerfile 中严格按顺序：
COPY go.mod go.sum .→RUN go mod download→COPY . .，防止覆盖 - 灾备切换窗口内，禁止任何
go get或go mod edit操作；所有变更必须走代码提交 + CI 流程
go.mod 和 go.sum 出发，且中间不被任何人工干预、环境变量覆盖或缓存污染打断。一致性不是配置出来的，是流程卡点守出来的。 
