vendor 目录与 go.mod 不一致的修复步骤

Go 项目出现 inconsistent vendoring 时，通常不是某个 vendored 包“坏了”，而是主模块的 go.mod 已经变化，vendor/modules.txt 还停留在旧状态。最稳妥的修复方式是在主模块根目录确认依赖图，再运行 go mod vendor 重新生成整个 vendor 目录，最后用 -mod=vendor 检查构建是否确实使用了它。

官方文档：https://go.dev/ref/mod#go-mod-vendor

一、先确认报错对应的是主模块

这类报错常见于执行 go test ./... 或 go list 时。Go 1.14 及更高版本的模块如果存在顶层 vendor，很多命令会默认按 vendor 模式工作，所以当前目录、go.mod 中的 go 版本和 vendor 位置都要先确认。

# 打印当前命令实际使用的模块文件
go env GOMOD

# 确认模块根目录有 vendor 清单
test -f go.mod && test -f vendor/modules.txt

# 查看模块声明和依赖入口，先不要手改 vendor 包
sed -n '1,80p' go.mod
sed -n '1,80p' vendor/modules.txt

如果 go env GOMOD 返回 /dev/null 或当前路径不是预期项目，先切换到主模块根目录。嵌套模块的 vendor 目录不会替代主模块顶层 vendor。

二、对照 go.mod、replace 与 vendor/modules.txt

不要只盯着报错末尾的文件路径。清单不一致通常有三类信号：go.mod 明确 require 了某个版本但清单没有标记为 explicit；go.mod 增加了 replace 但清单没有对应替换；或者依赖版本已经改变，清单仍记录旧版本。

# 只比较依赖描述和清单，不把输出当成线上运行结果
git diff -- go.mod go.sum vendor/modules.txt

# 如果模块图本身已整理过，再从当前状态重建 vendor
go mod vendor

go mod vendor 会根据主模块源码和模块图重建 vendor，并生成新的 vendor/modules.txt。它会清理旧 vendor 后再构建，因此本地直接改 vendored 包的做法不可持续；需要定制依赖时，应回到模块版本、replace 或源码仓库解决。

三、用 -mod=vendor 完成收尾检查

重建后不要只看 vendor 目录的文件数量。明确指定 -mod=vendor 可以把检查重点放在“构建是否按预期从顶层 vendor 取包”上；若项目允许联网并想暂时绕开旧 vendor，-mod=mod 或 -mod=readonly 是诊断选项，不是修复清单的替代品。

# 显式使用顶层 vendor 查看模块列表
go list -mod=vendor -m all

# 用测试覆盖实际包导入路径；失败时先看首个依赖错误
go test -mod=vendor ./...

# 只提交依赖重建带来的必要变更
git diff --stat -- go.mod go.sum vendor
git diff --check

如果检查仍提示不一致，优先回看 go.mod 的 require、replace、go 指令和是否存在 go.work，不要连续重复执行同一条命令。若项目使用 workspace，依赖图可能由工作区共同决定，这时应按仓库约定使用 workspace 的 vendor 流程。

相关问题

可以直接编辑 vendor/modules.txt 吗？

不建议。它是由 Go 工具根据模块图生成的清单，手改只能暂时掩盖差异，下一次重建还会被覆盖。

为什么 go.mod 改了以后构建突然失败？

当模块启用 vendor 模式时，Go 会检查 go.mod 与 vendor/modules.txt 的版本和替换信息是否一致；依赖描述变化后需要重新运行 go mod vendor。

什么时候使用 -mod=mod？

它适合诊断“如果不使用旧 vendor，模块图是否能正常解析”。确认模块依赖后，仍应重新生成并提交与 go.mod 对应的 vendor。