Go vendor inconsistent dependencies 怎样恢复一致

Go 项目出现 inconsistent vendoring 或 vendor inconsistent dependencies 时，通常不是某个依赖突然“消失”，而是 go.mod 已经变化，vendor/modules.txt 还保留着旧的模块版本或依赖标记。恢复一致的核心动作是：先确定最终模块图，再用 go mod vendor 重新生成 vendor 目录，最后明确使用 vendor 模式复查构建。

官方资料：https://go.dev/ref/mod

不要手工修改 vendor/modules.txt 来“对齐”报错行。它是由模块图生成的清单，正确修复应回到 go.mod、go.sum 和源码依赖，再整体重建 vendor。

• 声明边界：go.mod 描述主模块依赖，go.sum 保存校验信息。
• 生成边界：go mod vendor 根据当前模块图生成 vendor 包和 vendor/modules.txt。
• 构建边界：启用 vendor 后，go build、go test 等构建命令从 vendor 读取依赖。

为什么会出现 vendor inconsistent dependencies

Go Modules Reference 说明，vendor/modules.txt 记录了被复制进 vendor 的模块版本和包；当 Go 读取它时，会把清单中的模块信息与 go.mod 对照。如果 go.mod 在上一次生成 vendor 之后发生过增删、升级、降级、替换或间接依赖标记变化，构建就可能在进入编译前直接报不一致。

还要注意版本边界：当主模块的 go 指令为 1.14 或更高且根目录存在 vendor 时，构建命令默认可能按 vendor 模式工作；也可以显式传入 -mod=vendor。因此，这类错误经常只在 CI、发布机或某个工具链版本中出现——它们真正读取的是本地 vendor 清单，而不是你以为已经更新的模块缓存。

先固定真正要使用的模块图

恢复前先把“最终要发布的依赖版本”定下来。若最近只改了源码或合并了依赖变更，先在模块根目录检查 Go 识别到的主模块路径，再决定是否需要整理依赖。不要为了让报错消失而随意删除一段 require，否则 vendor 可能暂时一致，却把源码真正需要的包从构建输入中移走。

# 确认命令运行在包含 go.mod 的模块根目录，并查看当前工具链信息
go env GOMOD GOVERSION

# 读取当前模块图；这里的输出用于判断依赖是否仍被源码或测试使用
go list -m all

# 只有在源码依赖已经确定后，才整理 go.mod 和 go.sum
# tidy 会补齐需要的模块并移除不再提供相关包的要求
go mod tidy

go mod tidy 和 go mod vendor 不是同一件事。前者让 go.mod、go.sum 与源码包集合匹配，后者把已经确定的模块图物化为 vendor 目录。若项目有工具包、测试包或特定构建标签，整理依赖时也要以项目的真实构建约束为准，不能只看某一个业务包能否编译。

用 go mod vendor 整体重建清单与包目录

确认模块声明后，在模块根目录运行 go mod vendor。该命令会重建 vendor，并生成与当前模块图对应的 vendor/modules.txt。官方文档明确提醒，已有 vendor 会在重建前被移除，因此不要在 vendor 包目录里保存需要长期维护的本地改动。

# 在最终 go.mod 和 go.sum 已确定后重建 vendor 目录与模块清单
go mod vendor

# 需要查看重建涉及哪些模块时，可以保留详细输出
go mod vendor -v

如果这个命令本身无法完成，先区分是模块下载、私有仓库认证还是源码加载问题；不要直接编辑 vendor/modules.txt。GOPROXY、GOPRIVATE 等环境变量只影响模块获取与校验边界，不能替代 vendor 清单的生成。对于离线构建，重建动作应在依赖已可获取的环境中完成，再把完整 vendor 目录交给离线构建机。

用 vendor 模式确认修复结果

重建后不要只检查文件是否出现，而要让检查命令明确使用 vendor。这样可以把“清单已一致”和“源码本身还有编译错误”分开判断。

# 强制构建读取 vendor，避免检查结果被模块缓存或网络依赖掩盖
go test -mod=vendor ./...

# 只想先构建全部包时，可使用同样的 vendor 边界
go build -mod=vendor ./...

如果命令不再报告 vendoring 不一致，但随后出现普通编译错误，说明清单漂移已经解决，剩下的是源码、平台构建约束或测试本身的问题。如果仍然出现同类错误，回到模块根目录确认实际生效的 go.mod，检查 CI 是否使用了另一份工作目录、另一套工具链或未更新的 vendor 产物。

常见问题

只执行 go mod tidy，能解决 vendor inconsistent dependencies 吗？

通常不能。go mod tidy 调整的是 go.mod 和 go.sum；如果项目仍使用 vendor，还需要在最终模块图确定后执行 go mod vendor，让包目录和 vendor/modules.txt 一起更新。

可以手工删除 vendor/modules.txt 中的冲突模块吗？

不建议。该文件是 vendor 生成的模块版本清单，手工删除可能让当前报错换成缺包或版本错误。应修正真正的模块声明，再整体重建。

为什么本地能编译，CI 却报不一致？

常见原因是两边使用了不同的工作目录、Go 工具链、分支内容或 vendor 产物。CI 可以显式使用 -mod=vendor，并在构建前确认提交中的 go.mod、go.sum 与 vendor/ 属于同一份变更。