go build 默认不修改 go.mod 或 go.sum，新增 import 后必须先运行 go mod tidy 才能补全依赖、清理冗余并更新校验和；replace 和 indirect 会削弱可追溯性，CI 应校验 go.mod/go.sum 变更且清空 replace。

go build 默认不写入 go.mod，但你得让它“留痕”

默认情况下 go build 不会修改 go.mod 或 go.sum，哪怕你新增了 import、删了包，它也只管编译通过。这看起来省事，实则埋下隐患：下次 CI 构建或同事拉代码时，可能因依赖未显式声明而失败。

关键不是“能不能编译”，而是“谁在什么时候引入了什么依赖”。要让每次变更可追溯，必须强制工具链记录依赖变化：

• 新增 import 后，**不要直接 go build**，先跑 go mod tidy —— 它会补全 require、删掉未用项，并更新 go.sum
• 如果只是临时调试，用 go run main.go 也会触发自动下载和 go.sum 更新，但它不会清理冗余 require，不如 tidy 干净
• CI 流水线里建议加一步校验：git diff --exit-code go.mod go.sum，确保提交前已执行 tidy，否则拒绝合并

go.sum 不是日志，但它是唯一可信的“指纹”

go.sum 记录的是每个模块内容的哈希值，不是时间戳也不是作者信息，但它能精确回答一个问题：“这个构建用的 github.com/sirupsen/logrus@v1.9.3，是不是和上周五一模一样？”

容易忽略的点：

• go.sum 会随 go mod tidy 或 go get 自动更新，但**不会自动删除过期条目** —— 即使某个模块已被移出 require，它的哈希仍留在 go.sum 中。这不是 bug，是设计：防止旧版本意外复用
• 如果你手动编辑 go.mod 改了版本号，go build 第一次运行时会自动更新 go.sum 对应条目；但如果网络不可用且本地缓存缺失，构建会失败，而非回退到旧哈希
• 想确认某次构建用了哪些确切依赖？执行 go list -m all，输出结果可存为 deps.lock 作为辅助快照（虽非官方机制，但比人工截图靠谱）

replace 和 indirect 会让“可追溯性”变脆弱

replace 是调试利器，也是追踪盲区。一旦你在 go.mod 里写了 replace github.com/foo/bar => ./local/bar，go list -m all 显示的路径就变成本地文件系统路径，CI 环境根本找不到——这等于把依赖来源从“可验证的远程仓库”降级为“不可复制的本地状态”。

真实踩坑场景：

• indirect 标记看似只是说明“这不是我直接 import 的”，但它掩盖了真实依赖层级。比如 A 依赖 B v1.2.0，B 依赖 C v0.5.0，而 C 又悄悄升级到 v0.6.0 并破坏了 API，go.mod 里 C 就会标 // indirect，你很难意识到它已漂移
• 用 go mod graph | grep c-name 查具体哪个上游拉入了 C，再结合 go mod why c-name 看引入路径，比盯着 indirect 字样有用得多
• 上线前务必检查 replace 是否残留：go mod edit -json | jq '.Replace'，有输出就得处理；CI 中可加 go mod edit -dropreplace=all 强制清空

go 1.21+ 的 go 指令是隐性“时间戳”

go.mod 开头那行 go 1.22 不只是版本声明，它锁定了语言行为边界。比如 go 1.21 项目在 go 1.22 工具链下构建，某些语法（如泛型推导增强）会被禁用，避免“构建成功但行为突变”。

这意味着：

• 每次升级 Go 工具链后，应手动更新 go 指令并提交：go mod edit -go=1.22，否则团队成员用不同 Go 版本构建，可能得到不一致的结果
• go 指令变更本身不会触发 go.sum 更新，但它会影响依赖解析逻辑（例如新版本对 MVS 算法的微调），所以它和依赖变更一样需要纳入代码审查
• 如果你看到 PR 修改了 go 行，别跳过——它可能意味着底层构建环境已变，需同步验证所有依赖是否仍兼容

真正难的不是记录依赖，而是让记录不被绕过、不被误解、不被忽略。每次 go mod tidy 都该是一次显式承诺，而不是自动化黑盒。