1. 卡在 Receiving objects 的晚上GitHub 下载慢到底卡在哪1.1 三种典型卡死现场先说一个很具体的场景。某天晚上我想拉一个开源项目命令敲下去先是remote: Enumerating objects走了几秒然后进入Receiving objects百分比停在一个数字上不动了。等了五分钟我以为是网络波动按了 CtrlC 重新来结果这一次连Enumerating objects都没走完。这不是偶发情况。Git 拉取 GitHub 仓库卡住基本逃不过下面三种形态形态一Receiving objects卡在某个百分比。最常见尤其仓库历史里躺着几个大文件时进度条压根不往前走。形态二下载中途直接报错退出。比如fatal: early EOF、index-pack failed、RPC failed; curl 56这类本质是传输中断Git 没法把收到的对象完整拼起来。形态三Resolving deltas阶段卡死。这个阶段考验的是本地 CPU 和内存要解析远端传过来的压缩对象仓库提交历史一多进度也可能非常慢甚至看着像死掉。这三种形态的“卡”位置不一样原因也不完全一样需要分清楚因为后面选的解决方式完全不同。1.2 不是所有仓库都卡真正影响下载速度的因素网上很多人说“GitHub 下载慢”其实并不准确。很多几十 MB 的小仓库直连下载照样能跑完只是慢点。真正卡死的仓库往往有这几个共同点仓库体积大、历史记录重。Git 的特点是会把整个项目的完整提交历史全部拉下来而不只是当前这份代码。一个仓库现在代码可能只有 50MB但十年历史里改过的二进制资源、被误提交过的大文件、后来删掉的文件全都藏在.git对象库里。git clone的时候这些对象一个都跑不掉。单个文件特别大。比如仓库里塞了一个 100MB 的模型权重、视频、安装包。这种文件一旦传输中断Git 不会断点续传而是从头再来失败概率直线上升。本地网络到 GitHub 的传输质量不稳定。这个属于客观因素。直连时数据包要经过很多跳数中间任意一段丢包严重最终表现就是 Git 进度条停滞因为 Git 底层走的是 HTTP/HTTPS 传输TCP 丢包会导致窗口缩小速度掉到几乎为零。DNS 解析结果不理想。有些时候域名解析出来的 IP 绕了远路或者解析结果本身就不稳。你不妨在卡住的时候执行一下nslookup github.com如果解析出来的 IP 和你平时不一样或者 ping 的延迟忽高忽低那说明域名解析这层就已经不顺畅了。1.3 反复重试是最差的策略我在最开始踩过的一个坑就是卡住就 CtrlC然后重新git clone。这样做不仅浪费时间还可能让情况越来越糟。原因很简单git clone默认不做断点续传每次都是全新的完整下载。仓库体积越大失败代价越高。而且频繁从同一网络路径发起大流量请求很容易触发服务端的限流让你从“慢”变成“直接拒绝”。我自己遇到过一次连续重试三遍后远端返回fatal: unable to access的频率比第一次高得多。正确做法是先git clone --depth 1只拉最新一次提交的快照绕开庞大的历史对象。但这一步只是临时救急真正要彻底解决问题还是要靠换一条更顺的下载路径也就是下面要说的清华镜像。2. 清华镜像能管什么不能管什么2.1 清华镜像到底是什么清华大学开源软件镜像站通常叫 TUNA 镜像站域名是mirrors.tuna.tsinghua.edu.cn。它做的事情可以用一句话概括把很多常用开源软件、Linux 发行版、编程语言包管理器、操作系统安装镜像等从各自的官方源同步到清华的服务器上提供一个国内访问速度非常快的下载地址。你可以把它理解成一个“本地仓库”官方源在美国、欧洲访问慢清华镜像在国内访问快。只要官方源允许同步它就尽量做到每天甚至更频繁地同步更新。很多人在使用过程中只记住了 PyPI 镜像和 Anaconda 镜像实际上它覆盖的范围远不止这些。包括 Python 官方安装包、JDK 发行版、Homebrew 的 bottle 包、Linux 发行版 ISO、Docker 镜像仓库等都有对应的镜像路径。2.2 它能直接解决哪些“卡住”场景结合我自己的使用经验清华镜像在下面几类场景里几乎是“药到病除”第一Python 依赖包安装卡住。你执行pip install torch如果直连 PyPI 官方源大概率会卡在Downloading阶段。把 pip 源切换成清华 PyPI 镜像后速度通常能快到几 MB/s 甚至更高。第二Anaconda 创建环境或安装包卡住。Conda 默认的repo.anaconda.com在国内访问一直不太稳定配置清华 Anaconda 镜像后创建环境的成功率会高很多。第三下载编程语言或工具链安装包。比如想装 Python 3.10.11直接去 python.org 下载可能很慢而清华镜像里有一个python/目录里面按版本号完整保留了 Windows、macOS、Linux 安装包直接用浏览器或命令行下载都很快。第四想下载某个项目的发行版压缩包而不是整个 Git 仓库。很多项目在 GitHub Releases 中也会同步源码 tar.gz 包。如果你的目标是拿到代码看看不一定非要用git clone直接下载压缩包解压就能用。压缩包整体是一个文件下载时即使慢也比分段传输更稳。2.3 它管不了的事清华镜像不等于 GitHub 全站镜像这里必须诚实地说明一点清华镜像并没有提供“把整个 GitHub 所有仓库都镜像一份然后让你git clone”的服务。你在清华镜像站上找不到git clone https://mirrors.tuna.tsinghua.edu.cn/github.com/xxx.git这种通用地址。它镜像的是具体某个软件、某个发行版、某个包而不是 GitHub 全站。所以如果网上有人说“用了清华镜像就能让所有 GitHub 仓库秒 clone”这个说法是不准确的。真实情况是清华镜像能帮你说服很多“因为 GitHub 下载而卡住的下游环节”比如依赖包、安装工具、环境。但如果你想 clone 的仓库本身不在清华镜像覆盖范围内那就需要配合其他 Git 镜像地址来做中转下载。这个问题想清楚之后解决方案反而更好选了不要迷信单一方案而是根据项目类型组合使用。3. 实操三种能立刻抄走的镜像替换写法3.1 方案一用 URL 前缀改写的方式 clone GitHub 仓库这是最简单、最直接的替代方案。网上常见的镜像前缀是https://gitclone.com/github.com/使用方法就是把原来的 GitHub 地址从https://github.com/用户名/仓库名.git改成git clone https://gitclone.com/github.com/用户名/仓库名.git原理是让 Git 去请求这个镜像服务由镜像服务转发到 GitHub 拉取数据再把数据传回给你。因为镜像服务访问 GitHub 的速度通常比你直连更快所以能明显改善卡住的问题。不过要提醒一句这种镜像服务的稳定性和安全性依赖维护方不同时期不同镜像的可用性差异很大。我的经验是如果git clone失败先换镜像地址而不是反复重试原地址。针对标题里说的“清华镜像”如果你发现清华镜像站里恰好有这个仓库的独立镜像可以优先用清华地址如果没有再使用 gitclone 这类通用 Git 镜像前缀。3.2 方案二全局改写配置一劳永逸如果不想每次都手改 URL可以用insteadOf配置让 Git 自动帮你替换。执行git config --global url.https://gitclone.com/github.com/.insteadOf https://github.com/这条命令的意思是以后所有试图访问https://github.com/开头的地址Git 都会自动改成https://gitclone.com/github.com/开头。你不需要改变任何git clone命令的写法原来怎么写还是怎么写。但注意这个配置是全局生效的也会影响git push。大部分镜像站是只读的不支持推送所以如果你后续要推送代码需要先把这个配置去掉git config --global --unset url.https://gitclone.com/github.com/.insteadOf更稳妥的做法是按仓库配置不要设置 global。在某个仓库里执行git config url.https://gitclone.com/github.com/.insteadOf https://github.com/这样只对该仓库生效不会误伤其他项目。不过说实话按仓库配置麻烦我一般只在确定只是拉取、不推送的仓库里才用全局。3.3 方案三浅克隆大幅降低下载量镜像地址解决的是“传输路径不顺”的问题但对仓库本身特别大的情况效果有限。这时候需要结合浅克隆只拉最新提交不拉历史git clone --depth 1 https://github.com/用户名/仓库名.git--depth 1的参数含义是只拉取最近一次提交对应的文件快照历史记录全部不要。对一个大仓库来说下载量可能从几个 GB 降到几十 MB卡住的概率直线下降。还可以配合--single-branch只拉默认分支避免把仓库里所有分支都拉下来git clone --depth 1 --single-branch https://github.com/用户名/仓库名.git如果项目里需要的只是某一个子目录连整个仓库都不用下可以用稀疏检出git clone --depth 1 --filterblob:none --sparse https://github.com/用户名/仓库名.git cd 仓库名 git sparse-checkout set 需要/的/目录--filterblob:none表示先不下载文件内容只获取目录结构--sparse开启稀疏模式git sparse-checkout set再按需拉取指定目录。这套组合对那种“仓库巨大但只需要其中一小部分代码”的场景特别有效。4. 配置完仍然卡完整排查链路复盘4.1 第一步先确认卡在哪个阶段镜像地址配好之后如果还是卡不要急着换更多镜像先看清楚输出信息卡在哪。卡在remote: Enumerating objects阶段说明请求已经到达远端远端在准备对象列表此时卡顿主要是服务端处理大仓库时本身就需要时间和你的网络关系不大。卡在Receiving objects阶段说明本地正在接收数据此时如果速度低那就是传输链路的问题优先怀疑镜像地址、DNS、网络丢包。卡在Resolving deltas阶段说明数据已经收完本地正在解析此时 CPU 和内存会飙高。如果仓库提交历史很深这个阶段可能非常慢。解决方案是减少历史提交数量也就是用--depth 1。我把这几个阶段的判断整理成了一张表方便对照卡住位置问题本质推荐方案Enumerating objects远端仓库过大服务端准备慢放弃完整 clone改浅克隆Receiving objects传输链路慢或丢包换镜像地址、检查 DNS、断网重试Resolving deltas本地计算资源不足--depth 1、增加内存、耐心等待4.2 第二步查看 DNS 和实际连接速度镜像地址也挂了的话先把网络问题拆开看。执行nslookup github.com nslookup gitclone.com看看两个域名解析出的 IP 是否正常是否稳定。然后实测到目标地址的连通性。Windows 上可以用Test-NetConnection github.com -Port 443Linux 或 macOS 上可以用curl -I --connect-timeout 5 https://github.com如果curl能快速返回响应头说明网络本身是通的但 Git 慢可能与库的大小、HTTP 缓冲区设置有关。此时可以试着调大 Git 的 HTTP 缓冲区减少单次请求失败的概率git config --global http.postBuffer 524288000这个参数把 Git HTTP 发送缓冲区调到 500MB对某些“小水管”场景有一定帮助但也不是万能的不要指望设定它就能解决所有卡顿。4.3 第三步子模块和 LFS 是隐藏杀手很多仓库卡住卡在你看不见的地方。最常见的是子模块。假设你 clone 的主仓库很小但里面有.gitmodules文件指向了多个其他 GitHub 仓库。执行git submodule update --init --recursive时每个子模块都要单独从 GitHub 拉取。如果子模块地址写死的是https://github.com/...而你前面配置的insteadOf是按前缀替换的理论上子模块也会自动走镜像。但实际情况是有些项目在子模块里使用了 SSH 地址或相对路径就会绕过你的替换规则继续直连 GitHub。排查方法是在 clone 完成后执行git submodule status看看是不是卡在某个子模块上。如果是可以手动删除该子模块的地址改成镜像地址或者直接只拉取你需要的子模块。另一个隐藏杀手是 Git LFS。大型仓库经常用 LFS 管理二进制文件但 LFS 文件不在普通 Git 对象里而是存放在独立的 LFS 服务器上。默认情况下git clone https://github.com/xxx/yyy.git不仅拉 Git 对象还会同时拉取所有 LFS 文件体积可能暴涨。如果仓库主要让你卡住的正是 LFS 文件可以先跳过 LFSGIT_LFS_SKIP_SMUDGE1 git clone https://github.com/xxx/yyy.git这样只拉代码和历史记录不拉 LFS 二进制文件。之后等你真正需要某个文件时再单独执行git lfs pull --include路径/文件名按需拉取避免一次性把整个仓库的大文件全下载下来。4.4 第四步检查系统时间、证书和限流镜像地址配好了但 Git 报错SSL certificate problem: certificate has expired这其实多半不是证书真的过期而是本地系统时间不对。Git 校验证书时会看有效期系统时间如果在去年任何证书都会“已过期”。先校准系统时间再重启 Git 操作。如果报错是unable to access或HTTP 403则可能是镜像源限流。Git 镜像服务一般都有并发和流量限制你需要换一个镜像源而不是继续重试同一个。可以用git config --global url.https://gitclone.com/github.com/.insteadOf https://github.com/也可以临时改用另一个镜像前缀把原来的 unset 掉再配新的。镜像地址没有哪个是永久有效的我的习惯是先列出一两个备用哪个能用用哪个。5. 把依赖安装也纳入清华镜像体系5.1 pip 卡住切清华 PyPI 镜像很多时候你以为自己在“下载 GitHub 项目”但项目代码 clone 下来之后安装依赖才是真正的大头。比如一个 Python 项目git clone可能 10 秒就完成了但pip install -r requirements.txt卡了半小时。针对 Python 包安装清华镜像是最成熟的解决方案之一。临时指定pip install -i https://pypi.tuna.tsinghua.edu.cn/simple 包名永久配置pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple配置完成后再安装依赖就会优先从清华 PyPI 镜像下载。有些包在 PyPI 上没有编译好的 wheel需要从源码构建而源码包可能托管在 GitHub 上这种情况下 pip 也会去下载 GitHub 上的源码 tar.gz。如果这一步卡住可以先手动下载对应源码包放到本地再通过pip install 本地路径安装绕开网络下载。5.2 Anaconda 卡住配置清华 conda 镜像创建 Conda 环境时最容易卡住的两个环节是下载 Python 解释器包、下载 Conda 包索引。直连官方源时慢是常态配置清华镜像后通常会有明显改善。添加清华 Anaconda 镜像通道conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/ conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/ conda config --set show_channel_urls yes如果需要conda-forge通道也可以把通道地址换成conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/配置完成后建议先执行一次conda clean -i清除之前的索引缓存再创建环境。否则 Conda 可能还在用旧的、拉取失败的缓存结果就是配置改了但依然卡住。5.3 Python 和 JDK 安装包也走清华镜像除了包管理器编程语言解释器本身的安装包同样可以走清华镜像。以 Python 3.10.11 为例直接在清华镜像站下载https://mirrors.tuna.tsinghua.edu.cn/python/3.10.11/里面按操作系统分好了目录比如 Windows 的 installer、macOS 的 pkg、Linux 的源码包。比去 python.org 官网下载快很多。JDK 也有类似场景。在清华镜像站的 Adoptium 镜像路径下可以找到不同版本、不同平台的 JDK 安装包。比如想装 Temurin 17直接去对应目录挑.zip或.tar.gz下载解压后配置环境变量就能用。这些场景虽然不直接是“Git 下载 GitHub 项目”但很多开发者在实际操作中遇到的“下载卡住”一大半都发生在这些工具链环节。把清华镜像用到位等于把整条工具链的水源都换成了国内缓存。5.4 Homebrew 和前端依赖的顺带一说如果你用的是 macOSHomebrew 安装软件时也会从 GitHub Releases 下载很多预编译的 bottle 包卡住的情况很常见。配置清华 Homebrew 镜像可以改善export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles前端项目安装 npm 依赖卡住时可以临时切换 npm 镜像地址npm install --registryhttps://registry.npmmirror.comMaven 项目依赖下载卡住时可以配置阿里云 Maven 镜像。这些方案和清华镜像的核心思路一致换个更快的源让下载真正落地。6. 把整个下载过程变成一套可复用的预案6.1 不同场景直接按表操作经常有朋友问我“GitHub 下载卡住怎么办”我现在的习惯是不直接回答一个命令而是先反问几个问题卡在哪个阶段仓库大不大是要代码还是要安装包然后按场景给方案。用一张表总结我自己的处理逻辑场景症状首选方案备选方案小仓库 clone慢但能完成直连镜像前缀中大型仓库 clone卡在 Receiving--depth 1 镜像前缀下载压缩包解压仓库含大目录卡死或无响应--filter--sparse按需拉取下载单个 raw 文件Python 依赖安装pip 下载慢清华 PyPI 镜像本地源码包Conda 环境创建卡在 solving/下载清华 conda 镜像换 conda-forge 通道下载 Python/JDK 安装包官网下载慢清华镜像对应目录手动下载后内网分发这套预案的好处是不用每次遇到卡顿都从零开始想直接按症状对照方案执行能省下很多时间。6.2 我的日常下载习惯最后分享几个我自己的操作习惯算是踩坑之后形成的肌肉记忆。第一能用压缩包就不 clone。如果我只是想看代码、跑个 demo直接下载 GitHub 页面的 Code 按钮里那个 “Download ZIP”解压就能用。这一步绕过了 Git 对象传输只下载一个文件稳定性高很多。第二clone 前先看仓库体积。GitHub 仓库主页往下拉能看到语言统计和文件列表。如果明显有.zip、.pth、.bin这种大文件我会直接加--depth 1甚至配合GIT_LFS_SKIP_SMUDGE1把大文件先隔离在下载范围之外。第三不要同时配置太多层镜像。有些人配了 git 的insteadOf又配了 ssh 地址替换还设置了 http 代理结果出现问题后完全不知道是哪个环节出错。我的做法是保持配置精简一次只启用一层镜像确认生效后再叠加其他优化。排查时也方便回滚。第四关注官方文档而不是二次转述的教程。清华镜像站在官网每个镜像页面都提供了完整的使用说明和更新状态包括同步时间、磁盘占用、失效公告。遇到配置问题先去看一眼官方页面很多时候比到处搜索“最新可用地址”更靠谱。Git 下载 GitHub 项目卡住这件事说到底是传输路径和仓库体量两个核心变量的问题。清华镜像解决的是一部分路径问题浅克隆解决的是体量问题按需拉取解决的是耐心问题。把它们组合起来基本上九成以上的卡顿场景都能找到出路。