Go modules 怎样让 vendor 模式可复现

如果同一份 Go 代码在开发机能构建，到了没有网络或模块缓存不同的环境却失败，通常不是把 vendor 目录提交上去就结束了。可复现的关键是让 go.mod 记录的依赖版本、vendor/modules.txt 的快照和构建时采用的依赖来源保持一致。

官方资料：https://go.dev/doc/

稳定做法是：先整理 go.mod 与 go.sum，再执行 go mod vendor 生成快照；构建时显式使用 -mod=vendor，依赖变化后重新生成并把快照作为同一变更提交。

• 版本来源：go.mod 是主模块依赖图的声明，go.sum 保存模块校验记录。
• 本地快照：vendor 保存构建和测试需要的依赖包，vendor/modules.txt 记录来源模块及版本。
• 构建开关：-mod=vendor 让构建从 vendor 读取，不访问网络或模块缓存。

先把可复现拆成依赖声明和依赖快照

Go modules 默认会从模块源下载依赖到模块缓存，再从缓存加载包。vendor 模式则把主模块构建和测试所需的包复制到项目根目录下的 vendor，让源码树里出现一份可审阅、可随代码提交的依赖快照。

这几个文件不要混为一谈：go.mod 描述主模块和所需版本，go.sum 记录模块内容的校验信息，vendor 放实际被复制的包，vendor/modules.txt 是 vendored 包与模块版本之间的清单。可复现不是只追求“目录存在”，而是追求这些对象表达同一棵依赖树。

用 go mod vendor 生成团队可共享的快照

在准备提交 vendor 之前，先让主模块依赖声明回到可读、可维护的状态。常见的固定组合如下：

# 先整理主模块依赖声明，再生成与当前代码匹配的 vendor 快照
go mod tidy
go mod vendor

# 显式让构建只从 vendor 读取依赖，不访问网络或模块缓存
go build -mod=vendor ./...
go test -mod=vendor ./...

go mod vendor 会在主模块根目录重建 vendor，同时生成 vendor/modules.txt。官方参考说明它包含被 vendored 的包及其来源模块版本；因此依赖变更后，应该把 go.mod、必要的 go.sum、vendor 和 vendor/modules.txt 视为一组变更，而不是只提交其中一个文件。

这里的“可复现”也有边界：它固定的是构建所需的模块文件树，不会替你固定操作系统、编译器补丁版本、环境变量或外部服务。项目如果还依赖生成代码、系统库或私有工具，仍要单独记录那些输入。

为什么 go.mod 改了以后 vendor 构建会报错

启用 vendoring 时，Go 会读取 vendor/modules.txt 作为模块版本信息，并检查它是否与 go.mod 一致。也就是说，手工修改 go.mod、升级某个依赖，或者切换分支后继续沿用旧 vendor，都可能使声明与快照脱节。

遇到这类错误时，先问一个简单问题：当前提交是否同时更新了依赖声明和快照？如果依赖确实发生了变化，回到允许联网或具备模块缓存的依赖准备环境，重新执行 go mod tidy 和 go mod vendor，再把生成结果一并提交。不要直接编辑 vendor/modules.txt 伪造版本关系，因为它不是独立的依赖声明入口。

把固定检查点放进协作和 CI

我更倾向于把 vendor 当作一次有边界的依赖快照，而不是开发者随手修改的源码副本。日常开发可以在专门的依赖更新变更中执行整理和生成；普通业务提交只消费已有快照。这样审查时能清楚看到“依赖版本变化”和“vendor 内容变化”是否来自同一件事。

构建脚本可以统一带上 -mod=vendor，减少不同 Go 版本或不同本地缓存带来的歧义。若项目使用的 go 指令版本不低于 1.14，且根目录存在与 go.mod 一致的 vendor，Go 也可能默认采用 vendor；但在 CI 中显式写出开关更容易阅读，也能避免读者把“默认行为”误认为所有环境都一样。

依赖更新的复查点可以保持很小：确认 go.mod 变更是有意的；确认 vendor/modules.txt 与新版本对应；确认构建和测试命令使用相同的 -mod 策略；确认不把本地手改内容留在 vendor 中。官方文档还指出，go mod vendor 会先移除已有 vendor 再重建，所以不要在其中保存需要长期维护的业务修改。

常见问题

只提交 vendor，不提交 go.sum 可以吗？

不建议把它当成通用规则。go.mod、go.sum 和 vendor 的职责不同；应按项目的依赖管理约定提交，至少确保依赖声明、校验记录和 vendor 快照没有互相矛盾。

有 vendor 目录后还需要写 -mod=vendor 吗？

在满足特定 go 指令版本和清单一致等条件时，Go 可能默认使用 vendor；为了让构建意图明确，团队脚本和 CI 通常更适合显式写出 -mod=vendor。

go mod tidy 和 go mod vendor 谁先执行？

通常先整理依赖声明，再根据当前主模块生成 vendor。顺序的核心不是命令本身，而是不要用旧的依赖声明生成新快照。

vendor 能保证完全相同的构建结果吗？

它主要固定模块依赖文件树和加载来源，不能单独固定编译器、操作系统、生成工具或外部服务。要实现更完整的可复现构建，还需把这些环境输入纳入工程配置。

把 vendor 看成“可审阅的依赖快照”会更准确：依赖声明负责表达选择，vendor 负责保存构建所需文件，-mod=vendor 负责让构建使用这份快照。三者一起维护，才能让离线构建、CI 和开发机之间的差异更容易被发现和解释。