GitHub 直连慢/失败（clone 被重置、443 连不上、SSH 认证、Release 下载中断）

你会遇到什么

所有依赖 GitHub 的链路在国内直连都不稳：git clone 大仓库卡在 Cloning repository 后被重置；插件/技能 CLI 安装报 443 连不上；marketplace 克隆报 SSH 认证失败；从 Release 下 deb/AppImage 反复断连。

报错五花八门，但根因就三层：网络层（直连不稳）、配置层（git 重写规则/失效代理）、凭据层（SSH key / gh token 状态）。

先分层诊断，再动手，别对着报错瞎试。

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

关键认知：公开仓库匿名 HTTPS 即可访问，不需要任何凭据。凡是公开仓库报"权限错误"，先怀疑配置层和凭据层，不要怀疑网络。

三层模型对应三条独立链路：网络层是「TCP/TLS 到 github.com 与 objects.githubusercontent.com」的物理可达性，国内出口不稳定时连接在传输层被重置，跟命令无关；配置层是「寻址改写」——insteadOf 把 HTTPS 重写成 SSH、残留 http.proxy 把请求指向失效代理，作用在 git 访问任何远程之前；

凭据层是「认证状态」——SSH key、gh token、账号状态决定公开仓库之外的访问是否被接受。

三层是串联关系：先有可达性（网络），再按配置寻址（配置），最后凭据认证（凭据）——所以排查顺序固定，从下往上：先 curl 直连测网络、再查 insteadOf/proxy、最后验凭据。公开仓库报「权限错误」时，网络层已被排除（能连上才会走到认证），问题只可能在配置层或凭据层。

一步步来

1. 分层诊断 — 必做（30 秒，决定走哪条路）

curl -s -o /dev/null -w "%{http_code}\n" --max-time 10 https://github.com/

• 超时 / 000 → 网络层，走第 2 步；
• 200 / 301 → 网络通，继续：

GIT_CONFIG_GLOBAL=/dev/null git ls-remote https://github.com/octocat/Hello-World.git

• 能返回 refs → 配置/凭据层实锤，走第 4 步；
• 同样失败 → 网络层对 git 协议限速/断连，走第 2 步。

2. 网络层：换通道 — 按诊断结果（网络层命中才走）

三种通道按可用性排序（本市场 2026-08-28~30 实测）：

# a) gh-proxy 前缀（实测 13.5MB Release 资产秒级）
curl -L -o pkg.deb "https://gh-proxy.com/https://github.com/<owner>/<repo>/releases/download/<tag>/<asset>"

# b) codeload tarball（实测 544K / 2.1s 稳定）
curl -sL https://codeload.github.com/<owner>/<repo>/tar.gz/refs/tags/<tag> | tar xz

# c) 显式代理（有代理时）
git config --global http.https://github.com.proxy http://127.0.0.1:<端口>

tarball 下载断 → 改 git 浅克隆（git clone --depth 1）；clone 断 → 改 tarball。两者互换常能绕过坏链路。错峰（避开晚间高峰）与换网络（热点常能绕开）也有效。

SSH over 443（官方通道：SSH 层被墙的出路）

如果 22 端口不通但 SSH key 本身正常，GitHub 官方支持把 SSH 连接走 443 端口（HTTPS 端口，大多数防火墙放行 443 而拦 22）。

# ① 测 443 通道（主机名是 ssh.github.com，不是 github.com）
ssh -T -p 443 git@ssh.github.com
# 成功输出: Hi USERNAME! You've successfully authenticated, but GitHub does not provide shell access.

# ② 单次使用：直接按这个地址 clone
git clone ssh://git@ssh.github.com:443/<owner>/<repo>.git

# ③ 永久生效：写入 ~/.ssh/config
Host github.com
    Hostname ssh.github.com
    Port 443
    User git

首次连接会提示 The authenticity of host '[ssh.github.com]:443 ...' can't be established——这是 known_hosts 里还没有 ssh.github.com 的正常警告；指纹与 GitHub 官方公布的 ED25519 指纹一致即可选 yes。

注意两点：GitHub Enterprise Server 不支持此通道；显式代理可能干扰 443 通道（有代理时优先用 gh-proxy 方案）。

3. 网络层：安装类场景换"不依赖 GitHub"的路径 — 按场景（安装类工具）

