先确认goproxy是否真生效，因ide终端常不加载shell配置；若仍卡住，大概率是gosumdb尝试连接sum.golang.org失败，需同时设go env -w gosumdb=off验证。
go mod download 报 dial tcp 连接失败，先看 GOPROXY 是否真生效
很多报错表面是“模块找不到”或“超时”，实际是 GOPROXY 没真正起作用。IDE（比如 VS Code 或 GoLand）启动时往往不加载 shell 的 ~/.zshrc 或 ~/.bashrc，导致你在终端里用 go env -w GOPROXY=... 设置的值，对 IDE 内置终端和调试器无效。
验证方法很简单：在 VS Code 的集成终端里直接运行：
go env GOPROXY
如果输出不是你设的地址（比如还是 https://proxy.golang.org,direct），说明配置没进到这个环境。这时候别改 IDE 设置，直接在 VS Code 终端里临时设一次：
go env -w GOPROXY=https://goproxy.cn,direct
再试 go mod download。常见坑点：
-
GOPROXY值里混入了中文逗号、空格或换行——必须是https://goproxy.cn,direct（英文逗号，无空格） - 项目目录下存在
go.work文件，且其中定义了不同代理逻辑，会覆盖全局设置 - 某些 CI 脚本或 Makefile 里硬编码了
GOPROXY，优先级高于go env -w
设置了 goproxy.cn 还是卡住，大概率是 GOSUMDB 在阻塞
GOPROXY 只管下载，GOSUMDB 负责校验。国内镜像站（包括 goproxy.cn）不提供校验服务，Go 默认仍会尝试连 sum.golang.org，结果就是卡在 TLS 握手或直接 timeout。
临时验证是否是它的问题，执行：
go env -w GOSUMDB=off
再跑一次 go mod download。如果立刻成功，就坐实了问题。生产环境不建议长期关校验，但开发阶段可先这么用。更稳妥的做法是：
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
- 用清华源替代：
go env -w GOPROXY=https://mirrors.tuna.tsinghua.edu.cn/goproxy/,direct（它对带时间戳的v0.0.0-xxx版本兼容更好） - 配合
GONOSUMDB排除私有域名：比如你的模块在git.example.com，就加go env -w GONOSUMDB=git.example.com - 若必须保留校验，可设
GOSUMDB=sum.golang.org+local，让 Go fallback 到本地go.sum文件
go get 成功但 go build 报 checksum mismatch
这不是 GOPROXY 的锅，是 go.sum 文件和远程校验和对不上。典型场景：你之前关过 GOSUMDB，后来又开了；或者换了代理源，但旧的 go.sum 里记录的是另一套哈希。
最干净的解法不是删 go.sum，而是让 Go 重新生成：
go clean -modcache
然后强制刷新依赖并重写校验文件：
go mod download && go mod verify
注意两点：
- 别手动编辑
go.sum——它由 Go 工具链自动生成，手改会导致后续go mod tidy失败 - 如果项目里用了
replace指向本地路径，go mod verify会跳过那些模块，但go build仍可能因版本不一致报错 -
go mod vendor后再 build，能绕过网络校验，适合离线构建
私有 Git 仓库拉取失败，direct 不等于万能兜底
GOPROXY 末尾的 direct 只对公开仓库有效。如果你的 go.mod 里写了 github.com/myorg/private-lib，而这个仓库需要登录或走公司内网，direct 会直接失败，错误常是 git ls-remote 超时或 401，不会提示“请登录”。
解决方式分两步：
- 先配 Git 本身：
git config --global url."https://token@github.com/".insteadOf "https://github.com/"（把 token 填进去） - 再告诉 Go 别走代理：
go env -w GONOPROXY=github.com/myorg（支持通配符，如myorg.*） - 如果私有库用 SSH，确保
~/.ssh/config正确，且GIT_SSH_COMMAND没被覆盖
最容易被忽略的是：GONOPROXY 和 GOPROXY 是独立开关，设了 GONOPROXY 后，GOPROXY 的值对匹配域名完全失效——哪怕你写的是 https://goproxy.cn,direct，Go 也不会尝试第一个地址。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
