Go vendor inconsistent vendoring 的修复清单

Go 项目出现 inconsistent vendoring 时，通常不是业务代码坏了，而是 go.mod 已经变化，仓库里的 vendor/modules.txt 还停留在旧的依赖快照。最稳妥的处理顺序是：回到主模块根目录，先确认依赖声明，再执行 go mod vendor 重建目录，最后明确构建时采用 vendor 还是模块缓存。

先判断不一致发生在哪一层

先在项目根目录执行下面的检查，重点看 Go 版本、模块根目录和 vendor 清单是否同时存在：

# 确认当前目录确实是主模块根目录
pwd
go env GOMOD GOVERSION GOFLAGS

# 查看模块声明和 vendored 清单的头部
sed -n '1,80p' go.mod
test -f vendor/modules.txt && sed -n '1,40p' vendor/modules.txt || echo 'vendor/modules.txt 不存在'

# 只列出主模块依赖，帮助定位刚改动的模块
go list -m all

不要把 go list -m all 的输出和 vendor 包目录数量简单对比。真正需要匹配的是模块版本、标记过的显式依赖，以及当前主模块实际需要的包集合。Go 官方文档说明，go mod vendor 会在主模块根目录重建 vendor，并生成 vendor/modules.txt。

用 go mod vendor 重建，而不是手工改清单

如果最近执行过 go get、修改了 replace、调整了 go 指令，或合并了别人的 go.mod，建议按下面顺序处理：

# 先让 go.mod 和 go.sum 反映当前源码的真实依赖
go mod tidy

# 根据当前模块图重新生成 vendor 与 modules.txt
go mod vendor

# 再次使用 vendor 构建，确认清单已经能被读取
go build -mod=vendor ./...

go mod vendor 会重建整个 vendor 目录，因此不要把临时修改直接写进 vendored 包；如果确实要改第三方依赖，应使用独立模块、fork 或 replace 管理。图中的两条分支分别表示“依赖声明”和“本地副本”，它们必须在版本和包边界上重新汇合。

按构建目标选择模块模式

修复清单一致后，还要避免构建命令再次走错来源。Go 1.14 及以上的主模块在根目录存在 vendor 时，部分构建命令可能自动采用 vendor；团队脚本最好显式写出意图：

如果 CI 需要完全离线，缓存里有依赖并不代表仓库是可复现的，应把 vendor 和 vendor/modules.txt 一起提交，并固定构建参数。若 CI 需要更新依赖，则不要把 -mod=vendor 当成更新命令。

合并冲突、replace 与版本漂移的复查清单

仍然报错时，按这四项复查：第一，所有命令是否都在同一个主模块根目录执行；第二，合并提交是否只带了 go.mod，却漏了 go.sum 或 vendor；第三，replace 指向本地目录时，该目录是否仍包含有效的 go.mod；第四，开发机和 CI 是否使用了不同的 Go 工具链或不同的 GOFLAGS。

# CI 中用只读模式暴露“依赖声明还没准备好”的问题
go build -mod=readonly ./...

# 确认 vendor 版本来自当前 go.mod，而不是旧目录残留
go mod vendor
git diff -- go.mod go.sum vendor/modules.txt

# 若 diff 非空，先审查依赖变化，再决定是否提交
git status --short

这里的 git diff 是人工审查入口，不是让 CI 自动吞掉变化。只要依赖升级是有意的，就同时提交声明文件和生成结果；如果升级不是有意的，回到引入变化的提交检查，而不是只把 vendor 文件覆盖回旧版本。

常见问题

只删除 vendor 目录能不能解决问题？

可能暂时绕开 vendor 清单检查，但会改变构建来源，也可能让离线 CI 失效。更好的做法是先确认团队是否需要 vendoring，再重建或明确关闭它。

为什么 go mod tidy 后还要执行 go mod vendor？

go mod tidy 整理模块声明，go mod vendor 生成仓库内的依赖副本和 modules.txt；两者解决的是不同层面的同步问题。

vendor 目录里手改第三方代码会被 Go 检测出来吗？

Go 命令不会把 vendored 源码改动当作一致性检查的主要对象。需要验证副本是否漂移时，应重新生成 vendor 并审查差异。