Golang 模块代理失效解决方法

Go模块代理失效常见于国内网络，可通过更换GOPROXY代理（如goproxy.cn）、启用GO111MODULE、使用replace替换源、检查网络防火墙及校验和配置解决。

Go 模块代理失效或模块下载失败是开发者在使用 Go 时常见的问题，尤其是在国内网络环境下。即使配置了代理，也可能因为代理地址过期、网络策略调整或模块源不稳定导致拉取失败。下面介绍几种有效的解决方法。

检查并更换模块代理

Go 模块依赖代理（如 goproxy.io 或 goproxy.cn）来加速模块下载。若当前代理失效，应先确认并切换为可用的代理。

• go env -w GOPROXY=https://goproxy.cn,direct（推荐国内用户使用）
• go env -w GOPROXY=https://proxy.golang.org,direct（海外用户）

多个代理可用逗号分隔，direct 表示当代理无法响应时直接连接源仓库。

启用模块支持与校验和验证

确保 GO111MODULE 已开启，并且校验和数据库未阻止合法模块。

• go env -w GO111MODULE=on
• 若遇到 checksum 不匹配问题，可临时设置：go env -w GOSUMDB=off（仅用于调试，不建议长期关闭）

也可指定使用公共校验和数据库：go env -w GOSUMDB=sum.golang.org，必要时通过代理访问。

手动替换模块源或使用私有仓库配置

对于特定模块拉取失败的情况，可在 go.mod 中使用 replace 指令替换源地址。

replace (
    github.com/some/package => github.com/mirror/package v1.0.0
)

适用于公司内部模块或被墙的开源库。私有仓库还需配置 SSH 或环境变量认证。

排查网络与防火墙限制

某些企业网络或系统防火墙可能拦截 HTTPS 请求或 Git 协议。

• 尝试使用 curl https://goproxy.cn 测试代理连通性
• 若使用 Git 拉取私有模块，确保 SSH 配置正确，或改用 HTTPS 并配置凭证
• 临时关闭代理工具或切换网络环境测试是否恢复

基本上就这些常见原因和应对方式。模块代理失效多数可通过切换 GOPROXY 解决，配合 replace 和网络调试，基本能覆盖大多数下载失败场景。不复杂但容易忽略细节。