根本原因是goproxy默认镜像不支持断点续传，大文件下载遇网络抖动即失败重试；应改用direct模式直连github等源仓库（需同步设gosumdb=off），或手动下载缓存、启用vendor离线构建。
为什么 go mod download 会卡在大文件上
根本原因不是 Go 模块机制本身，而是 go mod download 默认走的是 GOPROXY（如 https://proxy.golang.org），而某些模块（尤其是含二进制、文档、测试数据的）在 proxy 上被完整镜像，导致单个 .zip 包动辄几十 MB —— 但 proxy 不支持断点续传，网络抖动或超时就直接失败重试，反复卡住。
常见现象：go mod download -x 显示某模块 URL 正在 GET，但进度停滞数分钟，最终报 context deadline exceeded 或 unexpected EOF。
- 不是所有模块都大：只有含
/archive/或/@v/vX.Y.Z.zip的版本才可能触发（比如github.com/uber-go/zap某些带 benchmark 数据的 tag） - 本地
go.sum已存在校验和，但download阶段仍要拉 zip，不跳过 -
GO111MODULE=on下无法绕过模块下载，哪怕你只想要编译
用 go mod download -json 定位具体哪个模块在拖慢
直接跑 go mod download 看不到进度细节，但加 -json 能输出每条下载请求的状态和大小，方便揪出“罪魁祸首”：
go mod download -json | grep -E '(size|module|error)'
输出类似：
{"Path":"github.com/segmentio/kafka-go","Version":"v0.4.27","Error":"Get \"https://proxy.golang.org/github.com/segmentio/kafka-go/@v/v0.4.27.zip\": context deadline exceeded (Client.Timeout exceeded while awaiting headers)","Size":0}
注意看 "Size":0 和 "Error" 字段——这说明该请求根本没拿到响应头，大概率是 proxy 返回太慢或中断。这时候别急着换源，先确认这个模块是否真被项目依赖（go list -deps -f '{{.ImportPath}}' . | grep kafka），有时是间接依赖的废弃子模块。
- 如果模块确实不用，用
go mod graph找出谁引了它，再replace或exclude - 如果必须用，但 zip 太大，可手动下载后放本地缓存：
$GOPATH/pkg/mod/cache/download/对应路径下建github.com/segmentio/kafka-go/@v/v0.4.27.zip和.info文件（内容为 JSON 格式元信息）
临时禁用 proxy + 启用 direct 拉取更可控
proxy 是为加速，但对大文件反而成瓶颈。改用 direct 模式让 Go 直连原始仓库（如 GitHub），好处是支持 HTTP range 请求（断点续传），且多数 Git 服务商对 zip 下载做了 CDN 优化：
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
export GOPROXY=direct export GOSUMDB=off
⚠️ 注意：GOSUMDB=off 是必须的，否则 go mod download 会因无法校验 checksum 卡住（因为 direct 模式不走 sumdb）。
- 只建议在 CI 或本地调试时临时启用，生产构建仍推荐保留 proxy
- GitHub 限速（60 req/h 未认证），若频繁失败，可配个人 token：
export GOPROXY=https://token:x-oauth-basic@github.com（需加/goproxy后缀并用反向代理封装，不建议裸用） - 某些私有模块（如 GitLab）需确保
GOINSECURE设置对应域名，否则 TLS 验证失败
用 go mod vendor 避开重复拉取
如果你的构建流程允许 vendor，这是最稳的解法：一次拉全、后续离线可用，彻底规避网络问题。
执行前确保 go.mod 干净（无未提交修改），然后：
go mod vendor -v
会把所有依赖（含间接依赖）解压到 vendor/ 目录，并生成 vendor/modules.txt 记录来源。之后编译时加 -mod=vendor：
go build -mod=vendor -o app ./cmd/app
-
vendor不影响go run，除非显式加-mod=vendor - CI 中建议
git add vendor/并提交，避免每次构建都重新下载 - 注意：vendor 后
go mod tidy仍会联网检查，如需完全离线，得配合GOFLAGS="-mod=vendor"
真正麻烦的不是大文件本身，而是它暴露了 proxy 配置和网络环境之间的隐性耦合——你得先判断是模块真需要，还是只是历史残留；再决定是换通道、切模式，还是干脆本地固化。选哪条路，取决于你控制构建环境的能力，而不是 Go 工具链能做什么。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
