Go vendor 与 module cache 选择不一致的定位

Go 项目同时保留 vendor 目录和本机 module cache 时，最容易出现一种错觉：大家看的是同一份 go.mod，构建却像读取了两套依赖。定位这类问题，重点不是先删缓存，而是先记录 go 命令的选择条件，再用 go list 看目标包的实际目录。

官方资料：https://go.dev/ref/mod

这篇只讨论依赖选择模式：vendor、module cache、GOFLAGS、-mod 与 go.mod 的 go 指令如何共同影响构建来源。

先把“路径不一致”变成一组基线信息

先在项目根目录记录环境。这里的目标不是收集所有 Go 配置，而是确认当前命令实际能看到的模块文件、缓存目录和默认参数。

# 在项目根目录记录模块文件、缓存目录、默认模块参数和 Go 版本
go env GOMOD GOMODCACHE GOFLAGS GOVERSION

# 查看 go.mod 中的 go 指令与项目根目录是否存在 vendor
sed -n '1,12p' go.mod
test -d vendor && echo "vendor directory: present" || echo "vendor directory: absent"

# vendor 模式依赖这份清单判断 vendored module 的版本对应关系
test -f vendor/modules.txt && echo "vendor manifest: present" || echo "vendor manifest: absent"

如果不同机器输出的 GOFLAGS 不同，先不要把差异归因于缓存。GOFLAGS 可以为接受这些参数的 go 命令提供默认 flag；而 GOMODCACHE 只是模块缓存位置，不等于本次构建一定从缓存读取。

判断 vendor 是否会被自动采用

Go Modules Reference 给出的关键条件是：主模块根目录有名为 vendor 的目录，并且 go.mod 中的 go 指令为 1.14 或更高时，接受 -mod 的构建命令会默认按 vendor 模式工作。这个判断只针对主模块的顶层 vendor，不是“磁盘上某处存在一个 vendor”就一定生效。

如果 vendor/modules.txt 与 go.mod 的模块版本不一致，构建可能报告 inconsistent vendoring。此时应在依赖文件稳定后重新生成 vendor，而不是把 module cache 当作修复手段：

# 重新按当前 go.mod 构建 vendor 目录和 modules.txt
go mod vendor

# 显式要求构建使用 vendor，便于把排障条件固定下来
go build -mod=vendor ./...

go mod vendor 会重建 vendor 目录，目录中的手工修改不应作为长期方案保留。它生成的 vendor/modules.txt 是版本关系记录；如果 go.mod 后来改变，就应再次运行该命令。

重点排查 -mod 和 GOFLAGS 谁在改变选择

排障时可以把模式分成三种明确的实验条件：

为了避免把个人配置永久写入环境，优先用一次性命令对比：

# 临时切到 vendor 模式；只影响这一条命令
GOFLAGS=-mod=vendor go list -m all

# 临时切到 module 模式；用于和上一个结果做来源对照
GOFLAGS=-mod=mod go list -m all

# 查看当前环境是否已经带有隐藏的默认模式
go env GOFLAGS

不要只检查 shell 配置文件。GOFLAGS 也可能来自 go env -w 写入的用户配置，CI 还可能在任务环境里注入它。若命令行显式传入 -mod，就把这个显式条件记录在排障结论里，不要只写“Go 自动选错了”。

用 go list 看目标包到底落在哪个目录

模块版本列表只能告诉你模块关系，不能直接回答“当前编译这个包时读的是哪份源码”。选择一个实际被项目导入的包，分别在两种模式下打印目录：

# 把导入路径替换成项目实际使用的依赖包
PKG='example.com/dependency/subpkg'

# go list 的 .Dir 会显示当前模式解析到的包目录
GOFLAGS=-mod=vendor go list -f '{{.Dir}}' "$PKG"
GOFLAGS=-mod=mod go list -f '{{.Dir}}' "$PKG"

对比结果时看目录形态即可：一条通常落在当前项目的 vendor/ 子树，另一条通常落在 GOMODCACHE 下的 module@version 目录。这里的重点是“实际包目录”，不是凭缓存是否存在来猜来源。

把定位结论固定成团队可复现的命令

如果团队明确要求提交 vendor，就在 CI 的构建和测试命令中显式使用 -mod=vendor，并把 go.mod、go.sum、vendor/ 和 vendor/modules.txt 作为同一次依赖变更处理。若团队明确使用 module cache，则显式使用 -mod=mod，不要让不同机器的自动条件承担策略职责。

一个紧凑的判断顺序是：先看 go env GOFLAGS，再看 go.mod 的 go 指令和顶层 vendor，接着用一次性 GOFLAGS=-mod=vendor 与 GOFLAGS=-mod=mod 对照，最后用 go list -f '{{.Dir}}' 确认实际目录。这样就能把“依赖不一致”拆成可观察的选择条件。

常见问题

有 vendor 目录就一定不会访问 module cache 吗？

不一定。自动采用 vendor 需要满足主模块顶层目录和 go 指令版本等条件；显式的 -mod=mod 或环境中的 GOFLAGS 也会改变构建条件。用 go list 看实际目录更可靠。

为什么 go mod vendor 后仍然觉得依赖版本不一致？

先确认命令是在正确的主模块根目录执行，再检查 go.mod 是否在生成 vendor 后又发生变化。vendor/modules.txt 必须和当前模块关系同步；不要只清理 module cache。

结论很简单：vendor 是项目内的一份依赖树，module cache 是 Go 管理的本机模块来源，真正决定本次构建读取哪里的，是 go.mod、-mod、GOFLAGS 和命令上下文的组合。先记录条件，再定位目录，最后固定模式，排查结果才不会依赖某台机器的默认配置。