go mod download卡住90%是GOPROXY未生效:需设GOPROXY=https://goproxy.cn,direct(direct小写且末尾无空格),并确保GOPRIVATE、GONOSUMDB、GOINSECURE配合私有域名,同时清理GOMODCACHE和正确加载shell环境变量。

go mod download卡住,90%是GOPROXY没生效
不是网络差,也不是Go慢,而是go mod download默认连https://proxy.golang.org,国内多数情况下根本连不上。你看到的“卡在某个模块几秒不动”,其实是TLS握手超时后重试+指数退避,看起来像冻结。
- 必须设
GOPROXY=https://goproxy.cn,direct(注意逗号无空格,direct小写且必须在末尾) - 别只跑
go env -w GOPROXY=...就以为完事——新终端要继承环境变量,macOS/Linux得source ~/.zshrc,Windows得进「系统属性 → 环境变量」图形界面设永久值 - 验证是否真生效:运行
go mod download -x github.com/gin-gonic/gin@v1.9.1,看日志里出现的是GET https://goproxy.cn/...还是GET https://proxy.golang.org/...
私有模块拉不下来?GOPRIVATE和GONOSUMDB漏配了
公司内网Git地址(比如git.internal.company.com/mylib)一旦出现在go.mod里,GOPROXY会照常转发请求——结果要么404,要么把SSH密钥或HTTP Basic Auth暴露给公共代理。
- 加
GOPRIVATE=git.internal.company.com(支持通配符,如*.company.com),告诉Go跳过代理直连 - 私有模块没有官方checksum记录,必须配
GONOSUMDB=git.internal.company.com,否则go mod download直接报verifying ...: checksum mismatch - 如果私有库用HTTP而非HTTPS,还得加
GOINSECURE=git.internal.company.com(Go 1.13+默认禁用HTTP)
本地缓存没清理干净,反复下载同一包
GOMODCACHE(模块缓存)和GOCACHE(编译缓存)不清理,有时会导致版本解析错乱或重复拉取,尤其换代理或切分支后。
在 Go 中使用 google/wire 实现编译时依赖注入——wire.NewSet、wire.Build、wire.Bind(接口→实现)、wire.Struct、wire.Value、wire.Interface
- 执行
go clean -modcache清空模块缓存,再跑go mod download——这是最干净的重试方式 - 设
GOCACHE=$HOME/.cache/go-build复用编译中间产物,避免每次go build都重编标准库 - 别依赖IDE自动缓存:VS Code或GoLand可能读旧缓存,改完环境变量后重启IDE或手动触发
Go: Restart Language Server
Mac/Linux下环境变量写错位置,shell根本没加载
很多人把export GOPROXY=...写进~/.bash_profile,但macOS Catalina之后默认用zsh,~/.bash_profile压根不会被读。
立即学习“go语言免费学习笔记(深入)”;
- 查当前shell:
echo $SHELL,zsh就写~/.zshrc,bash才写~/.bash_profile - 写完务必
source ~/.zshrc(或对应文件),否则新开终端还是空值 - 临时测试用
GOPROXY=https://goproxy.io go list -m all,避免污染全局配置
direct有没有放在末尾、GOPRIVATE有没有覆盖所有私有域名、以及新终端是否真的读到了你写的那行export。

















