go mod本身不提供私有git源网络重试，依赖底层git命令且无内置重试逻辑；需通过wrapper脚本对clone/fetch/ls-remote等命令实现指数退避重试，并过滤临时性网络错误，跳过永久性认证或路径错误。
go mod 本身不提供对私有 Git 源的网络重试控制 —— 它依赖底层 git 命令拉取模块，而 git 默认无重试逻辑。一旦遇到短暂网络抖动、SSH 连接中断或 HTTPS 证书握手失败，go mod download 就会直接报错退出，无法自动恢复。
git 命令级重试必须手动注入
go mod 调用私有源时（如 git@gitlab.example.com/internal/pkg 或 @#@#@#@#@#@#@#@#@#@0），实际执行的是类似 git -c core.autocrlf=false clone --mirror @#@#@#@#@#@#@#@#@#@0 /tmp/xxx 的命令。Go 不干预这个过程，也不暴露重试钩子。
- 不能通过
GO111MODULE、GOPROXY或go env配置项启用重试 -
git本身没有内置重试参数（如--retry=3），需靠 wrapper 脚本或环境变量间接控制 - 常见错误是误以为设置
GOPROXY=@#@#@#@#@#@#@#@#@#@2就能“让 go mod 自动重试私有源”——它只影响 proxy 路径，direct分支仍走裸git
可行做法是：
- 把
git替换为带重试逻辑的 shell wrapper（Linux/macOS）或 batch 包装器（Windows） - 在 wrapper 中对
clone、fetch、ls-remote等关键子命令做指数退避 + 错误过滤 - 只对临时性错误重试：
Connection refused、Operation timed out、Failed to connect to、SSL connect error；跳过Permission denied (publickey)、Repository not found等永久错误
示例 wrapper（保存为 /usr/local/bin/git 并确保在 $PATH 前置）：
#!/bin/sh
cmd="$1"
shift
<h1>只对可能因网络瞬断失败的操作加重试</h1><p>if [ "$cmd" = "clone" ] || [ "$cmd" = "fetch" ] || [ "$cmd" = "ls-remote" ]; then
for i in $(seq 0 4); do
if git.orig "$cmd" "$@"; then
exit 0
elif git.orig "$cmd" "$@" 2>&1 | grep -q -E "(Connection refused|timed out|Failed to connect|SSL connect error)"; then
sleep $(awk "BEGIN {print int(100 * (2 ^ $i))}") # ms 级指数退避
continue
else
exit 1
fi
done
exit 1
else
exec git.orig "$cmd" "$@"
fi</p>
注意：需先将原 git 二进制重命名为 git.orig。
GO_PROXY 链路中自建 proxy 的重试由 proxy 自身实现
如果你用 athens、goproxy.cn 或自研 Go module proxy（如基于 gin + git 后端），那么重试逻辑应落在 proxy 内部，而非 go mod 客户端。
-
go mod对 proxy 的请求是标准 HTTP GET，可被任意中间件拦截并重试 - 关键点：proxy 在向后端 Git 源发起
git clone或git archive时，必须自己封装重试（同上 wrapper 原理） - 切勿让 proxy 把原始
git错误透传给客户端 —— 应捕获并转换为 502/504，再由客户端按 HTTP 重试策略处理（但注意：go mod不遵循 HTTP 重试语义）
常见坑：
- proxy 设置了
http.Transport.MaxIdleConnsPerHost = 0却没配RetryableHTTPClient，导致上游 Git 源超时后直接返回 500，go mod收到即终止 - proxy 缓存了失败响应（如 404 Not Found），后续相同请求直接返回缓存，掩盖了源已恢复的事实
SSH 场景下 git 重试需额外处理连接复用与密钥代理
私有 Git 源若走 SSH（git@gitlab.internal:team/lib.git），重试失败常卡在 ssh 层，比如：
-
ssh: connect to host gitlab.internal port 22: Connection refused -
Write failed: Broken pipe -
Permission denied (publickey)（此为永久错误，不应重试）
此时仅靠 wrapper 脚本不够，还需：
- 配置
~/.ssh/config启用连接复用：ControlMaster auto、ControlPersist 2m，减少反复建连开销 - 设置
ServerAliveInterval 30和ServerAliveCountMax 3，主动探测并清理僵死连接 - 确保
ssh-agent已启动且密钥已添加，避免每次重试都触发交互式密码提示
git 本身不会重试 SSH 认证失败，所以 Permission denied 类错误必须在 wrapper 中识别并立即退出，否则会陷入无效循环。
真正容易被忽略的是：go mod 在解析 go.sum 或校验 checksum 时，根本不会触发任何 Git 操作，但会静默失败。例如你改了私有模块的 tag，却忘了更新 go.sum 中对应哈希，go mod download 会报 checksum mismatch 并退出 —— 这不是网络问题，重试毫无意义。务必把 checksum 校验失败和网络失败区分开，前者要人工介入，后者才值得自动化恢复。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
