Go vendor 目录更新后为什么依赖仍提示不一致

前几天我手动替换了vendor文件夹里的第三方依赖包，重新编译的时候还是一直提示依赖版本和go.sum记录的不一致，折腾了好一阵才理清楚所有可能的原因，都是平时用vendor模式很容易忽略的细节。

直接影响vendor更新后依赖校验不一致的核心原因，大多和go.sum未同步、vendor目录未执行官方标准更新流程、存在隐藏的依赖缓存配置有关。

我第一次遇到 go: inconsistent vendoring 时，已经把依赖源码重新复制进 vendor，所以直觉上觉得 Go 还在读旧缓存。后来才发现，Go 不只检查目录里的包文件，还会把 go.mod 的 require、replace 与 vendor/modules.txt 对照。只改源码文件、不重建清单，错误当然还在。

正确处理方式不是继续手动覆盖 vendor，而是先确认当前是单模块还是 workspace，再分别运行 go mod vendor 或 go work vendor，让包文件和 modules.txt 从同一份依赖声明重新生成。

官方参考：https://go.dev/ref/mod

先判断为什么当前构建会读取 vendor

模块的 go 版本为 1.14 或更高、主模块根目录又存在 vendor 时，Go 构建命令通常会自动采用 vendor 模式。项目也可能通过 GOFLAGS=-mod=vendor 显式强制。此时 go build、go test 会从 vendor 加载包，并在开始构建前检查清单与模块声明是否一致。

# 查看项目是否通过 GOFLAGS 强制使用 vendor 模式。
go env GOFLAGS

# 确认当前是否处于 go.work 定义的工作区中。
go env GOWORK

# 临时忽略 vendor 进行对照，只用于诊断依赖图是否本身可解析。
go list -mod=mod -m all

如果 -mod=mod 能通过，而默认构建失败，问题基本集中在 vendor 快照；如果两种模式都失败，应先修复 go.mod、go.sum、replace 或源码导入关系，再生成 vendor。

modules.txt 才是依赖身份清单

vendor/modules.txt 记录模块版本、显式依赖标记、替换关系以及 vendored 包列表。Go 会检查它是否与主模块的 go.mod 一致。常见错误包括：某版本在 go.mod 中是显式 require，清单却没有标为 explicit；replace 的目标目录发生变化；清单仍保留已删除的替换；或者新增依赖根本没有写进清单。

这也是为什么直接编辑第三方源码常常让排查变乱：源码内容可能变了，描述其来源的清单却没变。我的经验是把 vendor 当作可再生成的构建快照，而不是第二套手工维护的依赖仓库。

单模块和工作区必须用不同命令

go mod vendor 始终针对单个主模块工作。即使当前目录位于 go.work 下，这个命令也不会替你生成整个工作区的统一 vendor。工作区 vendoring 应使用 go work vendor；出现 workspace 一致性错误时，Go 的错误提示通常也会明确给出这个命令。

# 单模块项目：先整理当前模块依赖，再重建当前模块根目录下的 vendor。
go mod tidy
go mod vendor

# 多模块工作区：在 go.work 所在目录重建工作区级 vendor。
go work vendor

# 临时关闭工作区，确认某个子模块能否独立完成 vendor 重建。
GOWORK=off go mod vendor

不要把 go mod vendor 和 go work vendor 混着反复执行。前者反映一个模块的依赖，后者反映 go.work 中多个主模块的联合依赖。先确定你希望 CI 构建哪个范围，再选择唯一对应的生成方式。

一套不容易返工的更新流程

我现在更新 vendored 依赖时，会先修改依赖声明，再让 Go 工具生成快照。这样 go.mod、go.sum、包文件和 modules.txt 的来源一致，也便于代码评审判断真正变化。

1. 确认 go env GOWORK 与预期一致，并决定本次更新是单模块还是整个工作区。
2. 通过 go get、go mod edit 或调整 replace 修改依赖声明，不直接复制 vendor 包。
3. 单模块先运行 go mod tidy，再运行 go mod vendor；工作区使用 go work vendor。
4. 检查 Git 变更，确认 vendor/modules.txt 与预期模块版本、替换路径同时变化。
5. 使用与 CI 相同的 GOFLAGS 和工作目录执行构建或测试。

go mod vendor 会先移除原 vendor 再重新构建，因此不要在 vendor 中保存不能再生成的本地修改。需要临时修补依赖时，应使用本地 fork 或 replace，让变更来源进入模块声明。

重建后仍报错，继续看这三个位置

第一是 GOFLAGS。 本机没有设置，不代表 CI 没有设置。工作流脚本、容器镜像或 Makefile 可能强制 -mod=vendor，导致你本地用模块缓存验证通过，CI 仍检查 vendor。

第二是生成目录。 你可能在子模块执行了 go mod vendor，但构建从仓库根目录进入 workspace，实际读取的是另一个 vendor 根目录。用 go env GOWORK 和当前模块根目录一起确认作用域。

第三是缓存。 CI 如果恢复了旧 vendor 或工作区产物，再覆盖部分文件，就会重新制造清单不一致。vendor 已提交到仓库时，通常不需要再缓存同一目录；确需缓存时，应让缓存键包含 go.mod、go.sum、go.work 与相关替换配置。

速查表

相关问题

可以用 -mod=mod 直接绕过吗？ 可以用于诊断或明确不使用 vendor 的构建，但如果仓库约定提交 vendor，它不能代替同步。

需要手动删除 vendor 再生成吗？ 通常不需要，官方命令会重建目录；关键是先修正依赖声明和工作区范围。

go mod tidy 会自动更新 vendor 吗？ 不会。它整理模块依赖与校验信息，vendor 仍要单独生成。

只要把 vendor 看成“依赖声明生成的快照”，这类错误就很好理解：Go 不是嫌目录旧，而是在告诉你，模块声明、清单和构建作用域没有来自同一个状态。