Go Go modules vendor vendor/modules.txt 不一致怎么修复

看到 inconsistent vendoring，通常不是某个依赖包“突然坏了”，而是 go.mod 的模块声明已经变过，vendor/modules.txt 仍然保留着旧的模块图。修复原则很简单：先确认当前是单模块还是工作区，再让 go.mod 反映源码真实依赖，最后用对应的 vendor 命令整体重建清单。

先确认到底是哪一份模块图失配

先别急着删目录。报错路径和当前命令的模块入口，决定了后面该执行哪个命令。Go 官方文档说明，go mod vendor 会生成 vendor/modules.txt，而启用 vendor 时，Go 会拿这份清单与 go.mod 做一致性检查。

# 查看当前命令识别到的主模块、工作区和 Go 版本
go env GOMOD GOWORK GOVERSION

# 查看依赖声明、替换规则和 vendor 清单的改动
git diff -- go.mod go.work vendor/modules.txt

# 强制使用 vendor，便于把问题固定在当前副本
go list -mod=vendor -m all

GOMOD 指向具体的 go.mod 时，先按单模块处理；GOWORK 不是 off 时，要留意工作区作用域。表格可以快速对应常见现象：

单模块先修正 go.mod，再重建 vendor

如果只是切换了版本、增加了导入或删除了包，先处理模块图，再生成供应目录。go mod tidy 负责让 go.mod 和源码中的依赖关系对齐；它不会替你自动更新已存在的 vendor 目录。

# 只有在源码依赖或 go.mod 确实需要整理时才执行 tidy
go mod tidy

# 根据当前模块图整体重建 vendor 和 vendor/modules.txt
go mod vendor

# 查看清单是否已经包含目标模块及其包路径
go list -mod=vendor -m all

go mod vendor 会先移除已有 vendor 再重建，因此本地不应把业务改动长期写进 vendored 包。若团队需要审阅依赖变化，让 Git 记录 go.mod、go.sum、vendor/ 和 vendor/modules.txt 的同一提交，避免只提交其中一部分。

单模块和工作区分别怎么修

存在 go.work 时，模块集合和替换规则可能来自多个工作区模块。此时不要一边用 go mod vendor，一边期待得到工作区级的 vendor 结果；应让生成入口和构建入口属于同一个作用域。

# 单模块项目：关闭工作区语义后生成当前模块的 vendor
GOWORK=off go mod vendor

# 工作区项目：在 go.work 所在作用域生成 workspace vendor
go work vendor

# 用工作区的 vendor 树检查所有主模块
go test -mod=vendor ./...

本地依赖尤其容易造成错配：replace example.com/lib => ../lib 写在 go.mod，但构建实际处于 go.work 作用域时，清单中的替换标记就必须反映有效的工作区规则。不要为了消除报错而手改清单里的版本或 ## explicit；应修复声明来源后再次生成。

用 vendor 模式做一次反向验证

修复后的检查重点不是“文件看起来更新了”，而是构建能否仅依赖当前 vendor 树。先跑列表命令确认模块图，再跑测试；如果 CI 禁止联网，这个检查更有价值。

# 检查模块和包都从 vendor 作用域解析
go list -mod=vendor ./...

# 执行项目测试；失败时保留第一条缺包或清单不一致信息
go test -mod=vendor ./...

若仍报不一致，回到三件事：go.mod 是否刚被合并或改写、是否存在生效的 replace、当前目录是否被 go.work 接管。只有当这三层一致时，删掉缓存或反复重试才有意义。

常见问题

改了 go.mod 后只运行 go mod tidy 可以吗？

不够。tidy 整理模块声明和 go.sum，vendor 清单仍需用 go mod vendor 或 go work vendor 重建。

可以直接删除 vendor/modules.txt 吗？

不建议。它记录 vendored 包来自哪些模块及版本；删除它可能让启用 vendor 的构建无法完成一致性检查。应从声明源重新生成。

为什么本地 replace 最容易触发这个问题？

因为替换既改变依赖来源，也改变清单需要表达的关系。单模块与工作区的有效替换不一定相同，生成和构建必须使用同一作用域。