Go work vendor 离线构建多模块工作区的依赖落盘方案

多模块项目已经用 go.work 串起来，但构建机不能访问模块代理时，单独执行 go mod vendor 往往只处理一个主模块。更稳妥的做法是进入工作区根目录执行 go work vendor，让 Go 按工作区中所有模块的构建依赖生成一份共享的 vendor 目录。

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

先把工作区边界确认清楚

Go 会先看 GOWORK。它为空时，命令会从当前目录向父目录寻找 go.work；设置为 off 则强制回到单模块模式。因此同一条命令在工作区根目录和子模块目录执行，结果可能完全不同。

# 查看当前命令实际使用的工作区文件
go env GOWORK

# 查看工作区构建列表，确认模块是否都已纳入
go list -m all

# 只在工作区根目录维护模块列表
go work use ./service-a ./shared

如果 go env GOWORK 为空，先不要生成 vendor。检查当前路径、GOWORK 环境变量和 go.work 的 use 路径，避免把不完整的依赖树固化下来。

用 go work vendor 生成共享依赖目录

确认工作区后，在 go.work 所在目录执行命令：

# 在 go.work 所在目录生成工作区级 vendor
go work vendor

# 需要观察纳入了哪些模块时使用详细输出
go work vendor -v

命令会重建工作区的 vendor 目录，并写入 vendor/modules.txt。不要手工改 vendored 包；依赖变化后重新执行命令，才能让目录内容和模块图同步。若要把输出放到其他目录，可以使用 -o，但 Go 构建默认只识别模块根目录下名为 vendor 的目录。

离线构建时要固定入口和一致性检查

生成 vendor 后，构建命令仍应从工作区根目录或明确的工作区路径启动。go build、go test 等构建命令会优先读取 vendor；但 go mod tidy、go get 等模块维护命令并不会因为 vendor 存在就变成离线命令，它们仍可能访问模块缓存或网络。

出现 “inconsistent vendoring” 一类错误时，优先比较各模块的 go.mod、工作区的 go.work 与 vendor/modules.txt。不要只删掉错误信息对应的一行；直接从当前工作区重新生成通常更可靠。

常见问题

为什么在子模块执行 go work vendor 结果不符合预期？

命令的工作区判断受当前路径和 GOWORK 影响。先用 go env GOWORK 确认实际文件，再回到工作区根目录执行。

go work sync 和 go work vendor 是一回事吗？

不是。go work sync 把工作区构建列表同步到各模块的 go.mod；go work vendor 则重建工作区级 vendor 目录，解决构建时的依赖落盘问题。

vendor 目录可以提交到仓库吗？

可以，但要把它当作由模块文件生成的交付物管理。模块依赖或源码导入变化后重新生成，并在 CI 中检查 vendor/modules.txt 是否随之更新。

这套方案的关键不是把所有模块都复制一份依赖，而是让 go.work 定义的工作区、生成命令的执行目录和交付时的 vendor 目录使用同一条边界。单模块发布和多模块离线构建应分别选择对应命令。