Go vendor/modules.txt 怎样排查依赖版本漂移

排查 vendor 版本漂移，先确定构建用了哪份 go.mod、是否启用了 go.work，以及 -mod 最终选了哪种模式，再比较 vendor/modules.txt 中的模块版本、显式依赖标记和替换记录。确定依赖声明正确后重新生成整个 vendor，避免只改清单里的版本号。

Go 官方文档：https://go.dev/ref/mod

构建场景：本地正常，CI 却报告不一致

设想一个服务仓库：开发者更新依赖并提交 go.mod，CI 仍带着旧 vendor 构建，出现 inconsistent vendoring。这是本文的说明场景，并非真实运行日志。另一个容易混淆的场景是本地走模块缓存、CI 强制使用 vendor，两个入口本来就没有消费同一份依赖。

这里按构建负载、约束、方案选择和落地清单组织排查。目标是统一输入，不把问题扩大成代理服务器或缓存故障；没有确认实际构建入口前，清理缓存通常无法解释差异。

约束条件：先固定模块与工作区

在失败命令所在目录查看 Go 环境，并对照 CI 配置中的工作目录和完整命令。以下均为读者可执行的排查示例，本文没有在本机运行这些命令。

# 在与失败构建相同的目录查询；不要先切到另一个模块
go version
go env GOMOD GOWORK GOFLAGS
# 看本轮提交涉及哪些依赖文件，不修改文件
git diff -- go.mod go.sum vendor/modules.txt

GOMOD 帮助定位模块文件，GOWORK 帮助定位工作区，GOFLAGS 可能携带默认构建参数；还要检查脚本显式传入的 -mod、-modfile 及包装命令。嵌套模块、容器的 COPY 范围和 CI 的工作目录也应列入对照。

本文后续采用单模块发布作为明确约束，命令用 GOWORK=off 避免父目录工作区介入。团队若采用多模块工作区发布，应使用对应工具链支持的工作区 vendor 方案，不能把单模块命令当作工作区依赖快照。

方案对比：明确这次构建从哪里取包

不要把某种模式成功理解为另一种模式的数据已修复。模式对照属于定位手段，发布入口最终仍需选择团队约定的那一种。

# 单模块场景：显式选择 vendor，避免依赖默认模式
GOWORK=off go list -mod=vendor -m
# 不使用 vendor 的对照；这条命令可能需要可用的模块缓存或网络
GOWORK=off go list -mod=readonly -m

上述 -m 只展示主模块信息，不等于列出全部依赖，更不是完整的供应链证明。发生 vendor 一致性错误时，先阅读错误指出的模块路径和差异类别，再决定下一步。

推荐组织方式：声明与 vendor 快照一起维护

把 go.mod 当作依赖约束，把 vendor/modules.txt 当作生成清单，把 vendor 中源码当作实际构建材料。modules.txt 记录模块版本和包含的包；其中显式标记与 require 声明有关，替换记录还应与 replace 配置相符。它不是允许独立手工维护的另一份版本锁文件。

例如声明的某个模块版本已经变化、vendor 清单仍记录旧版本，应追溯这次依赖更新是否漏交 vendor；若报错指向替换不一致，则检查 replace 是否新增、移除或改了目标。仅比较 v 开头的版本字符串，可能忽略本地目录替换。

在确认 go.mod 是期望状态、工作区已保存变更后，再运行生成命令。go mod vendor 会重建 vendor，直接改在 vendor 内的补丁应先转为可追踪的模块替换或上游修复。

# 单模块维护：从当前依赖声明重新生成 vendor
# 先保存现有改动；该命令会重建 vendor，不能保留手工补丁
GOWORK=off go mod vendor
# 生成后查看全部相关差异，而不只看 modules.txt
git diff -- go.mod go.sum vendor
# 最终采用团队约定的 vendor 构建入口
GOWORK=off go build -mod=vendor ./...

不必把 go mod tidy 无条件塞到每次修复前面。若确实要清理或调整依赖声明，应作为单独可审阅的维护动作，再生成快照；否则一次 vendor 修复可能混入无关依赖变化。

风险点：版本对齐不代表文件内容没有变化

清单一致性主要约束模块声明与生成记录，不能据此断言 vendor 中源码从未被编辑。审阅代码差异时，也要关注源码快照是否夹带手工改动。go.sum 也不是 vendor 源文件的逐文件哈希清单。

另一个风险是“离线构建”被理解得过宽：构建使用 vendor 可以避免为依赖包读取网络，但重新生成 vendor 所需的模块材料仍可能依赖模块缓存或下载。维护阶段与发布阶段应分别安排，不能承诺所有 go mod 命令均无需网络。

落地清单：让本地和 CI 使用同一入口

• 记录构建目录、Go 工具链、GOWORK、GOFLAGS 和脚本参数。
• 确认单模块或工作区发布策略，避免两套 vendor 方案交叉使用。
• 对照错误中的模块路径，检查 require、replace 与生成清单。
• 保留原改动后重新生成 vendor，并把声明和快照作为同一次提交审阅。
• CI 明确使用选定模式，容器构建上下文包含相应依赖文件与 vendor 源码。

只改 modules.txt 的旧版本号可以吗？

不可以靠它完成修复。清单文字改变并不会把 vendor 源码同步成那个版本，可能只是掩盖了清单与源码的另一层差异。

go.sum 相同为什么依赖行为仍不同？

先看两边是否用相同入口。工作区替换、本地 replace、vendor 内源码改动和构建条件都可能影响结果，不能只拿 go.sum 判断实际用包来源。

为什么切换 -mod=mod 后不报错了？

因为这次没有按 vendor 模式读取包。这能帮助定位来源差异，但没有修复原来的 vendor 快照，且该模式允许更新依赖声明。

官方依据：模块与 vendoring 参考 https://go.dev/ref/mod#vendoring；命令参数参考 https://pkg.go.dev/cmd/go。排查时应把这些规则与仓库真实构建入口对照。