上游仓库临时不可访问时，Go模块不会自动降级或跳过，必须主动干预：先用go mod download -v定位卡点，再通过GOPROXY=direct验证是否上游问题；若确认中断，则用replace强制切换至镜像或本地路径，并配合GOPRIVATE和GONOSUMDB精准控制私有库路由与校验。
上游仓库临时不可访问时，Go 模块不会自动降级或跳过，而是卡住或报错——必须主动干预，不能等。
go mod download 卡在 timeout 或 404？先确认是不是 upstream 问题
Go 默认行为是死等远程仓库响应，哪怕只是 GitHub、GitLab 或私有 Git 服务短暂抖动，go mod tidy 或 go build 就会卡在某个 git clone 步骤，不超时、不重试、不提示具体哪条依赖挂了。
- 用
go mod download -v观察最后一行输出：如果停在git -c core.autocrlf=false clone https://...，基本就是 Git 协议层失败，不是 Go 模块系统问题 - 临时换
GOPROXY=direct运行一次：GOPROXY=direct go mod download -v。如果立刻失败（比如报repository not found），说明确实是上游仓库不可达；如果仍卡住，问题可能出在 SSH 配置或凭证上 - 别只测
curl https://github.com/xxx/yyy—— Go 走的是 Git 协议或 HTTPS + Git credential helper，得用git ls-remote https://github.com/xxx/yyy.git HEAD模拟真实行为
replace 是唯一能绕过上游中断的可靠手段
当某个依赖（比如 golang.org/x/net）因官网维护或 DNS 污染无法拉取时，replace 可强制改用镜像或本地缓存副本，且不依赖 GOPROXY 设置。
-
replace必须写在go.mod文件末尾、require块之后，格式为：replace golang.org/x/net => github.com/golang/net v0.25.0 - 推荐优先用官方镜像地址（如
github.com/golang/net）而非第三方 fork，避免 patch 差异引入隐性 bug - 若连镜像也失效，可临时
git clone到本地，再用相对路径替换：replace golang.org/x/net => ../vendor/golang-net，但要确保该目录下有合法go.mod - 执行
go mod tidy后，go.sum会记录新路径的校验和——这没问题，只要开发阶段能编译通过即可
GOPRIVATE 和 GONOSUMDB 要配合用，尤其对私有 Git 服务
上游中断常发生在企业内网 GitLab 或自建 Gitea 上，这时单纯设 GOPROXY 没用，因为 Go 会把请求发给代理，而代理根本不知道怎么连你内网地址。
-
GOPRIVATE必须精确覆盖域名，支持通配符但**不支持路径段匹配**：go env -w GOPRIVATE="git.internal.company,*.internal.company"，而不是git.internal.company/myproject - 若内网 Git 无 HTTPS 或证书不可信，必须同时设
GONOSUMDB：go env -w GONOSUMDB="git.internal.company,*.internal.company"，否则go mod download会在校验阶段失败 - SSH 方式更稳：确保
~/.ssh/config中 Host 别名与go.mod里 import path 的 host 部分一致，例如git@mygit:org/repo对应Host mygit配置
CI 构建失败时，别盲目清缓存
很多团队遇到 CI 编译失败第一反应是 rm -rf $GOCACHE 或 go clean -modcache，但这解决不了上游中断问题——缓存里本来就没有那个模块。
- CI 环境应预装常用镜像依赖（如
golang.org/x/...的 GitHub 镜像版），通过go mod download提前拉到构建机本地，再设GOPROXY=file:///path/to/local/mirror - CI 脚本里加检查：
git ls-remote --quiet https://github.com/golang/net.git HEAD || echo "golang/net mirror unreachable"，早于go build报错 - 真正要清理的只有
go.sum中已失效的 checksum 行——手动删掉对应行后运行go mod tidy重建，比清整个 modcache 快得多
上游仓库中断不可预测，但 Go 模块的应对逻辑其实很明确：不靠运气等恢复，而是用 replace 锁路径、用 GOPRIVATE 控制路由、用 go mod download -v 定位卡点。最容易被忽略的是——replace 生效的前提是目标路径本身能被 go list 识别为合法模块，也就是它必须带 go.mod 文件，哪怕只是空的。
