go mod download在私有仓库下卡住，是因为未设GOPRIVATE导致Go将其误判为公共模块而走代理，必须显式配置GOPRIVATE=git.internal.company.com/*并配合SSH密钥或HTTPS凭据，否则direct模式不生效；replace本地路径的模块需手动准备且路径正确，离线构建还需GOPROXY=direct与GOSUMDB=off双关闭，并验证go build -v无Fetching日志。
go mod download 在私有仓库下为什么总卡住
因为默认 GO_PROXY=https://proxy.golang.org,direct，而 direct 模式要求直连私有 Git 地址（如 git.internal.company.com/lib），但离线环境或内网策略常阻断 SSH/HTTPS 访问，导致报错类似 git.internal.company.com: no such host 或 TLS handshake timeout。这不是配置写错了，是 Go 模块机制本身不自动 fallback 到本地路径或跳过认证。
- 必须提前设置
GO_PRIVATE=git.internal.company.com/*，否则go mod download会把私有域名当公共模块走代理，失败后也不尝试direct -
GO_PROXY=direct单独设没用——它只对未匹配GO_PRIVATE的域名生效；私有域名必须显式列入GO_PRIVATE才触发 direct 行为 - 若私有仓库用 SSH（
git@git.internal.company.com:org/repo.git），确保离线机已预置对应 SSH key 和~/.ssh/config，否则go mod download会静默失败（无错误提示，只卡住）
replace 后的本地路径依赖怎么下载
go mod download 完全忽略 replace 到本地路径（如 replace github.com/internal/pkg => ./pkg）的模块，因为它认为“无需下载”。但构建时若该路径不存在或内容不完整，go build 直接报错 cannot find module providing package。
- 手动
git clone私有仓库到./pkg目录，并确保其go.mod中模块名与 replace 前一致（例如module github.com/internal/pkg） - 运行
go mod edit -replace=github.com/internal/pkg=./pkg确保路径正确（注意：路径是相对于项目根目录，不是 GOPATH） - 执行
go list -m github.com/internal/pkg验证是否识别为本地替换——输出应含// indirect或直接显示路径，而非版本号
离线环境下如何验证依赖已真正就绪
光看 go mod download all 成功不等于能离线构建。Go 构建阶段仍可能触发额外网络请求，比如 cgo 调用系统 DNS、//go:embed 引用外部文件、或 build tag 分支引入未被 go list -m all 覆盖的模块。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 设
GOPROXY=direct+GOSUMDB=off后，运行go build -v -a ./...，观察输出里是否出现新Fetching日志——有则说明还有漏掉的依赖 - 检查
go.sum是否包含所有模块的校验和：运行go mod verify，报错即表示某些模块哈希缺失或不匹配 - 若项目含
cgo，且目标环境禁用 cgo（CGO_ENABLED=0），需确认 net 包行为——它会退回到纯 Go DNS 解析器，不读/etc/resolv.conf，可能导致 etcd/client-go 等库初始化失败
用 goproxy 起本地文件代理比 go mod vendor 更可靠
go mod vendor 把依赖复制进 vendor/，看似离线，但它不处理 replace 的本地路径、不包含 // indirect 依赖、且编译时仍需目标机具备 cgo 工具链——这对 ARM64 麒麟等异构私有云节点极不友好。
立即学习“go语言免费学习笔记（深入）”；
- 在有网机器上执行
go mod download -x，记下所有落盘路径（形如$GOPATH/pkg/mod/cache/download/github.com/xxx/@v/v1.2.3.zip） - 打包整个
$GOPATH/pkg/mod/cache/download/目录，拷贝到离线机/opt/go-proxy-cache - 离线机运行：
goproxy -proxy=file:///opt/go-proxy-cache -listen=localhost:8080，再设GOPROXY=http://localhost:8080 - 验证：
go list -m all应完整输出所有模块，无报错；go build不再触发任何网络请求
真正麻烦的是跨架构和私有证书——预拉取必须用与目标环境完全一致的 Go 版本（如 go1.21.6），且若私有 Git 用自签名证书，需提前把 CA 证书注入离线机系统信任库，否则 go mod download 会因 TLS 验证失败静默退出。
