根本原因是国内直连proxy.golang.org被拦截或返回403，必须配置代理；立即执行go env -w GOPROXY=https://goproxy.cn,direct并确认生效，避免临时export或未重启终端导致配置不生效。
go mod tidy 卡住或超时
根本原因是国内直连 proxy.golang.org 几乎必失败，不是网络慢，而是被拦截或返回 403。不配代理时，go mod tidy 会反复重试、卡在某个包上，甚至假死。
- 立刻执行：
go env -w GOPROXY=https://goproxy.cn,direct（goproxy.cn当前更稳，比goproxy.io故障率低） - 如果公司内网有私有代理，可设为：
go env -w GOPROXY=http://your-proxy:8080,direct - 确认生效：
go env GOPROXY输出应含goproxy.cn，不含空格或多余引号 - 避免用
export GOPROXY=...临时设置——它只对当前 shell 有效，IDE 或后台任务不继承
go clean -modcache 后依赖仍错乱
go clean -modcache 只清缓存，不重置本地模块状态。若 go.mod 已损坏或版本冲突，清完还是报错。
- 先删掉
go.mod和go.sum（确保你没改过它们，或已 commit） - 再运行：
go mod init your-module-name（模块名必须小写、无空格、符合域名格式，如github.com/you/project） - 然后：
go mod tidy—— 它会重新拉取所有依赖并生成新go.sum - 注意：不要用目录名直接当模块名，比如
go mod init my-app，首字母大写或含下划线都会触发malformed module path
项目在 $GOPATH/src 下导致 go mod 不生效
Go 会自动降级到旧的 GOPATH 模式，无视 go.mod，go run 报 package main is not in GOROOT 就是典型症状。
- 检查当前路径是否在
$GOPATH/src内：echo $GOPATH（macOS/Linux）或echo %GOPATH%（Windows），再看 pwd 输出 - 把项目移到任意其他位置，比如
~/projects/myapp或C:\work\myapp - 确认
GO111MODULE=on：go env GO111MODULE必须输出on；若为auto或off，执行go env -w GO111MODULE=on - 重启终端或 IDE，否则旧环境变量不生效
go mod download 速度仍慢或失败
即使配了 GOPROXY，某些包（尤其是带 git 子模块或私有 repo 的）仍可能 fallback 到 direct 模式，卡在 git clone。
立即学习“go语言免费学习笔记（深入）”；
- 加个备用代理兜底：
go env -w GOPROXY=https://goproxy.cn,https://goproxy.io,direct - 禁用 git 走 https（针对企业防火墙）：
git config --global url."https://".insteadOf git:// - 临时跳过校验（仅调试）：
go env -w GOSUMDB=off，但上线前务必关掉 - 观察日志：
go mod download -v显示具体卡在哪一步，比静默执行更容易定位
go.mod 的命名规则、GO111MODULE 的开关时机、代理 fallback 顺序，三者稍有错位就会反复失败。最常被跳过的其实是重启终端这一步，尤其在 macOS 上改了 ~/.zshrc 却忘了 source。 
