Go 项目怎么打包依赖以支持离线构建

Go 项目要在没有外网的构建机上编译，最稳妥的交付物不是只复制开发机的模块缓存，而是在联网环境运行 go mod vendor，把生成的 vendor/ 和 vendor/modules.txt 随源码一起打包。构建时使用 GOPROXY=off go build -mod=vendor ./...，Go 就会从项目根目录的 vendor 树加载依赖，不再访问网络或本地模块缓存。

离线构建失败先看什么

先确认命令是在包含 go.mod 的主模块根目录执行。Go Modules Reference 规定，go mod vendor 只为主模块中构建和测试所需的包生成依赖树；只被主模块之外的测试引用的包不会被带入。因此，复制一个看似很大的旧缓存，不能证明当前源码可以离线构建。

准备机上建议先把模块文件整理干净，再查看项目状态：

# 先让 go.mod 与源码中的导入保持一致
go mod tidy

# 查看主模块和依赖版本，确认准备的是当前项目
go list -m all

go mod tidy 仍可能访问模块代理，所以它属于联网准备阶段。断网环境只负责构建和测试，不负责补依赖。

依赖打包怎么做

在依赖已经能正常解析的联网准备机执行：

# 在包含 go.mod 的主模块根目录生成依赖副本
go mod vendor

# 可选：打印本次写入的模块和包，便于保存到构建日志
go mod vendor -v

命令会重建 vendor/，并创建 vendor/modules.txt。不要直接编辑 vendor 下的第三方源码；官方文档明确说明，重新生成前会移除已有 vendor 目录，本地修改会丢失。交付时至少包含源码、go.mod、go.sum、vendor/ 和 vendor/modules.txt。如果仓库用 Git 管理，通常应把这棵树作为普通文件提交或放入构建制品，而不是依赖某台机器的缓存目录。

无网络环境如何强制使用 vendor

构建机上把网络和缓存变量设成明确值，并把模式写进 CI 脚本。-mod=vendor 让 Go 使用 vendor；GOPROXY=off 则让缺失依赖直接暴露，而不是等待代理：

# 断网构建：缺少 vendor 依赖时立即失败
GOPROXY=off go build -mod=vendor -o bin/service ./cmd/service

# 断网测试：测试也使用同一棵 vendor 树
GOPROXY=off go test -mod=vendor ./...

Go 1.14 及更高版本在主模块根目录存在且一致的 vendor 时，默认可能自动采用 vendor，但交付脚本仍建议显式写出 -mod=vendor，这样换构建机或调整 go 指令后行为更容易审计。注意，go mod download 和 go mod tidy 不会因为启用了 vendor 就变成离线命令；不要把它们放在断网发布阶段。

go.mod 改了之后如何回滚与复查

如果构建报出 vendor 与 go.mod 不一致，优先把它看成交付物版本错配，而不是先改构建参数。官方规则是：vendor/modules.txt 中的模块版本必须与 go.mod 一致；依赖声明变化后应重新运行 go mod vendor。

正确的处理有两条路径：若新依赖确实要发布，在联网准备机提交新的 go.mod、go.sum、vendor/ 和 vendor/modules.txt；若这次改动不应进入发布包，则回退这四部分到同一个提交或制品版本，不能只回退其中一个文件。随后再次使用 GOPROXY=off 执行构建和测试。

值班排查可以记住三项：构建目录是否为主模块根目录，vendor 是否来自当前 go.mod，CI 是否偷偷使用了 go mod download。这三项都满足，离线失败通常会收敛为缺少源码包、平台构建约束或项目自身编译错误，而不是依赖来源不明。

常见问题

只复制 GOPATH 或 GOMODCACHE 能不能离线构建？

不建议。缓存是机器级状态，交付边界不清晰；vendor 随项目保存，版本和源码更容易一起审计。

vendor 目录应该放在哪里？

放在主模块根目录，也就是包含 go.mod 的目录。其他模块内部的 vendor 不会被当前主模块构建自动采用。

vendor 生成后还能手工改第三方代码吗？

不要这样做。后续再次运行 go mod vendor 会重建目录；需要修改依赖时，应使用明确版本、replace 或维护自己的模块。

参考：Go Modules Reference：Vendoring。