Go模块下载失败多由网络、代理、路径错误或认证问题导致，需依次检查：①配置国内镜像如goproxy.cn；②验证模块路径与版本是否存在；③设置GOPRIVATE并配置Git凭证处理私有模块；④清除modcache缓存并重试，结合环境变量调试定位具体阶段错误。
Go模块下载失败是开发过程中常见的问题，尤其在依赖外部包或使用私有仓库时。这类问题通常与网络、代理配置、模块路径错误或版本控制有关。以下是实际项目中总结的排查思路和解决方案。
检查网络与镜像配置
国内开发者常因网络原因无法访问proxy.golang.org或goproxy.io等默认代理。应优先确认是否设置了合适的模块代理：
- 执行go env -w GOPROXY=https://goproxy.cn,direct切换为国内镜像
- 多个代理可用逗号分隔，direct表示后续地址直连
- 通过go env GOPROXY验证当前设置
若企业内网限制外网访问，需联系管理员开通对GOPROXY域名的出口权限。
验证模块路径与版本是否存在
拼写错误或引用了不存在的版本会导致下载失败：
立即学习“go语言免费学习笔记（深入）”；
- 手动访问模块URL（如https://goproxy.cn/github.com/user/repo/@v/v1.2.3.info）确认版本存在
- 使用go list -m -versions github.com/user/repo查看可用版本
- 检查go.mod中require语句的模块名是否正确
常见错误包括大小写不符、组织名拼错、使用了未发布的语义化版本标签。
处理私有模块认证
拉取私有仓库（如GitHub Enterprise、GitLab私有项目）需要身份验证：
- 设置环境变量GOPRIVATE=git.company.com,github.com/org/private-repo
- 配置Git凭证：使用SSH密钥或个人访问令牌（PAT）
- 确保~/.gitconfig中包含正确的替换规则，例如：
[url "git@github.com:org/"]
insteadOf = https://github.com/org/
对于GitHub，推荐生成PAT并配合gh auth login完成登录。
清除缓存并重试
模块缓存损坏可能导致重复失败：
- 运行go clean -modcache清除所有模块缓存
- 删除$GOPATH/pkg/mod目录手动清理
- 重新执行go mod tidy触发下载
结合GO111MODULE=on GODEBUG=gomodules=1可输出详细模块解析日志，帮助定位问题源头。
基本上就这些。多数下载问题都能通过调整代理、校验路径、配置认证和清理缓存解决。关键是要根据错误信息判断阶段——是解析、连接还是认证失败，再针对性处理。
