发布前必须确保go.mod和go.sum都已提交，二者共同构成可重现构建契约；go.sum校验各模块zip包及go.mod文件的SHA256哈希，强制保障依赖完整性与安全性，缺失或不匹配将导致校验失败。
发布前必须确保 go.mod 和 go.sum 都已提交
发布版本时锁定依赖，本质不是“执行某个命令”，而是让 go.mod 和 go.sum 两个文件共同构成可重现的构建契约。只要它们被完整提交到 Git（或其他 VCS），任何人在相同 commit 下运行 go build 就会拉取完全一致的依赖内容。
常见错误是只提交 go.mod 却忽略 go.sum，导致不同机器校验失败或拉到被篡改的包。
-
go.sum不是缓存，是每个依赖模块 zip 包和go.mod文件的 SHA256 校验和，Go 工具链在go build时强制校验，不匹配直接报checksum mismatch - CI/CD 流程中应加检查：运行
go mod tidy -v后，用git status --porcelain go.mod go.sum确认无未提交变更 - 私有模块（如
gitlab.example.com/internal/lib）必须配置GOPRIVATE=gitlab.example.com/*，否则 Go 会尝试走 proxy.golang.org，导致下载失败或版本错乱
用伪版本锁定未打 tag 的 commit
如果你依赖的某个库还没发正式版（比如只在 main 分支修了个 bug），go get github.com/user/repo@abc123 会自动生成伪版本，例如 v0.0.0-20260722104530-abc123def456，并写入 go.mod。
这种写法比 @latest 或 @master 可靠得多——它精确绑定 author date 和 commit hash，只要该 commit 没被 force-push 覆盖，就永远可重现。
立即学习“go语言免费学习笔记（深入）”；
- 手动指定伪版本不如让 Go 自动生成：直接运行
go get github.com/user/repo@abc123，别自己手写 - 可用
go list -m -f '{{.Version}}' github.com/user/repo查当前解析出的实际版本（含伪版本） - 伪版本中的时间戳来自 commit 的 author date，不是你本地执行时间，所以跨团队、跨时区也一致
禁止间接依赖意外升级的实操要点
发布前最常踩的坑是：没动直接依赖，但 go.mod 里某个间接依赖的版本变了——这通常是因为 go get -u 或 go mod tidy 在无人监督时自动选了新 minor 版。
根本解法不是“阻止 tidy”，而是提前声明约束：
- 对关键间接依赖（比如
golang.org/x/net），即使没直接 import，也在go.mod中显式加一行require golang.org/x/net v0.14.0，然后运行go mod tidy——它会保留这一行，并确保整个图都用这个版本 - 避免无参数使用
go get -u；升级单个包时，务必带@version，例如go get github.com/sirupsen/logrus@v1.9.3 - 用
go mod graph | grep 'some-lib'查谁在拉旧版，再针对性处理，而不是盲目go get -u
replace 仅用于开发，上线前必须清理
replace 是调试利器，但绝不能出现在生产发布的 go.mod 中。它会让构建环境强依赖本地路径或特定 fork，CI 机器找不到 ./local-fork 就直接失败。
真正需要的是“统一版本”，不是“替换源”：
- 如果多个依赖拉了不同版本的
github.com/json-iterator/go，正确做法是在go.mod中require一个你想锁定的版本（如v1.1.12），再go mod tidy -
replace行上线前必须删除或注释掉；CI 流程可加检查：grep -q 'replace' go.mod && echo "replace found!" && exit 1 || true - 指向本地目录的
replace必须确保该目录是 Git 仓库（含.git），否则go mod tidy会报no module found
go.mod 里每一行 require 是否明确、go.sum 是否完整、以及所有 replace 是否已被移除——这些细节稍有遗漏，就可能让线上构建行为和本地不一致。 
