国内Go开发者必须配置Go Modules代理，因proxy.golang.org直连不稳定且golang.org/x/等模块无法访问，易导致校验失败、超时或包缺失；推荐使用https://goproxy.cn并配置go env -w GOPROXY=https://goproxy.cn,direct。
Go Modules 代理不是可选配置，而是国内 Go 开发者必须设置的基础设施——不配就大概率 go mod download 卡死或超时。
为什么国内必须用代理？
Go 官方模块仓库（proxy.golang.org）在国内直连极不稳定，且部分模块（如 golang.org/x/...）因域名解析和网络策略问题根本无法访问。不走代理时常见现象包括：
-
go mod tidy卡在verifying github.com/xxx@v1.2.3: checksum mismatch或直接 timeout -
go get报错failed to fetch或no matching versions for query "latest" - 依赖中含
golang.org/x/net等时，提示module golang.org/x/net@latest found (v0.28.0), but does not contain package golang.org/x/net/http2（实际是拉取失败导致元数据错误）
推荐代理地址与一键配置命令
目前最稳定、更新及时的公开代理是 https://goproxy.cn（由七牛云维护），其次可备选 https://goproxy.io 或 https://proxy.golang.org（仅限海外 IP）。配置方式如下：
- 全局启用（推荐）：
go env -w GOPROXY=https://goproxy.cn,direct
- 若需兼容私有模块（如公司内网
git.mycompany.com），必须加,direct后缀，否则所有非代理源请求都会被拒绝 - 禁用代理（调试用）：
go env -w GOPROXY=off
，但此时需确保所有依赖都可通过go.sum本地验证，且无golang.org/x类模块
GOINSECURE 和 GOPRIVATE 配合私有模块
当项目引用公司 GitLab 或 GitHub 私有仓库（如 git.mycompany.com/internal/utils）时，仅设 GOPROXY 不够，还需绕过 TLS 校验和代理转发：
立即学习“go语言免费学习笔记（深入）”；
- 让 Go 跳过指定域名的 HTTPS 证书检查：
go env -w GOINSECURE="git.mycompany.com"
- 让 Go 不将这些模块发往代理（避免泄露或 404）：
go env -w GOPRIVATE="git.mycompany.com/*"
-
GOPRIVATE支持通配符，多个域名用逗号分隔，例如：git.mycompany.com/*,github.com/my-org/private-repo - 注意：如果
GOPRIVATE域名未同时加入GOINSECURE，而该域名又用的是自签名证书，go get仍会报x509: certificate signed by unknown authority
验证代理是否生效 & 常见失效原因
运行 go env GOPROXY 应输出 https://goproxy.cn,direct；进一步验证可执行：
go mod download github.com/gin-gonic/gin@v1.12.0
若成功下载并在 $GOPATH/pkg/mod/cache/download/ 下生成对应目录，说明代理工作正常。容易忽略的问题包括：
- 终端启动新 shell 后未加载最新
go env（尤其在 zsh/fish 中，需确认~/.zshrc是否 source 了 go 的环境变量） - CI/CD 环境（如 GitHub Actions）未显式设置
GOPROXY，导致构建失败 - IDE（如 Goland）使用独立的 shell 环境，需在 IDE 设置里手动配置
GOPROXY，不能只依赖终端配置 - 某些老版本 Go（GOPROXY，必须升级到 Go 1.16+ 才能稳定使用
directfallback 机制
代理配置本身很简单，但它的生效边界（shell、IDE、CI）、与私有仓库的配合逻辑、以及 fallback 到 direct 的触发条件，才是实际项目中最常出问题的地方。
