Go vendor inconsistent 时怎样恢复依赖目录

看到 go: inconsistent vendoring 时，先不要手改 vendor/modules.txt。这个错误通常表示当前主模块的 go.mod 已经变化，但 vendor 目录和它的模块清单仍停留在旧状态；最稳妥的恢复方式是让 Go 根据当前模块定义重新生成 vendor。

官方地址：https://go.dev/

单模块项目运行 go mod vendor；由 go.work 管理多个主模块时运行 go work vendor。两条命令都应在对应的模块或 workspace 根目录执行，命令完成后再回到原来的构建命令。

先判断是不是 go.mod 与 vendor/modules.txt 不一致

go mod vendor 会把主模块构建和测试需要的依赖复制到 vendor，同时生成 vendor/modules.txt。Go 读取 vendor 模式时，会用这份清单核对 go.mod 中的模块版本、显式依赖和替换关系。

因此，下面几类报错都属于同一条排障线索：模块在 go.mod 中被显式要求但在清单中没有标记、replace 目标不同、清单里多出不再需要的显式依赖，或者 vendor 中存在包但没有被 modules.txt 正确记录。它们与“代理不可用”“源码本身编译失败”不是一回事。

单模块项目用 go mod vendor 重新生成

确认当前目录包含目标模块的 go.mod 后，直接重新生成 vendor。这个动作以当前模块图为准，不要先删除清单，也不要从另一台机器复制一份 vendor 覆盖当前目录。

# 在包含目标 go.mod 的模块根目录执行
go mod vendor

# 恢复后沿用项目原本的构建入口
go test ./...

重新生成会同时更新依赖目录和 vendor/modules.txt。如果项目声明的 Go 版本达到自动 vendoring 的条件，并且清单与 go.mod 一致，普通的 go build 或 go test 就可以从 vendor 加载依赖。

一个常见误区是只执行 go mod tidy。tidy 负责整理模块依赖声明，不等于把已经存在的 vendor 内容同步到最新模块图；需要交付 vendor 目录时，仍要执行 go mod vendor。

重点排查 require、replace 和 Go 版本标记

如果重新生成前后仍然出现一致性错误，优先看三个边界。第一，go.mod 里新增的直接或间接依赖是否已经纳入当前模块图；第二，replace 是否指向本地目录或另一版本；第三，模块的 go 指令是否影响了 vendor 清单中的版本信息。

# 用 Go 自己打印主模块和依赖关系，避免凭目录猜版本
go list -m all

# 查看当前模块声明的替换关系
go mod edit -json

# 只有确实要交付 vendor 时，才按当前 go.mod 重新生成清单和目录
go mod vendor

不要把 vendor/modules.txt 当成独立配置文件维护。它是 vendor 生成结果，手工补一行可能暂时绕过一个提示，却可能留下错误的版本、显式标记或替换目标。尤其是本地 replace，必须让 go.mod 和重新生成的清单同时表达同一个目标。

Go 1.17 及更高版本的模块 vendoring 还会在清单中记录依赖模块声明的 Go 版本。项目升级 Go 版本后，旧清单出现差异并不奇怪，重新运行生成命令比手工对齐某个版本字符串更可靠。

使用 go.work 的项目要运行 go work vendor

如果仓库根目录存在 go.work，并且它的 use 块包含多个模块，那么不要把排障思路简化成“进入其中一个子目录运行 go mod vendor”。workspace 的主模块集合由 go.work 决定，应在 workspace 根目录生成共享的 vendor。

# 在包含 go.work 的 workspace 根目录执行
go work vendor

# 再从 workspace 视角检查项目包
go list ./...

如果只是普通单模块仓库，继续使用 go mod vendor。两种场景的关键差异不是命令长短，而是谁定义“主模块集合”：前者由单个 go.mod 定义，后者由 go.work 把多个模块放到同一工作区。

恢复后怎样选择 -mod 参数

同步成功后，优先让项目保持原有默认模式。排障时可以临时用参数区分问题来源，但不要把临时绕过方案当成修复提交：

如果 -mod=mod 能通过而默认模式失败，通常说明代码本身未必有问题，仍应回头同步 vendor。反过来，如果两种模式都失败，再分别检查依赖下载、包导入和源码编译错误，避免把所有问题都归到 vendor inconsistent。

一份可提交的恢复清单

1. 在报错目录确认真正的主模块：单模块看 go.mod，workspace 看 go.work。
2. 不要手改 vendor/modules.txt，先让生成命令依据当前声明重建。
3. 单模块执行 go mod vendor，workspace 执行 go work vendor。
4. 检查 require、replace 和 Go 版本变化是否是本次差异来源。
5. 按项目约定提交 vendor 目录与清单，再用原构建入口完成团队自己的回归测试。

这套处理的核心只有一句话：vendor/modules.txt 是模块定义生成出的索引，不是应该独立修补的真相源。先找对主模块，再用对应的 vendor 命令同步，最后才判断是否需要临时切换 -mod 模式。

两个容易混淆的问题

只删除 vendor 目录能解决 inconsistent vendoring 吗？ 不一定。删除后可能暂时不再使用 vendor，但这不是恢复可提交依赖目录的方案；如果项目需要 vendoring，仍应根据当前模块定义重新生成。

go mod tidy 和 go mod vendor 哪个先运行？ 取决于改动目的。整理依赖声明时可以先运行 go mod tidy，确认模块图后再运行 go mod vendor；不要把 tidy 的结果误认为 vendor 已经同步。