Go vendor 模式和模块缓存结果不同怎么办

如果同一个 Go 项目在本地能编译，切到 CI 或去掉 vendor 后却得到不同结果，先不要把它归咎于“模块缓存脏了”。最常见的原因是两次构建读取的依赖来源不同：-mod=vendor 从项目根目录的 vendor 读取，-mod=mod 才会继续使用模块缓存并允许更新模块文件。

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

排查这类差异的核心是先固定来源，再比较版本清单。确认命令实际使用的模式、vendor/modules.txt 是否和 go.mod 对得上，最后统一 Go 版本与工作区入口，通常就能恢复一致结果。

先确认构建到底从哪里读依赖

同一个包名可能同时出现在模块缓存和 vendor，但 Go 命令不会把两处内容合并。官方规则是：-mod=vendor 使用 vendor，不访问网络或模块缓存；-mod=mod 忽略 vendor，并允许自动更新 go.mod。当 go.mod 中的 Go 版本不低于 1.14 且根目录存在 vendor 时，默认行为通常等同于 -mod=vendor。

# 先记录工具链、模块根目录和当前工作区入口
go version
go env GOMOD GOWORK GOFLAGS

# 明确使用 vendor，构建和测试都从项目根目录的 vendor 取包
go test -mod=vendor ./...

# 明确忽略 vendor，使用模块缓存；这里只用于对照来源差异
go test -mod=mod ./...

如果两条命令的编译结果或报错不同，这个差异本身已经说明问题不在“同一份依赖的随机解析”，而在两套输入树。注意 go list -m 主要报告 go.mod 中的模块信息，不能把它当成 vendor 目录内容的逐文件证明。

检查 vendor/modules.txt 是否还是旧清单

go mod vendor 会在主模块根目录重建 vendor，并生成 vendor/modules.txt，其中记录被复制的模块版本和包。启用 vendoring 时，Go 会用这个清单提供模块版本信息，并检查它与 go.mod 是否一致；如果 go.mod 已经变化而 vendor 没有重建，构建会直接提示清单不一致。

# 先看模块声明和 vendor 清单是否处于同一次变更
git diff -- go.mod go.sum vendor/modules.txt

# 重新生成项目根目录的 vendor 树，不手工编辑其中的第三方包
go mod vendor

# 重新生成后查看依赖清单的变更范围
git diff --stat -- go.mod go.sum vendor/modules.txt

不要直接修改 vendor 下的第三方源码来“修复”结果。官方文档说明，go mod vendor 会先移除旧的 vendor 目录再重建；因此正确做法是修改主模块的依赖声明或源码，再重新生成整棵依赖树。

把工作区和工具链输入也纳入比较

如果一个命令在仓库根目录执行，另一个命令在包含 go.work 的父目录执行，参与模块解析的边界可能已经改变。GOFLAGS 还可能暗中带上 -modfile，使命令读取另一份 .mod 和由它推导出的 .sum。这类差异看起来像缓存问题，实际是入口文件不同。

# 对照 CI 和本地的入口变量，不要把凭据写入日志
go env GOMOD GOWORK GOFLAGS GOPROXY GOPRIVATE GONOPROXY GONOSUMDB

# 从主模块根目录执行，确认实际使用的 go.mod 路径
go env GOMOD

# 如果项目明确采用工作区，提交并固定 go.work 的成员范围
go work edit -json

同时比较 CI 使用的 Go 版本、分支内容和构建标签。工具链版本会影响模块图的读取规则；如果只想验证依赖来源，先不要把升级 Go 版本和重写 vendor 混在同一个提交里。

按团队目标固定一种发布方式

如果目标是离线构建或让构建输入随仓库一起交付，就把 go.mod、go.sum、vendor 和 vendor/modules.txt 作为同一组变更管理，并在 CI 中显式使用 -mod=vendor。如果目标是由代理和模块缓存管理依赖，则不要让旧的 vendor 目录被默认拾取，可以显式使用 -mod=mod 或 -mod=readonly，并统一缓存与代理配置。

# 离线/随仓库交付：依赖树由 go.mod 生成后固定进构建
go mod vendor
go test -mod=vendor ./...

# 代理/缓存交付：禁止构建阶段悄悄改写 go.mod
go test -mod=readonly ./...

# 发现两种来源不同，不要混合提交；先保留成对 diff 再决定方案
git diff -- go.mod go.sum vendor/modules.txt

可以把“来源模式、Go 版本、工作区路径、模块清单”写进 CI 的构建说明。这样下次出现差异时，先看输入边界就能判断是需要重建 vendor，还是应该清理默认 vendoring，而不是反复删除模块缓存。

快速结论：四个检查点定位差异

• 命令来源：是否一个使用 -mod=vendor，另一个使用 -mod=mod。
• 版本清单：vendor/modules.txt 是否在 go.mod 变化后重新生成。
• 入口边界：GOWORK、GOFLAGS 和执行目录是否一致。
• 交付策略：团队究竟要仓库内 vendor，还是代理与模块缓存。

vendor 与模块缓存结果不同并不意味着 Go 的解析不稳定，而是两次构建选择了不同的依赖来源。把来源模式显式化，再让清单和工具链跟着同一套输入更新，问题就会变成可审查的依赖变更。

相关问题

为什么项目有 vendor 目录却没有使用它？ 先看 go.mod 的 Go 版本、vendor/modules.txt 是否存在且一致，以及 GOFLAGS 是否显式指定了其它模式。

能不能手动删除 vendor 里的某个包？ 不建议。依赖树应由 go mod vendor 根据主模块重新生成，手工删除会让清单和源码树失去对应关系。

为什么 go mod tidy 仍然访问模块缓存？ vendoring 主要改变构建和测试加载包的来源，go mod 命令本身仍可能下载模块并访问模块缓存。