Go vendor 模式下如何确认实际使用的依赖版本

项目切到 vendor 模式后，我最常遇到的误判是：看到 go.mod 里的版本，就以为构建一定用了那一份代码。真正参与构建的目录、模块清单和最终二进制信息，应该沿着三层证据核对：vendor/modules.txt 说明复制进来的模块版本，go list -mod=vendor 说明包从哪里加载，go version -m 说明交付物里留下了什么 BuildInfo。

要确认 Go vendor 模式的实际依赖版本，先看项目根目录的 vendor/modules.txt，再用 go list -mod=vendor -f '{{.Module.Path}} {{.Module.Version}} {{.Dir}}' all 对照目录；不要用 go list -m all 在 vendor 模式下强行推导完整模块图。

先把 vendor 模式和 module cache 分开

Go 1.14 及更高版本在主模块的 go.mod 声明允许且根目录存在一致的 vendor/modules.txt 时，可以自动启用 vendor；为了排查时不受环境默认值影响，我更建议显式写出 -mod=vendor。这个标志让构建、测试和包加载优先使用主模块顶层的 vendor，不去网络或模块缓存找依赖。

先执行一个只读查询，不需要下载依赖：

go env GOMOD
# 确认当前命令属于哪个主模块
go list -mod=vendor -f '{{with .Module}}{{.Path}} {{.Version}} {{.Dir}}{{end}}' all
# 重点看 Dir 是否落在项目根目录的 vendor 下

如果输出的 Dir 是类似 vendor/example.com/lib，说明包解析路径符合预期；如果看到模块缓存路径，先检查命令是否在主模块根目录执行、是否误用了 -mod=mod，以及 GOFLAGS 是否覆盖了参数。这个判断只回答“包从哪里来”，还没有回答“版本清单是否最新”。

vendor/modules.txt 才是 vendor 复制版本的索引

go mod vendor 会重建 vendor 目录，并生成 vendor/modules.txt。其中以 # 模块路径 版本 开头的行对应模块版本，下面的缩进或普通路径行列出被复制的包。较新的 Go 版本还可能写入依赖模块声明的 Go 版本信息。

# 用模块头部快速找出某个依赖的复制版本
rg -n '^# (github\.com/[^ ]+|golang\.org/x/[^ ]+) ' vendor/modules.txt
# 先看模块头，再结合下面的包路径判断它是否真的被 vendor
sed -n '1,80p' vendor/modules.txt

这里要留意三个边界。第一，目录名不能替代版本证据，版本通常只在 manifest 的模块头部出现。第二，replace 可能让模块头部同时表达替换来源，不能把被替换路径和本地目录混为一谈。第三，vendor/modules.txt 与 go.mod 不一致时，Go 命令会报错，正确动作是重新运行 go mod vendor，而不是手工改 manifest。

用 go list 形成“版本 + 目录”的对照表

只看文本清单仍然不够，我通常会把模块路径、版本和解析目录一次打印出来：

go list -mod=vendor -f '{{with .Module}}{{.Path}} {{.Version}} {{.Dir}}{{end}}' all
# .Module 提供路径和版本，.Dir 用来确认实际包目录
# 输出为空的包通常不是独立模块根，要回到其依赖模块头查看版本

这条命令适合确认参与当前包集合的模块。不要把它和 go list -m all 的含义混在一起：官方文档明确说明，vendor 模式下需要完整模块图的查询可能无法用 vendor 目录计算；要查看不依赖 vendor 加载的模块图，可使用：

go list -mod=readonly -m all
# readonly 保留 go.mod 语义，不允许命令为了查询改写依赖
go mod graph
# 用边表示模块版本之间的要求关系，辅助解释为什么选中某版本

因此，排查表最好保留两列：vendor 证据写 vendor/modules.txt 和 .Dir，模块图证据写 go.mod、go list -mod=readonly -m all 或 go mod graph。两者一致，才适合继续定位代码行为；不一致时先更新 vendor。

交付二进制时用 BuildInfo 做最后确认

如果问题发生在 CI 或发布包，构建目录里的 vendor 只是过程证据，最终产物还应单独核对。对使用模块构建的 Go 二进制，可以执行：

go version -m ./bin/server
# -m 读取二进制内嵌的模块版本信息
go version -json -m ./bin/server
# JSON 形式便于归档到发布记录或构建产物清单

输出里能看到主模块和依赖模块的路径、版本以及可能的替换信息。若二进制没有可用的 BuildInfo，不能反过来断言它一定没有使用 vendor；这只表示发布物缺少这一层可读元数据。此时应把构建命令、go.mod、vendor/modules.txt 和源码提交号一起保存。

当依赖升级、切换分支或修改 go.mod 后，收尾动作应是：

go mod vendor
# 根据当前源码和 go.mod 重建 vendor 目录及 modules.txt
git diff -- go.mod go.sum vendor/modules.txt
# 只检查依赖声明和 vendor 清单是否随变更一起更新

这套方法的价值不在于记住某一个命令，而是把“模块图选了哪个版本”“包实际从哪里加载”“发布物留下了什么信息”拆开。以后遇到 vendor 目录看似正确但行为仍旧异常的情况，先按这三层证据排查，通常比反复删除缓存更快。

常见问题

go list -mod=vendor -m all 为什么可能失败？

因为 vendor 清单主要服务于 vendored 包的加载，未必包含计算完整模块图所需的信息。要看完整模块图，可改用 -mod=readonly 或 go mod graph，但这回答的是模块关系，不是包目录来源。

手工修改 vendor/modules.txt 能解决版本不一致吗？

不建议。它是 go mod vendor 根据主模块依赖关系生成的清单；修改了 go.mod 或源码依赖后，应重新生成 vendor 并把变更纳入同一次提交。