go mod vendor 保持离线构建依赖一致的方法

如果 Go 项目需要在无网络的构建机上稳定编译，核心不是把模块缓存目录整体搬过去，而是把依赖快照固定在主模块根目录：先在依赖可取得的环境运行 go mod vendor，提交 vendor/ 与 vendor/modules.txt，再让构建和测试明确使用 -mod=vendor。这样每次构建读取同一份本地依赖树，网络是否可用就不会改变依赖来源。

官方地址：https://go.dev/ref/mod#go-mod-vendor

本文只解决“离线构建依赖如何保持一致”这一件事。Go 官方文档说明，go mod vendor 会在主模块根目录构造 vendor/，并生成记录模块版本与包的 vendor/modules.txt；构建时使用 -mod=vendor，Go 命令会从 vendor 目录加载，而不使用网络或本地模块缓存。

先明确四个一致性对象

离线构建是否可复现，取决于声明、校验、清单和代码副本是否来自同一状态。不要只把 vendor/ 当作一个可以随意复制的文件夹。

其中 vendor/modules.txt 很关键：Go 命令会用它获取 vendored 模块的版本信息，并检查这些版本是否与 go.mod 一致。把四个对象作为同一次依赖变更的一部分提交，才能让审查者知道清单和代码副本没有脱节。

在联网准备环境生成依赖快照

go mod vendor 本身是准备动作，应放在依赖可以正常解析的开发机或构建准备机上。进入包含 go.mod 的主模块根目录执行：

# 进入主模块根目录，避免把其他目录误当成模块输入
cd /path/to/your-module

# 按当前 go.mod、源码和测试所需包重新构造 vendor 目录
go mod vendor

# 查看被写入清单的模块和包，数字可作为依赖快照指标
grep -c '^# ' vendor/modules.txt
find vendor -type f | wc -l

这里的两个数字不是 Go 的版本结论，而是适合写入构建记录的可复现指标：模块清单条目数帮助发现依赖范围变化，vendor 文件数帮助发现副本规模变化。不要手工向 vendor/ 填文件来“修复”缺失依赖；重新生成才是稳定的修复入口。

官方文档还特别说明，go mod vendor 会先移除已有的 vendor 目录再重建，因此不要直接修改其中的第三方包。若项目的 go.mod、源码或构建条件发生了会影响依赖集合的变化，应在联网准备环境再次生成，然后把对应的四个对象一起提交。

固定离线构建和测试入口

生成快照之后，构建脚本要明确告诉 Go 使用 vendor。-mod=vendor 的意义是使用主模块根目录的 vendor 目录；它不是“优先使用缓存”，而是把依赖来源限定为这棵本地树。为避免脚本误把网络恢复当成成功条件，可以同时关闭模块代理和校验数据库：

# 强制构建只读取主模块的 vendor 目录，不依赖网络和模块缓存
GOPROXY=off GOSUMDB=off go build -mod=vendor ./...

# 测试使用同一份 vendor 快照，失败时保留原始错误便于定位
GOPROXY=off GOSUMDB=off go test -mod=vendor ./...

如果项目的 go.mod 中 Go 版本不低于 1.14，并且 vendor/modules.txt 与 go.mod 一致，Go 命令还可能自动进入 vendor 模式；不过在 CI 脚本中显式写出 -mod=vendor 更容易读懂，也不依赖构建机对默认行为的理解。

把一致性变成可记录的构建指标

“离线成功”不应只记录一个绿色状态。可以把依赖快照和构建结果分成三组指标：模块清单条目数、vendor 文件数、构建与测试结果。它们分别回答依赖范围有没有变化、副本是否齐全、代码是否能在禁网条件下消费这份副本。

# 记录依赖快照的两个规模指标，便于和上一次提交比较
module_count=$(grep -c '^# ' vendor/modules.txt)
vendor_file_count=$(find vendor -type f | wc -l)

# 将指标写进 CI 日志；这里不输出依赖内容、路径或凭据
printf 'vendored_modules=%s vendored_files=%s\n' "$module_count" "$vendor_file_count"

# 只有 build 与 test 都通过，离线构建门槛才算满足
GOPROXY=off GOSUMDB=off go build -mod=vendor ./...
GOPROXY=off GOSUMDB=off go test -mod=vendor ./...

比较指标时重点看变化是否有解释：新增功能可能让模块数上升，删除功能可能让文件数下降；如果数字变化却没有对应的 go.mod 或源码变更，就应该回到依赖准备阶段查原因。指标用于定位漂移，不代替编译和测试本身。

遇到清单漂移时怎样修复

当 Go 报告 vendor/modules.txt 与 go.mod 不一致时，优先把它当作“依赖快照过期”处理，而不是去改清单中的一行文本。先在可解析依赖的环境确认当前分支和模块文件，再重新生成 vendor：

# 先确认当前模块上下文，避免在错误的工作区目录生成快照
go env GOMOD GOWORK

# 重新根据当前模块状态生成 vendor 和 modules.txt
go mod vendor

# 查看依赖快照相关差异，确认是否与本次模块变更相符
git diff -- go.mod go.sum vendor/modules.txt vendor

如果差异来自预期的依赖升级，就把 go.mod、go.sum、vendor/modules.txt 和 vendor/ 作为一个变更提交；如果差异来自错误的工作区或未预期的源码分支，先修正输入再生成。不要在离线构建机上运行 go mod vendor 作为排查手段，因为它可能需要解析依赖，而离线构建阶段的目标是消费已经准备好的快照。

适用边界与常见误区

• vendor 不是所有模块命令的离线开关：go build 和 go test 可以从 vendor 加载，但 go mod tidy、go mod download 等模块维护命令仍可能访问模块缓存或网络。
• 不要把任意 vendor 目录当成当前项目依赖：Go 命令关注主模块根目录的 vendor，其他模块内部的 vendor 不会自动成为当前构建的来源。
• 不要只提交清单：vendor/modules.txt 只是版本和包的索引，离线构建仍需要对应的 vendor/ 代码副本。
• 不要把测试范围想得过大：go mod vendor 会覆盖主模块构建和测试所需的包，但不会把只被主模块之外的包测试导入的依赖全部纳入。
• 不要手改第三方副本：本地修改会让快照难以复现，应该通过模块版本、replace 规则或源码变更重新生成。

结论：把 vendor 当作一次依赖快照

保持 Go 离线构建一致，最稳的做法是把 go.mod、go.sum、vendor/modules.txt 和 vendor/ 视为一个版本化快照：在联网准备环境运行 go mod vendor，提交完整快照，在 CI 中用 GOPROXY=off GOSUMDB=off go build -mod=vendor ./... 与对应的测试命令消费它，并用模块数、文件数和构建结果记录变化。清单漂移时重新生成，不手工修补 vendor。

相关问题

go mod vendor 能在完全断网的构建机上运行吗？

它的职责是重新解析当前模块状态并构造 vendor，通常应放在依赖可取得的准备环境完成。离线构建机更适合直接消费已经提交的 vendor/ 和 vendor/modules.txt。

为什么只提交 vendor/modules.txt 仍然无法离线编译？

清单只记录模块版本和包范围，真正参与编译的源文件仍在 vendor/ 中；两者缺一不可。

可以只用 GOPROXY=off 来证明构建是离线的吗？

不够。还应显式使用 -mod=vendor，并确保主模块根目录的 vendor 快照与 go.mod 一致；否则命令可能因模块来源不完整而失败，却不能说明 vendor 快照本身是否正确。