go build 本身不偷偷连网，真正触发隐式下载的是第三方工具（如swag、mockgen）在运行时调用go list -m all或go mod download，若未设-mod=readonly或GOPROXY=off，便会直连proxy.golang.org导致超时失败。
go build 为什么偷偷连网？第三方工具触发的隐式下载
离线构建失败常不是因为 go build 自己去拉包，而是你项目里用的第三方工具（比如 swag、mockgen、stringer、protoc-gen-go）在运行时自动调用 go list -m all 或 go mod download。这些工具没加 -mod=readonly 或没设 GOPROXY=off，一执行就直连 proxy.golang.org，报错 “dial tcp: i/o timeout”。
典型现象：单独跑 go build 成功，但执行 swag init 或 make generate 就卡住或失败；CI 日志里看到工具进程输出 “Fetching modules…” 却没你手动执行过 go mod download。
- 所有这类工具必须在离线机上提前安装好二进制（别用
go install动态拉），且版本与联网机一致 - 运行前统一设置环境变量：
go env -w GOPROXY=off GOSUMDB=off，否则工具内部的go命令仍会尝试校验 - 若工具依赖特定模块（如
swag需要github.com/swaggo/swag的@latest），得在联网机用对应版本运行一次该工具，让其触发的模块也进缓存 - 检查工具源码或文档，确认它是否支持
-mod=readonly参数（部分新版swag支持swag init -mod=readonly）
replace 私有模块后，go build 仍解析失败
replace 写在 go.mod 里，只影响当前 module 的构建上下文；但第三方工具（尤其是基于 go/packages 的）往往启动独立的 go list 进程，不继承你的 replace 规则，导致它仍试图解析原始 URL（如 gitlab.internal/foo/bar），而离线机 DNS 不通或 Git 服务不可达。
常见错误信息：go list -m: gitlab.internal/foo/bar@v0.1.0: unexpected status code 404 或 exec: "git": executable file not found（工具想 clone，但没装 Git 或网络不通）。
立即学习“go语言免费学习笔记（深入）”；
- 不要只靠
replace，对私有模块，必须同时用go mod edit -replace=gitlab.internal/foo/bar=./internal/foo/bar指向本地路径，并确保该路径真实存在且含完整go.mod - 把私有模块目录一起打包进项目（如
./internal/foo/bar），而非仅靠replace指向远程地址 - 若工具强制走
go list，可在其调用前临时设GOPRIVATE=gitlab.internal，避免代理转发 - 验证：在离线机运行
go list -m gitlab.internal/foo/bar，应直接返回本地路径，而不是报错或超时
vendor 目录存在，但 go build -mod=vendor 仍失败
go build -mod=vendor 不是“有 vendor 就能用”，它会严格比对三者一致性：go.mod、vendor/modules.txt、vendor/ 目录结构。任何一项不匹配，就会 fallback 到 module mode 并尝试联网。
最容易被忽略的是：vendor/modules.txt 里漏了间接依赖，或 go.mod 里多了 // indirect 条目但 vendor 没包含对应包——这时 go build 会静默跳过 vendor，转而查 $GOMODCACHE，而离线机那里是空的。
- 生成 vendor 前，先跑
go mod tidy -v，确认无require报错，且所有// indirect都已 resolve - 执行
go mod vendor -v，观察输出里有没有 “skipping … (not in vendor)” —— 这类包必须手动补进go.mod或确认测试依赖是否被误引入 - 检查
vendor/modules.txt行数是否等于go list -m all | wc -l，少一行就说明漏包 - 离线机上执行
go build -mod=vendor -x，看实际构建过程是否真从vendor/读取，还是又去pkg/mod查了
交叉编译 + cgo 场景下的离线陷阱
启用 CGO_ENABLED=1 时，Go 不仅要找 Go 包，还要找系统头文件和静态库（如 libpcap、openssl）。这些不在 vendor 或 mod cache 里，离线机若没装对应 dev 包（如 libpcap-dev、openssl-devel），go build 会直接报错 “cannot find -lpcap” 或 “fatal error: pcap.h: No such file or directory”。
这不是 Go 模块问题，是底层绑定缺失。即使 vendor 完整、代理关闭，也会跪在这一步。
- 离线机必须预装目标平台的 C 工具链和系统库开发包（
gcc、pkg-config、*-dev或*-devel） - 若用 Docker 构建，基础镜像得是
golang:1.21.6-slim这类带 build deps 的，不能用alpine除非手动apk add - 交叉编译到 ARM 或国产 OS（如麒麟）时，
go env -w CC_arm64=/path/to/arm64-gcc必须指向离线机已有的交叉工具链，不能指望go自动下载 - 验证方式：在离线机跑
pkg-config --exists libpcap && pkg-config --cflags libpcap，成功才代表 cgo 环境就绪
关键点始终落在：离线不是“关掉网络就行”，而是要把所有可能触发网络请求的环节——包括工具链、私有路径解析、cgo 头文件、校验服务器——全部在联网阶段预置并验证完毕。 一旦漏掉任意一个隐式依赖点，构建就会在你看不见的地方悄悄失败。