• 只想用工具：pip install <包>（清华镜像 -i https://pypi.tuna.tsinghua.edu.cn/simple），不需要 clone 源码；
• 技能/插件：tarball 解压后手工复制到对应目录（如 cp -r agent-skills-0.6.7/skills ~/.claude/skills/）；
• 判断成功看产物（目录/文件就位），不要只看 exit 码（部分 CLI 失败时 exit 码仍为 0）。

4. 配置层：查重写规则与失效代理 — 按诊断结果（配置层命中才走）

git config --global --get-regexp 'url\..*\.insteadof'   # 看到 url.git@github.com:.insteadof = 元凶
git config --global --list | grep -i proxy               # 代理残留检查
git config --global --unset-all "url.git@github.com:.insteadof"
git config --global --unset http.proxy
git config --global --unset https.proxy

5. 凭据层：SSH 与 gh 凭据助手 — 按诊断结果（凭据层命中才走）

git ls-remote git@github.com:<owner>/<repo>   # Permission denied (publickey) = SSH 层问题
git config --global url."https://github.com/".insteadOf "git@github.com:"   # 强制 HTTPS（公开仓库匿名即可）
gh auth status                                # 凭据助手状态
gh auth logout && gh auth login               # 重新授权

6. 下载后校验完整性 — 必做（收尾）

du -h pkg.deb        # 对照资产页标注大小，差太多 = 断了一半，重下
dpkg-deb -I pkg.deb >/dev/null && echo DEB-OK   # 结构可读 = 完整（deb 类）

变体速查表（8 条同根条目并入）

怎么确认修好了

• 网络层：原命令（clone / 下载 / 安装）完整跑完，无 reset by peer / Timed out；下载类对照资产页大小一致。
• 配置层：GIT_CONFIG_GLOBAL=/dev/null git ls-remote https://github.com/octocat/Hello-World.git 返回 refs；重写规则与失效代理已删。
• 凭据层：公开仓库匿名 HTTPS 可 clone；需要 SSH 的场景 git ls-remote git@github.com:... 不再报 Permission denied；22 端口被拦时 ssh -T -p 443 git@ssh.github.com 能认证成功。- 凭据层：公开仓库匿名 HTTPS 可 clone；需要 SSH 的场景 git ls-remote git@github.com:... 不再报 Permission denied。
• 安装类：看产物就位（目录/文件），不看 exit 码。

其它环境的表现

症状

• git clone 卡在 Cloning repository 后报 Connection reset by peer / 超时；
• Failed to connect to github.com port 443；
• SSH authentication failed / Permission denied (publickey)；
• 公开仓库也报 Please make sure you have the correct access rights and the repository exists；
• Release / zip / tarball 下载反复断连、TLS 中断；
• 部分 CLI 失败时 exit 码仍为 0（坑）。

原因

国内出口到 GitHub 直连不稳定（Release 资产另走 objects.githubusercontent.com，链路更差）；老教程留下的 HTTPS→SSH 全局重写规则与失效代理残留放大问题；SSH key / gh 凭据 / 账号状态异常时，连公开仓库也被拒。

解法

1. 分层诊断：curl https://github.com/ + GIT_CONFIG_GLOBAL=/dev/null git ls-remote 区分网络层/配置层/凭据层；
2. 网络层换通道：gh-proxy 前缀、codeload tarball、浅克隆、显式代理、错峰/换网络；SSH 被墙时走官方 443 通道（ssh.github.com）；2. 网络层换通道：gh-proxy 前缀、codeload tarball、浅克隆、显式代理、错峰/换网络；
3. 安装类换不依赖 GitHub 的路径：pip 清华镜像、tarball 手工复制；判断成功看产物不看 exit 码；
4. 配置层删重写规则与失效代理；凭据层强制 HTTPS / gh 重新授权；
5. 下载后校验大小/结构。

相关 canonical

按「同根（网络层出口不稳，换源家族）」读：

• pip 安装超时/慢（网络层同类，PyPI 源配置）
• npm install 慢/挂起（网络层同类，npm 源配置）
• Go 模块拉取慢/超时（网络层同类，Go proxy 配置）
• docker pull 失败/镜像加速（网络层同类）
• 只有个别网站打不开（其他网站正常）——分层定位（同分层思路：先 curl 定位网络层）

报错相近但根因不同：TLS/证书类问题。

参考资料

• GitHub Docs: Using SSH over the HTTPS port — <https://docs.github.com/en/authentication/troubleshooting-ssh/using-ssh-over-the-https-port>