Go模块离线构建方法解析

Go模块支持可靠的离线构建，但需严格满足前提条件：所有依赖已完整缓存于本地（如`$GOMODCACHE`目录）、`go.mod`和`go.sum`未被篡改且校验通过；首次联网构建后，只要不执行`go get`、不修改依赖版本、不触发模块自动更新，后续`go build`即可完全断网运行。通过`GOPROXY=off GOSUMDB=off go build -mod=readonly`组合可强制实现确定性离线行为，而`go mod verify`和`go mod download -json`是验证缓存完整性与定位缺失依赖的关键工具——尤其在CI/CD中，仅靠`go mod vendor`并不足以保证真正离线，必须预下载缓存或携带完整的模块缓存快照，才能规避网络请求陷阱，让构建稳定、安全、可重现。

Go build 能否完全离线运行

可以，但前提是所有依赖模块已缓存在本地 pkg/mod 目录中，且 go.mod 和 go.sum 文件完整、未被篡改。Go 1.13+ 默认启用 GOPROXY=https://proxy.golang.org,direct，首次构建会自动下载并缓存模块；只要不执行 go get 或修改 require 版本，后续 go build 不触发网络请求。

如何确认依赖已全部缓存

检查 $GOPATH/pkg/mod（或 $GOMODCACHE 指向的路径）是否存在对应模块目录，例如 github.com/go-sql-driver/mysql@v1.7.1。更可靠的方式是运行：

go mod verify

若输出 all modules verified，说明 go.sum 中记录的哈希与本地缓存内容一致；若报错 missing zip hash 或 mismatched hash，代表缓存损坏或缺失，此时即使有文件也无法离线构建。

• go mod download -json 可列出所有依赖及其本地路径，快速定位缺失项
• 若项目含 replace 指向本地路径（如 replace example.com/foo => ../foo），该路径必须真实存在且可读，否则离线构建失败
• go list -m all 在离线状态下会报错 no required module provides package —— 这是正常现象，不代表构建失败，go build 本身不依赖此命令

强制离线构建的三种有效方式

Go 没有全局 “offline mode” 开关，但可通过组合环境变量和参数实现确定性离线行为：

• 设置 GOPROXY=off：彻底禁用代理和 direct 回源，任何缺失模块都会直接报错 module not found
• 设置 GOSUMDB=off：跳过校验服务器（如 sum.golang.org），仅依赖本地 go.sum；注意这会削弱完整性保障
• 搭配 go build -mod=readonly：禁止自动修改 go.mod 或下载新依赖，一旦发现需更新模块就终止构建

最稳妥的离线构建命令是：

GOPROXY=off GOSUMDB=off go build -mod=readonly

CI/CD 中离线构建的关键陷阱

很多 CI 流程误以为 go mod vendor 后就能断网构建，其实不然：

• vendor/ 目录只影响 go build -mod=vendor 行为，但不会改变 go test 或 go list 的模块解析逻辑；若测试中导入未 vendored 的间接依赖，仍可能触发网络请求
• go mod vendor 不复制 replace 指向的本地路径内容，那些路径必须在构建机上同步存在
• Docker 构建中，COPY go.mod go.sum . 后应立即执行 go mod download（联网阶段），再 COPY . . 和 go build（离线阶段）；否则多阶段镜像里缓存会丢失

真正可靠的离线交付单元，不是单个二进制，而是包含完整 pkg/mod/cache/download 子树的模块缓存快照——这点常被忽略。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Go模块离线构建方法解析》文章吧，也可关注golang学习网公众号了解相关技术文章。