go mod download在局域网内失败的典型表现是命令卡住、超时或报“dial tcp: i/o timeout”，根源在于Go默认直连proxy.golang.org和sum.golang.org，而局域网通常禁止出网或DNS不通；需同时设GOPROXY=off和GOSUMDB=off，或配置内网代理，并确保离线缓存完整且路径一致。
go mod download 在局域网内失败的典型表现
直接执行 go mod download 卡住、超时，或报错类似 Get "https://proxy.golang.org/...": dial tcp: i/o timeout —— 这不是模块本身有问题，而是 Go 默认尝试直连公网代理和校验服务器，而局域网通常不允许出网或 DNS 不通。
常见错误现象：
- 命令无输出、长时间等待后失败
-
go list -m all能列出模块，但go mod download仍失败 - 即使配置了
GOPROXY，仍提示verifying github.com/xxx@v1.2.3: checksum mismatch
离线缓存必须提前在有网环境完成
Go 的模块缓存机制不支持“边下载边离线”，go mod download 本质是联网拉取并写入 $GOMODCACHE（默认为 $GOPATH/pkg/mod），离线机器上它只是个只读仓库。所以关键动作必须在能联网的机器上做完：
- 确保项目
go.mod已完整（go mod tidy运行成功） - 执行
go mod download，再用go list -m -f '{{.Dir}}' all | head -n 5随机检查几个模块目录是否存在 - 打包整个
$GOMODCACHE目录（不是$GOPATH/pkg/mod的软链接，而是真实路径）：用go env GOMODCACHE确认实际位置 - 解压到离线机相同路径，且
go env GOPATH必须一致，否则 Go 找不到缓存
GOPROXY=off 和 GOSUMDB=off 缺一不可
只设 GOPROXY=off 不够，因为 Go 仍会尝试连接 sum.golang.org 校验 go.sum —— 局域网里这一步照样失败。两个开关必须同时关闭：
立即学习“go语言免费学习笔记（深入）”；
- 执行
go env -w GOPROXY=off和go env -w GOSUMDB=off - 验证是否生效：
go env GOPROXY GOSUMDB应输出off off - 注意安全风险：关闭校验后，依赖完整性完全依赖你本地缓存的可信度；若缓存来自不可信源，慎用
- 如果局域网内有自建代理（如 Nexus、goproxy.cn 私有镜像），可设
GOPROXY=http://intranet-proxy:8080，此时GOSUMDB可保留为sum.golang.org+http://intranet-proxy:8080/sumdb
离线构建失败时最该检查的三件事
运行 go build 报 cannot find module providing package xxx，别急着重装 Go，先看：
-
go env GOMODCACHE输出路径下，对应模块的版本目录是否存在（例如github.com/sirupsen/logrus@v1.9.0） - 离线机
go version是否与下载依赖的机器一致？不同 Go 版本可能生成不兼容的缓存结构 - 项目中是否用了
replace指向本地路径？这种替换不会被缓存，离线时需手动复制对应代码到vendor/或调整为相对路径引用
离线缓存真正生效的前提，是缓存目录里每个模块都完整、路径准确、且 Go 环境拒绝任何网络试探——少设一个 off，或少拷一个子目录，都会让构建卡在第一步。
