模块下载失败应先检查 GOPROXY 和 GOSUMDB 配置，国内常见错误为 GOPROXY 设为不可达的 proxy.golang.org 或 GOSUMDB 未关闭导致校验失败；可临时设为 go env -w GOPROXY=https://goproxy.cn,direct 和 go env -w GOSUMDB=off。
模块下载失败时先看 go env 的 GOPROXY 和 GOSUMDB
绝大多数模块下载失败不是网络连不通，而是代理或校验机制主动拦截。运行 go env GOPROXY GOSUMDB，确认值是否为预期配置。国内常见错误是 GOPROXY 被设成 https://proxy.golang.org（无法直连），或 GOSUMDB 未关闭导致校验失败。
临时修复可直接设置：
go env -w GOPROXY=https://goproxy.cn,direct go env -w GOSUMDB=off
注意：GOSUMDB=off 仅用于调试，生产环境建议保留校验，改用可信的 sumdb（如 sum.golang.org）并配好代理。
执行 go get 时加 -v -x 查看真实请求路径和失败点
-v 输出详细日志，-x 显示每条 shell 命令（包括 git clone、curl 请求等），能快速定位卡在 DNS、TLS 握手、重定向还是 403/404。
立即学习“go语言免费学习笔记（深入）”；
例如：
go get -v -x github.com/gin-gonic/gin@v1.9.1
重点关注输出中类似这样的行：
-
GET https://goproxy.cn/github.com/gin-gonic/gin/@v/v1.9.1.info—— 若返回 404，说明版本不存在或 proxy 缓存未命中 -
git -c core.autocrlf=false clone --mirror --no-hardlinks ...—— 若卡住，大概率是git协议被墙或 SSH key 未配置 -
Fetching https://goproxy.cn/github.com/gin-gonic/gin/@v/list—— 若超时，说明 proxy 不可达，需检查网络或换源
私有模块或 Git 仓库地址不走 GOPROXY 时的 fallback 处理
当模块路径匹配 replace、exclude 或属于非公开域名（如 gitlab.example.com/mylib），Go 默认跳过 proxy，直接走 git 或 https 协议拉取。此时失败往往与认证或协议有关。
常见应对方式：
- 确保
git config --global url."https://token:x-oauth-basic@github.com/".insteadOf "https://github.com/"类似配置已生效（尤其 GitHub 私有 repo） - 对 GitLab/Gitee 等，用
git config --global url."https://user:token@gitlab.example.com/".insteadOf "https://gitlab.example.com/" - 若必须用 SSH，确认
~/.ssh/config中 Host 别名与模块路径中的 host 一致，且ssh -T git@gitlab.example.com可通 - 在
go.mod中显式replace到本地路径或已 clone 好的目录，绕过网络拉取：replace github.com/private/lib => ./vendor/github.com/private/lib
CI/CD 环境下模块缓存失效或并发冲突
GitHub Actions、GitLab CI 等默认不复用 $GOPATH/pkg/mod，每次都是干净环境，容易触发重复下载和限流。同时，并发 go mod download 可能因写锁冲突报错 cannot lock... because of permission denied。
推荐做法：
- 在 CI 配置中启用模块缓存（如 GitHub Actions 的
actions/cache缓存~/go/pkg/mod） - 避免在脚本中多次执行
go mod download；统一在构建前跑一次即可 - 若使用
go build -mod=readonly，确保go.sum已提交且完整，否则会因校验失败中断 - 镜像内构建时，提前
go mod download并打包进基础镜像，减少运行时依赖拉取
模块下载不是单纯“重试就行”的问题，关键在分清是代理策略、认证缺失、协议限制，还是环境隔离导致的缓存缺失——每个环节的日志和配置都得对应着查。
