Go vendor 怎么生成离线依赖并检查版本一致

构建机不能联网时，Go 项目要提交的是由 go mod vendor 根据当前模块图生成的 vendor 目录，而不是手工复制某个缓存目录。生成后，Go 会读取 vendor/modules.txt 对照 go.mod 中的版本、显式依赖和替换关系；再用 GOPROXY=off 配合 -mod=vendor 构建，才能确认离线依赖确实完整。

最稳妥的流程是：联网准备机运行 go mod tidy（仅在确实需要整理模块图时）和 go mod vendor，提交 go.mod、go.sum、vendor/；离线构建机只读 vendor，用一致性检查和无网络构建验收。

先确认 vendor 解决的是离线构建，不是依赖解析

go.mod 描述模块图和版本选择，go.sum 保存下载模块的校验信息，vendor/ 则把当前主模块构建和测试需要的源码放在项目树里。三者职责不同：vendor 不是新的依赖声明，也不能代替 go mod tidy 发现遗漏的直接依赖。

当主模块的 go 指令为 1.14 或更高、根目录存在 vendor 时，Go 命令通常会自动采用 vendor；在 CI 中仍建议显式写 -mod=vendor，让构建意图一眼可见。此模式不访问网络，也不从模块缓存加载第三方包，但 go mod tidy、go mod download 这类修改或准备模块图的命令并不会因此变成离线命令。

用 go mod vendor 生成可提交的 vendor 目录

在能正常下载依赖的准备机上，从包含 go.mod 的主模块根目录执行：

# 先让模块图反映当前源码的实际导入关系
go mod tidy

# 按主模块的构建与测试需求重建 vendor 和版本清单
go mod vendor

# 查看本次生成涉及的模块和包，便于提交前留痕
go mod vendor -v

命令会重建 vendor/，并生成 vendor/modules.txt。不要直接在 vendor 下编辑第三方源码；如果必须修改依赖，应通过版本升级、replace 或维护自己的模块来表达，之后重新生成。检查提交内容时，至少确认 go.mod、go.sum、vendor/modules.txt 和实际包目录来自同一次生成。

用 modules.txt 和 GOPROXY=off 检查版本一致

最常见的报错是 inconsistent vendoring。它通常不是网络问题，而是 go.mod 已经改过，vendor 仍是旧生成结果；也可能是 replace 目标、显式依赖标记或某个包没有同步到 modules.txt。处理原则只有一个：回到依赖准备机重新运行 go mod vendor，不要手改清单凑结果。

# 让 Go 只使用项目根目录的 vendor
go list -mod=vendor -m all

# 关闭代理，避免遗漏依赖被网络悄悄补齐
GOPROXY=off go test -mod=vendor ./...

# 构建也使用同一条离线路径
GOPROXY=off go build -mod=vendor ./...

如果第二条命令提示找不到模块，说明 vendor 不完整或构建标签下仍有未收录的包；如果直接报 vendoring 不一致，优先比较 go.mod 的 require/replace 与 vendor/modules.txt，然后重新生成。go mod verify 只验证模块缓存中已下载内容的哈希，适合检查准备机缓存是否被修改，不能替代上面的 vendor 一致性和离线构建检查。

依赖变更后的更新与回退清单

回退时不要只恢复 vendor/ 而留下新的 go.mod；这会把版本声明和源码树拆成两套状态。更可靠的做法是把三类文件视为同一变更单元，回退后再次运行 go list -mod=vendor -m all，再执行离线测试。

常见问题

vendor 目录存在，为什么 Go 还提示缺包？

先确认命令是在主模块根目录执行，并且缺少的包属于当前主模块的构建或测试集合；再检查是否是特殊 build tag 或外部模块测试未被纳入。用 go mod vendor 重建后，配合 GOPROXY=off 重试最容易定位。

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

不建议。vendor 提供源码树，go.mod 和 go.sum 仍是模块声明与校验记录；三者一起提交，后续更新、回退和审查才有一致的依据。

为什么不直接把 GOPROXY 设置成 off 再运行 go mod vendor？

go mod vendor 是准备依赖树的命令，缺少模块时需要读取模块源或缓存。应先在可联网环境完成生成，再在离线环境用 GOPROXY=off 验收构建路径。