断点续传技术完整实现文档干这一行久了你会发现一个特别朴素的真理在网络上传输数据没有一次连断是意外你迟早会在断点上栽跟头。断点续传这个话题从我早年折腾FTP下载到现在做大文件上传、维护git仓库几乎每个阶段都会撞上它。这篇文章我就把断点续传这件事从头到尾掰开揉碎从底层原理、前端分片到后端合并顺便聊聊git clone这个破天荒不支持断点续传的顽疾到底怎么绕以及断点续传和完整上传之间那条很多人没想明白的线到底划在哪里。如果你正在做一个上传组件、被大文件传输折磨过、或者只是想知道为什么git clone断了只能从头再来这篇文档都值得你花十分钟看完它既适合刚入门的新手也能给老手提个醒。先说一个真实场景。之前我给客户做一个大文件上传系统一块几十GB的监控录像要传到云端内网环境还好一旦走公网分分钟给你断一次。第一次设计时我图省事直接上完整上传结果客户骂街了。从那以后我彻底明白了断点续传不是锦上添花而是刚需。它的核心逻辑用一句话概括就是——把一次大传输拆成若干小单位记录进度失败了从最近的位置重新来而不是从头再来。听起来很简单但真做起来里头全是细节。1. 断点续传到底是什么从一个下载中断说起1.1 断点续传的核心原理Range与分片很多人以为断点续传是一个高深的技术其实它的底层原理一点都不神秘。你想象一下看书看到第100页停电了你夹个书签来电了从第101页接着看这就是断点续传。HTTP协议里有对应的实现——Range请求头。客户端可以跟服务器说我不需要从第0字节开始你从第10000字节开始给我发。服务器如果支持就返回206 Partial Content状态码带着指定范围的数据给你。这里有个关键点Range是按位置offset计算的不是按时间、不是按文件名是按绝对的字节偏移量。比如一个100MB的文件你下了50MB断了重连后你请求Range: bytes52428800-服务器就从第52428800字节开始继续发。这个机制在HTTP下载工具比如IDM、aria2、音视频播放器拖动进度条里都被用得飞起。那“分片”又是怎么回事呢如果说Range是协议层面的断点续传分片就是我们应用层面的断点续传。我们拿到一个文件把它按固定大小切开比如每个分片5MB然后逐片上传。每一片都是一个独立的HTTP请求已经传成功的片就标记一下没传的继续传。这本质上是一种“多进度条”的断点续传比单个Range更灵活。比如你并行上传10个分片其中3个失败你只需要重试这3个其他7个不用动。1.2 为什么断点续传比完整上传更“聪明”两者的本质区别断点续传和完整上传的区别表面上是一个“切开了传”一个“一口气传”但背后的架构思想完全不同。完整上传就是把一个文件当作一个整体POST到服务器一把梭。它的优点就是实现简单代码量少服务器逻辑也简单——收完了存下就行。但缺点也很明显不支持并发、无法高效重试、对网络要求极高而且整个传输过程中服务器端占用的连接资源是持续的一个大文件可能要连续占用几分钟甚至几小时对服务器的并发连接数是个不小的压力。断点续传则是把一个传输任务拆解成多个可独立完成的小任务。它的优势是三方面的失败恢复成本低坏了哪片重传哪片、可以并发加速同时传多个分片、网络抖动容忍度高。但代价是你必须引入额外的复杂度——分片管理、进度存储、校验算法、合并服务任何一个环节处理不好都会带来新的问题。我见过一些团队一上来就抱着“用断点续传一定比完整上传好”的想法结果在小文件上强行上断点续传性能反而更差。文件只有50KB你切成10个5KB的分片来回传性能损耗比你省下来的那点重试成本高多了。所以“聪明”是相对的要看场景。这块我下面会专门展开说。2. 完整上传与断点续传的博弈架构与场景对比2.1 什么时候用完整上传什么时候必须断点续传我们先澄清一个容易被误解的概念断点续传不是完整上传的“升级版”它们是两个不同场景下的不同工具。我给不少项目做过技术选型一个靠谱的判断逻辑是这样的文件小于10MB网络环境稳定比如内网用户体量小——用完整上传。为什么因为断点续传的额外开销主要集中在分片计算、进度存储、服务端合并这些在小文件场景下完全是浪费。文件在10MB到500MB之间网络可能波动比如办公网络、移动网络——强烈建议做分片断点续传。这个区间的文件一旦完整上传中途断了用户心态会瞬间崩掉。文件超过1GB属于大文件——必须断点续传而且要严格设计并发和重试策略否则传输成功率会降到惨不忍睹。还有一个隐秘的临界条件服务器是否有上传时长限制。很多网关、反向代理、云负载均衡器都会设置请求超时时间普遍在几十秒到几分钟不等。如果完整上传一个大文件超过这个时限连接就被强制断掉了。断点续传由于每个分片小单次请求时间短反而能巧妙地“绕过”这个超时限制。另外还要看用户对传输进度的感知需求。完整上传就好比你在银行柜台办一笔大额转账中间排队等待感受不到进度只知道“没办完、还在忙”。断点续传就好比你把转账拆成好几笔小额汇款每一笔都能看到状态哪个环节卡了你能精准定位。在很多产品设计中进度条和失败提示的颗粒度直接决定用户体验的成败。2.2 断点续传的三种典型实现架构从架构层面看断点续传大致有三条路本地方案纯前端分片所有逻辑都跑在浏览器或客户端里。前端读取文件切成一片片逐片上传同时把“哪些分片已上传”的记录存在本地localStorage或IndexedDB。上传中断后重新检测本地记录只上传缺失的分片。它的优点是服务端改动小缺点是进度记录在本地换一台电脑就接不上了。服务端方案服务端分片存储上传前前端告诉服务端“我要传这个文件”服务端返回一个上传会话ID并且告诉你这个文件已经有哪几个分片了。前端只传缺失的分片。这种方案把进度状态放到服务端跨设备续传也支持缺点是服务端需要多设计几张表。协议层方案依赖网络协议比如HTTP的Range请求你自己不切分片而是直接让服务器支持Range。下载软件用的就是这种。又比如rsync这个工具它不是分片而是把整个文件做差异传输哪个块发生了变化就传哪个块。这是更底层的断点续传我们一般在自己写代码的时候用前两种更多。下表把这几种方案的核心差异罗列一下对比维度完整上传前端分片方案服务端分片方案协议层Range方案实现难度很低中等较高低重试成本高从头再来低按分片重试低服务端精确续传低从offset继续并发能力无多分片并发多分片并发单连接串行跨设备续传不适用不支持支持不适用适用场景小文件、内网浏览器大文件上传云存储、网盘下载器、播放器3. 断点续传的完整实现路径从前端到后端3.1 前端分片文件怎么切、切多大前端要做的第一件事就是把File对象切分。在浏览器里可以直接用Blob.slice()方法这是浏览器原生支持的不需要外部库。以JavaScript为例伪代码如下// 假设你有一个File对象比如从input里拿到的 const file input.files[0]; // 每个分片大小我通常取 5MB这个值可以调 const CHUNK_SIZE 5 * 1024 * 1024; let chunks []; for (let start 0; start file.size; start CHUNK_SIZE) { chunks.push({ chunk: file.slice(start, start CHUNK_SIZE), index: chunks.length }); }切多大会比较合适这没有绝对标准但根据我的经验有几条参考分片太小的坏处请求数量爆炸比如一个1GB文件切成1MB分片就是1024个请求光是建立连接的开销就压垮浏览器而且服务端要处理大量的元数据。分片太大的坏处一旦某一个分片传输失败重试成本高同时单请求占用时间长容易触发超时。我的常用值文件越大分片越大。100MB以下的文件用2MB分片500MB左右用5MB超过1GB我会考虑用10MB甚至20MB。原则就是让分片数量控制在100到500之间既不太多也不太少。另外一个容易被忽略的问题是分片在传输时要携带文件的唯一标识。如果你只是传分片数据过去服务端根本不知道这些分片属于哪个文件。常见的做法是前端计算整个文件的MD5或SHA-1哈希值把它和分片序号一起发过去。但要注意计算大文件的MD5并不是一个瞬间操作1GB文件算哈希可能要几秒钟甚至更久所以我认为比较合理的做法是如果不在乎那么高的完整性可以只计算文件大小文件名最后修改时间来生成一个弱标识如果严谨一点就得做一次全文件读取用加密库计算哈希。后者能保证文件内容级别的唯一性代价是性能。3.2 后端合并与校验如何保证数据不丢不重当前端把分片一个个传上去之后服务端就得做一个合并操作把散沙聚成塔。这个阶段也是最容易出bug的地方我见过太多系统在“合并”这一步翻车。服务端接收分片的存储目录通常是一个临时目录每个分片单独存成一个文件。合并时的思路是先按分片序号排序再依次写入最终文件。以Node.js为例// 假设每个分片已经上传到 server.tmp 目录 const fs require(fs); const path require(path); async function mergeChunks(identifier, totalChunks, finalName) { const tmpDir path.join(/tmp, identifier); const outputPath path.join(/storage, finalName); // 创建写入流 const writeStream fs.createWriteStream(outputPath); // 按顺序读取每个分片并写入 for (let i 0; i totalChunks; i) { const chunkPath path.join(tmpDir, ${identifier}-${i}); const data await fs.promises.readFile(chunkPath); if (!writeStream.write(data)) { // 如果写入速度跟不上读取速度等待drain事件 await new Promise(resolve writeStream.once(drain, resolve)); } } writeStream.end(); }合并的操作看起来简单但有几个坑必须提前规避。第一是文件名的冲突。两个不同的用户上传了同名文件怎么办不能只靠名字得加上用户ID和上传会话ID来隔离。第二是分片的缺失。如果你发现分片序号中间缺了一段千万别合并先让前端把缺失的分片传完。第三是磁盘空间不足。合并时需要一份完整文件的存储空间同时临时目录还要存一遍所有分片所以实际占用的磁盘空间是最终文件的两倍。这是很多人预估容量时漏掉的。合并完成后还有一个至关重要的环节——校验。服务端要把合并好的文件从头到尾算一遍哈希比如MD5或SHA-256和前端上报的整文件哈希比对。如果一致说明整个传输过程是正确的如果不一致说明某个分片在传输过程中可能被篡改、损坏或者传重复了。这时你不能说“上传成功了”得让前端重新传验不过的部分。为了做这一步我通常会在每个分片单独上传时就校验分片自身的哈希前端先把分片的MD5发给服务端服务端存盘后再比对一次。这样可以把问题提前暴露在分片阶段而不是等到合并结束后才发现整体校验失败。这也是我踩过坑之后总结出的经验千万不要省分片级校验不然合并后的排错成本高得离谱。3.3 关键参数分片大小、并发数、重试策略的设计断点续传的很多“坑”其实不在原理而在参数设计上。你随便找一个在线文档可能只告诉你“要分片”但没人告诉你这些参数到底怎么配。我挨个说清楚。并发数浏览器的HTTP并发限制一般是同域6个左右但这不意味着你就该把并发开到6。我用过几个档位做个参考内网环境服务端性能好并发可以开到5到8迅速把文件传完。公网环境链路质量差并发建议控制在2到3。为什么因为分片传上去之后服务端必须按顺序合并如果并发太高后面的分片都到了前面的还没到等待队列会占用大量内存与磁盘临时文件空间。另外高并发在弱网下反而容易触发丢包和超时得不偿失。我通常的做法是动态调节前几个分片用较低并发先探路看看丢包和时延情况如果网络状况好逐步增加并发。这个思路比固定并发数更稳健。重试策略每个分片上传失败后你是立即重试还是等待我认为最有效的重试策略是指数退避算法。第一次失败后等1秒第二次失败后等2秒、4秒、8秒最多等待30秒。不要连续快速重试那样只会让已经拥堵的网络更加拥堵。同时要设置最大重试次数比如10次超过之后直接判定该分片失败并通知用户“网络异常请稍后再试”而不是无限期卡住。进度存储如果是浏览器环境上传进度记在哪里是一个容易被忽视的问题。用localStorage可以但小心容量限制和刷新丢失。我建议用IndexedDB功能更强空间更大而且不会轻易被浏览器清理。存的内容包括文件标识、分片大小、总分片数、已成功分片的序号列表。这样即使浏览器刷新也能恢复上传。秒传与断点续传的结合这里说一个高阶设计。当用户再选择同一个文件上传时可以先问服务端这个文件我是不是已经传过了服务端检查一下文件哈希如果发现已经存在完整文件就直接返回“上传成功”这就是秒传。如果发现传过一半就返回“你还有哪些分片没传”这就是断点续传。两者共用同一套存储结构实现起来其实不复杂但用户体验直接翻倍。4. git clone 断点续传一个被反复问起的伪需求4.1 git clone 为什么天生不支持断点续传“git clone能不能断点续传”这个问题我几乎每个月都要被问一次。答案很遗憾不能git clone本身就没有断点续传能力。这跟SVN不同SVN的checkout支持断点续传中途断了下次继续不会重复下载。而git clone的设计是它会先下载一个包含所有对象objects的仓库包然后本地做一次checkout。如果中途网络断了整个clone流程就终止了你再次执行git clone只能从头开始。为什么git不做断点续传从设计哲学上讲git是分布式版本控制系统它把仓库内容以对象commit、tree、blob的形式存储对象之间有复杂的引用关系。clone过程会执行一个所谓的packfile negotiation包文件协商流程客户端告诉服务端“我有什么、你要什么”服务端动态生成一个数据流。这个数据流是流式的、无状态的一旦中断客户端没有持久化的局部状态来告诉服务端“你上次发到了哪里”。所以从底层机制上git clone想断点续传就不是一个简单的功能点而是一次架构革新。Git官方选择不去做这件事而是鼓励用户通过浅克隆shallow clone或后续用git fetch来避免全量传输。4.2 网络中断后的实际应对方案既然知道git clone不支持断点续传那我们在实际开发中遇到clone中断该怎么办我的经验总结成四个办法方法一浅克隆shallow clone。先把克隆深度降低只拉最新一版git clone --depth 1 https://github.com/user/repo.git这样传输的数据量极小即使断了重来也很快。等你需要历史记录时再用git fetch慢慢补git fetch --depth50 origin main这个方法适合仓库特别大、网络环境不稳定的情况。很多大型开源项目比如内核源码官方文档也推荐这种玩法。方法二从能访问的其他协议入口走。很多时候git clone走的是HTTPS网络质量不行但同一台服务器可能还开放了SSH端口。切换协议试试# 原来的 git clone https://github.com/user/repo.git # 换成 git clone gitgithub.com:user/repo.git如果服务器上开放了git协议的9418端口也可以试试git://协议。不同的协议走不同的TCP连接路径虽然最终还是同一根网线有时实际效果差别很大。方法三用镜像站点或预下载tar包。如果clone的是GitHub上的仓库可以先通过GitHub提供的codeload地址下载zip/tar.gz包解压后再用git init把这个目录变成一个git仓库。注意这样不会带git历史只带当前快照历史还得靠后续fetch补。方法四换网络环境。听起来像废话但实践中真的管用。很多clone中断不是带宽不够而是路由丢包严重。断点续传在这种场景下不是技术问题而是物理问题——你换个热点、换条线也许一次就成功了。4.3 从协议到仓库管理的四个变通思路如果你要长期在弱网环境下操作大仓库我建议你别只惦记“断点续传”这个功能而是从流程上改变使用方式。以下是四个亲测有效的思路仓库瘦身不要一股脑clone整个仓库用--filterblob:none选项只下载提交树和文件元数据等到真正需要内容时再按需拉取具体文件。这个功能叫partial clone部分克隆Git 2.19以上版本支持搭配--depth使用效果更好。git clone --filterblob:none --depth 1 https://github.com/user/repo.git这条命令拉下来的仓库体积通常只有完整仓库的一半甚至十分之一速度大幅提升。先打包再搬运如果你有另一台机器或者一个临时跳板机能完整访问仓库可以在这台机器上生成一个bundle文件相当于一次性打包然后把bundle文件传输过去再从bundle拉取到本地。传输bundle文件可以用任何支持断点续传的工具比如rsync或aria2这样就迂回实现了“git仓库的断点续传”。# 在源机器上 git bundle create repo.bundle --all # 用rsync传输bundlersync天然支持断点续传 rsync -avP repo.bundle userdestination:/path/ # 在目标机器上从bundle克隆 git clone repo.bundle用已有仓库增量fetch如果你之前有过一次完整的clone只是后来中断了更新那根本不需要重新clone只需要git fetch origin它是支持增量下载的失败了再来一次就好。很多人把“clone中断”和“fetch中断”混为一谈前者确实需要重来但后者其实一直在天然支持断点续传。管理预期如果仓库极端庞大比如超过5GB我建议你放弃完美主义把“一次性拿到全部历史”改成“分步获取”。先用浅克隆再定期git fetch --deepen加深。这个过程虽然繁琐但每一步失败成本都很低本质上是把一次大任务拆成了多个小任务——这就是断点续传的核心思想只不过不是在协议层面实现的而是在流程层面实现的。5. 完整实现中的常见问题与排查技巧实录5.1 分片丢失、校验失败、重复上传做了这么多年的断点续传系统我把实际项目中遇到过的高频问题整理成一个排查清单触发条件、原因和解决方案都给你们列出来现象可能原因排查方法解决方案合并后文件哈希不一致传输中某个分片损坏对比每个分片上报的MD5分片阶段加哈希校验并重传某个分片反复上传失败该分片上传接口超时查看服务器日志是否有503/504增大超时时间并走指数退避重试秒传判定失败文件哈希计算方式不一致核对前后端哈希算法是否一致二进制/文本模式区别统一算法用二进制流计算前端进度条突然回退本地存储的进度记录被清理检查浏览器是否有存储限制改用IndexedDB存储分片列表重复上传同一分片重试机制没做幂等服务端收到重复分片时是否覆盖或报错设计幂等接口同一序号分片重复上传返回已存在这里有一个我特别想强调的细节接口要做到幂等。什么叫幂等就是同一个操作执行多少次结果都一样。比如前端因为网络超时以为自己的分片没传成功于是重传了一遍。如果服务端不检查就直接再次写入可能导致磁盘上出现两个同名分片文件合并时就乱了。正确的做法是每次上传分片前先查询“此分片是否已存在”如果已存在就直接返回成功不需要重新传输。为此服务端接口设计里必须有一个用于查询已完成分片列表的接口这是整个断点续传系统最容易被忽略但最关键的一个接口。5.2 服务器合并失败与磁盘爆满合并失败的场景往往发生在高负载环境下。当初我遇到过一个典型问题同一个用户上传一个大文件分片都没问题但合并的时候报“ENOSPC: no space left on device”磁盘满了。为什么因为临时目录里不仅有当前这个文件的全部分片还有一大堆其他用户的半成品。磁盘空间被这些临时文件塞满了。排查方法很简单用du -sh /tmp/*看看哪些目录占空间。解决方案是在业务上定期清理超过24小时未完成上传的临时目录同时在上传开始时先用服务端接口检查磁盘剩余空间空间不足直接拒绝发起新上传别让用户白传几百MB分片然后合并失败。另外一个容易踩的坑是合并时的IO阻塞。当你用流式写入合并大文件时如果同时有大量用户在上传磁盘IO会被完全占满导致合并速度特别慢、甚至超时中断。我的经验是合并这个动作不要在用户请求的上下文里同步做而是拆分到后台任务队列。前端最后传一个“完成上传”的HTTP请求服务端只负责确认并把这个任务丢进队列合并完成后再通过轮询或者WebSocket通知前端。这样用户体验更好也避免请求超时造成“其实服务端已经在合并了但前端以为失败了”的竞态问题。5.3 网络波动与重试策略断点续传系统的成败很多时候不取决于分片逻辑而取决于你对网络波动的容忍能力设计。我试过很多种重试策略最后留下的最稳定的组合是这三条连接超时设置单个分片请求的超时时间设置为30到60秒不要设成2分钟以上。为什么因为网络长时间无响应基本可以判定链路已死你再等下去也是浪费时间。指数退避与抖动jitter第n次重试前等待的时间是base * 2^n再加一点随机抖动避免多个客户端在同一时刻集体重试打爆服务器。我的base是1秒最大上限30秒。整体传输暂停机制如果连续失败的分片数量达到某个阈值比如10个应该停止整个上传任务提示用户检查网络。不要再继续硬试因为这种连片失败的场景通常是断网级别的继续重试只会浪费资源和电量。这里还有一个网络诊断的小技巧断点续传系统里应当记录每次分片请求的耗时、重试次数、HTTP状态码。把这些数据可视化出来你能很直观地看到网络质量在时间维度上是如何变化的。有一个阶段的请求几乎全部集中在超时和重试那大概率是那段时间内用户网络整体不稳定跟你的代码没太大关系。5.4 一个实战案例浏览器2GB视频上传的断点续传设计最后分享一个完整的实战案例方便你把上面的内容串起来。项目背景是一个教育培训平台用户需要上传2GB以上的课程视频。原始方案是完整上传走公网几乎必断后来我重构为断点续传架构。前端部分的流程是这样的用户选择文件后先计算文件的SHA-1哈希用Web Worker异步计算避免卡死主线程调服务端/upload/info接口传入哈希服务端返回该上传会话是否已存在、已有分片列表、分片大小建议前端根据返回结果跳过已上传分片只处理剩余部分分片大小设为10MB并发数取4每个分片独立上传上传完成后更新本地的IndexedDB记录所有分片完成后调/upload/merge接口触发服务端合并前端轮询/upload/status接口等待合并结果和整体哈希校验结果。服务端部分收到分片时先存到临时目录文件名采用哈希-分片序号的格式同时记录分片的MD5查询分片状态接口直接扫描临时目录返回已存在分片的序号集合合并后台化用异步任务处理避免超时合并完成后删除临时目录文件释放空间。上线以后的效果很明显2GB的视频在普通家庭宽带上原本成功率不到三成重构后成功率提升到95%以上剩下的5%基本是用户主动断网或者电脑关机。因为任何一次网络中断只需要在恢复之后重新点击上传系统会自动续传用户感知不到之前付出的时间和带宽白白浪费了。在整个设计和实施过程中我个人最深刻的体会是断点续传这个功能本身并不难难的是一次性把“状态管理”设计对。如果一开始就把上传会话、分片状态、合并状态这些核心概念抽象清楚接口设计成幂等的前后端的进度记录方式保持一致后面基本不会出大问题。反过来如果你把断点续传当作一个锦上添花的“加分项”回头再往一个已经写死的上传流程上去补那真的会越补越乱。给还没入坑的同学一个建议当你准备做一个上传系统时先把断点续传设计进架构里而不是等被用户骂了再回来加。这个习惯能让你少熬很多夜。