基于WebUploader改造的大文件断点续传方案：从分片原理到实践

原先项目里用的上传模块是一次性提交整个文件，到了卫星视频这种动辄几个GB、十几个GB的大附件场景，问题立马暴露：网络稍微抖一下，进度条归零重来，传了半小时等于白传。领导盯着进度看还好，要是赶上网络质量差的内网环境，光传一个文件就能把人耗崩溃。

我当时的第一反应是赶紧选一款现成的断点续传组件顶上，试了一圈下来发现：plupload停更太久，vue-uploader又绑定框架，反而是百度开源的WebUploader虽然也谈不上活跃维护，但它那套分片、并发、MD5指纹、断点续传的骨架设计是真的扎实，非常适合在此基础上做深度改造。这个选择在军工行业场景里尤其重要——你不能指望所有浏览器都是最新版Chromium，更不能接受上传到一半任务挂掉、数据全部作废。把WebUploader改造成一个跨浏览器、支持超大附件分片断点续传的上传插件，就成了当时技术方案里最靠谱的一条路。

下面把整个改造过程、踩过的坑和值得参考的设计思路都摊开来说，希望能给同样跟大文件上传死磕的朋友一些实际帮助。

1. 为什么盯上了WebUploader：选型背后的技术账

1.1 从业务痛点到技术选型

先交代一下业务背景，别怕啰嗦，这决定了后面所有技术决策的方向。卫星视频这类文件有几个非常头疼的特征：体积大、时长长、来源单一。一个未压缩或轻度压缩的视频，轻轻松松突破10GB；这类文件的产生频率不高，但一旦需要上传，往往是任务式的、必须完整到达的。换句话说，业务上对"传不完就重来"是完全不可接受的。

军工行业还有个特殊背景——用户环境是典型的内网专网，网络出口带宽有限，且链路稳定性做不到公网那么理想。叠加一些安全设备的过滤，TCP长连接动不动就会被切掉。传统的HTTP表单上传在这种场景下基本废掉：要么请求超时，要么进度条卡死，要么传完服务端发现文件还不完整。

我当时列了三条硬性选型标准：

• 必须支持分片上传与断点续传，单次网络异常不能导致全部重新上传；
• 必须跨浏览器，覆盖用户环境里可能存在的各种WebKit、Trident甚至双核浏览器；
• 必须在纯前端的约束下实现（部分分保环境不允许轻易引入过多依赖），且上传过程可监控、可回溯。

对照这三条，再去看市面上的组件：原生XMLHttpRequest要自己手搓分片逻辑和维护续传状态，工程量极大；axios这类HTTP库只管发请求，不管文件切片和断点；plupload本身是个不错的备选，但它的Runtime体系偏重，且对HTML5之外的回退支持做得不够细。WebUploader的最大优势是它把"文件选取→MD5计算→分片→并发上传→失败重试→续传"整条链路都内置好了，对外暴露的API又足够底层，你可以在不破坏它的核心骨架的前提下，替换掉一些关键环节，定制成自己想要的样子。

1.2 WebUploader的核心能力拆解

WebUploader并不是一个简单封装文件上传的库，它内部有一套完整的分层架构：最上层是面向业务开发者的Uploader实例，中间是Runtime（运行时）抽象层，底层则针对不同浏览器环境提供不同的实现。

在HTML5环境里，它通过File API拿到文件对象，然后用File.prototype.slice把文件切成指定大小的Blob分片，每片单独发起XHR上传。在旧版IE环境里，它还可以回退到Flash或者iframe方案。对改造者来说，最有价值的一点就是：它把"切片"和"上传"这两个环节抽象成了可插拔的机制，你可以把某个自定义Runtime挂上去，也可以重写它的分片策略，而不需要动整个上传业务逻辑。

此外，WebUploader集成了一个很实用的细节：支持对文件计算MD5哈希。这个哈希值有两个用途，一是作为文件唯一标识，二是用于秒传和续传的比对依据。在超大文件场景下，如果不用MD5做标识，服务端就没法判断"你这次上传的分片和上次拍脑袋传的分片是不是同一个文件"，断点续传也就无从谈起。

1.3 为什么不直接手写原生上传

可能有人会问，既然WebUploader也要改造，为什么不干脆从零手写一套？这里有一个看不见的成本：断点续传涉及的状态机远比看起来复杂，包括文件排队、分片状态记录、网络错误重试、并发控制、上传进度聚合、错误分类处理等。手写一套，光是把这些状态关系理清楚，再加上真机测试，至少要多花两三倍的时间。

而且，WebUploader在社区里沉淀了很多年，尽管官方维护频率低，但它踩过的边界条件（例如各种浏览器对File.slice实现不一致、跨域上传时如何携带认证信息等）都已经处理过。站在巨人的肩膀上做定向改造，比从零开始写更可控，和团队领导汇报技术方案时也更有说服力。

2. 军工场景下卫星视频传输的特殊约束

2.1 文件体量：超大附件的真实量级

先说文件大小。普通办公场景里的"大附件"可能也就几十MB，但卫星视频不是这个概念。我遇到的实际案例里，最少的单个文件也有1.5GB左右，多的可以到20GB以上。文件一大，很多平时觉得无所谓的问题都会被放大：

• 一次性读取整个文件会直接撑爆浏览器内存；
• 单个HTTP请求传输超时后，需要整文件重传；
• 极端情况下，浏览器标签页直接崩溃；
• 如果服务端对上传请求体大小有硬限制，超大单文件请求会被直接拒绝。

所以在设计分片策略时，分片大小必须和文件总量互相匹配。后面讲性能优化时会专门展开，这里先记住一点：超大文件绝不能用默认的2MB分片，更不能用一个请求怼到底。

2.2 网络环境的现实限制

军工行业很多场景跑在专网或内网上。这类网络有一个特点：带宽不算小，但稳定性充满不确定性。安全审计设备、防火墙、代理网关都可能在传输过程中介入，导致连接重置。另外，内网里的DNS解析、反向代理配置、证书信任链也可能和公网环境完全不同。

这意味着上传组件必须具备极强的容错能力——单个分片失败绝不等于整个上传任务失败，失败后要自动重试，重试无果要准确记录断点位置，等网络恢复后继续。

2.3 跨浏览器兼容的硬性要求

不少军工业务系统跑在国产化终端上，浏览器可能是奇安信、360安全浏览器、红莲花这些双核浏览器，内核版本也参差不齐，有的偏老的WebKit内核连File.slice的参数都认不全。与此同时，部分办公区还残存着Windows 7 + 老版本Chrome甚至IE11的组合。

在这种环境矩阵下，"跨浏览器"不是一句轻飘飘的营销词，而是要正儿八经解决三个层面的问题：

• HTML5 File API在不同内核里的实现差异；
• 老内核不支持的一些ES6语法、DOM API；
• Flash禁用后在旧内核上的降级策略。

WebUploader自带的Runtime抽象层正好是对抗这种碎片化的利器。我们把HTML5 Runtime做深，同时针对极旧的Trident内核场景才考虑Flash回退，确保各环境都能跑起来，只是能力级别不同。

3. WebUploader断点续传的内部原理，你得先摸清这几件事

3.1 分片上传的完整流程

先把WebUploader默认的分片上传流程捋清楚，这决定了我们改造的切入点。

当用户选择一个文件后，组件内部大致经历以下状态流转：

文件选择 → 初始化MD5计算 → 计算完成后统计总分片数 → 提交文件元信息 → 开始并发上传分片 → 每个分片独立回调 → 全部分片完成后触发合并通知

实际到代码层面，核心操作是uploader.upload()和uploader.upload()内部对每个chunk的遍历。每个chunk会走request方法，发送一个携带chunk、chunks和文件唯一标识的multipart请求。服务端收到后，把分片文件暂存，等所有分片到齐后再按顺序合并成完整文件。

3.2 断点如何被"记住"：MD5指纹与分片状态

断点续传的核心，是让服务端能回答两个问题：这个文件以前传过没有？传过的话已经收到哪些分片了？

WebUploader默认在分片上传前计算整个文件的MD5值。这个值在整个生命周期里就是文件的身份证。前端把MD5和服务端已知的分片序号做对比，就能跳过已经传过的分片，从断点位置继续。服务端不需要额外存储一个复杂的任务表，只需要维护"文件指纹 → 已上传分片集合"的映射关系即可。

我改造时把MD5计算挪到了Web Worker里，避免超大文件计算MD5时阻塞UI线程。实测一个10GB文件在不限速的情况下，计算MD5耗时约半分钟到一分钟，这个等待是值得的，因为如果跳过了这一步，后续每次传输失败都不知道该从哪儿续起。

3.3 续传与秒传背后的服务端协议设计

前端的断点续传离不开服务端的配合。这里需要约定一套简单的接口协议，大致如下：

预检测接口放在正式上传之前调用。如果文件MD5在服务端已存在且分片完整，直接触发秒传；如果只有部分分片存在，前端就只传缺失的那部分。这其实是"断点续传"与"秒传"共用一套机制，逻辑上是同一件事。

服务端合并分片时要注意：按chunk序号顺序合并，不能依赖上传完成的先后顺序。我们曾踩过一个坑——并发上传下第5片比第3片先到达，服务端如果顺序处理就会把文件内容拼错。后来要求前端每个分片请求都要携带chunk序号，服务端必须在全部就绪后按序号拼接，并且最后校验整文件MD5是否与预检测一致。

4. 核心改造：让WebUploader在跨浏览器环境里真正跑起来

4.1 浏览器内核适配：从IE到Chromium

我上来就干的第一件事，是确认当前目标环境里到底有哪些浏览器。在这类行业项目里，最忌讳的就是默认用户都用Chrome最新版。我列了一张环境矩阵，包括浏览器类型、内核版本、支持的File API级别，然后针对每种环境写兼容策略。

WebUploader的Runtime机制在这里帮了大忙。它本身会检测当前环境支持HTML5还是Flash，自动选择合适的Runtime。我的改造思路是：默认强制走HTML5 Runtime，毕竟Flash已经接近淘汰；但对于一些连FileReader都不全的老内核，要能回退到Flash或给出明确的提示。

核心代码段可以这样重写Runtime的注册逻辑：

// 自定义HTML5 Runtime，用于覆盖WebUploader在老旧WebKit内核里的兼容性 Uploader.register({ 'before-send-file': 'overrideBeforeSendFile', 'before-send': 'overrideBeforeSend', 'after-send-file': 'overrideAfterSendFile' }, { overrideBeforeSendFile: function (file) { // 在发送文件元信息前，附加自定义参数 file.md5 = this.options.md5Value; // 全局计算好的文件指纹 return true; }, overrideBeforeSend: function (chunk) { // 分片发送前可拦截、可重试 chunk.params = chunk.params || {}; chunk.params.taskId = this.options.taskId; return true; }, overrideAfterSendFile: function (file) { // 全部片传完后，通知服务端合并 return this.request('mergeFile', { md5: file.md5, fileName: file.name }); } });

这里有一个容易被忽略的细节：老版本WebUploader对File.slice的兼容写法是把它转成file.source.slice，因为部分浏览器对File.prototype.slice的支持不完整。改造时务必对slice做一层兼容封装。

4.2 自定义分片逻辑替换默认行为

WebUploader默认的chunkSize是2MB，这个大小在几百MB的文件场景下没问题，但面对10GB以上的卫星视频，会产生大约5000多个分片，这会带来两个副作用：

• 请求数量过多，网络往返时间累加明显；
• 服务端需要维护的分片文件数量过多，影响合并性能。

我在改造中把chunkSize调整到了10MB，甚至20MB。同时，由于卫星视频文件通常很大，分片大小应该根据文件大小动态调整，而不是固定值。我做了一个简单的分段策略：

并发数和分片大小之间是跷跷板关系：分片越大，服务端合并越快，但单分片传输时间越长，失败重试的代价越大；并发数越大，带宽利用率越高，但对服务端压力和内存占用也越大。浏览器对同一域名的并发连接数本身有限制，太大反而导致排队。

我还在改造中重写了文件切片的逻辑，让切片后的Blob不再持有对原始大文件的整体引用，避免内存泄漏。这是超大文件上传最容易忽略的一个点。

4.3 断点续传的状态管理与恢复

断点续传在实现上有两种层级：一种是页面不刷新、网络闪断情况下的自动重试；另一种是页面关闭、浏览器重启后还能从上次进度继续。WebUploader默认只处理前者，后者需要前端把上传状态持久化到localStorage或IndexedDB。

我在改造中把上传状态管理单独拎出来，做了一个UploadTaskStore模块，它保存的核心信息包括：

• 文件MD5；
• 已成功上传的分片序号集合；
• 文件名、文件大小、分片大小；
• 最近一次活跃时间。

页面重新加载后，扫描这个任务表，对每个未完成任务调用预检测接口，把已上传的分片对比出来，然后从断点继续。

class UploadTaskStore { saveTask(task) { const key = `upload_task_${task.md5}`; localStorage.setItem(key, JSON.stringify(task)); } getTask(md5) { const key = `upload_task_${md5}`; const raw = localStorage.getItem(key); return raw ? JSON.parse(raw) : null; } removeTask(md5) { const key = `upload_task_${md5}`; localStorage.removeItem(key); } }

插一句，localStorage的存储空间通常是5MB左右，如果任务状态数据本身很大（比如几千个分片序号），可以改用IndexedDB。实测下来，5000多个分片序号用localStorage存会有超限风险，所以最终改用了IndexedDB。

4.4 跨域与认证信息携带

内网系统经常通过Nginx反向代理暴露服务，前后端可能不在同一个域名下。这会导致上传请求触发CORS预检（OPTIONS），如果服务端没有正确处理，就会出现"跨域访问被拒绝，请检查浏览器配置"这样的报错。这个报错字符串在行业里相当常见，基本都是CORS配置缺失导致的。

对策分两步。前端在WebUploader的request方法里加上withCredentials或自定义头；服务端在响应里加上对应的CORS头：

uploader.option('server', UPLOAD_SERVER_URL); uploader.option('withCredentials', true); // 携带Cookie或Token // 服务端Nginx或网关需配置 // Access-Control-Allow-Origin 与前端域名一致 // Access-Control-Allow-Headers: Content-Type, X-Requested-With // Access-Control-Allow-Methods: POST, OPTIONS

一个容易踩的坑是：WebUploader在发送multipart请求时，默认会带上一些内部参数（如chunk、chunks等），自定义请求头要确保放在允许列表里，否则预检阶段就过不了。

5. 卫星视频超大附件的性能优化

5.1 分片大小与并发数的最优配置

我在正式环境里做过一组对照测试，结论是：分片大小和并发数的最优组合取决于服务端的处理能力和网络带宽，而不是越大越好。

测试环境带宽约100Mbps，服务端为普通SSD服务器。测试结果如下：

最终我选择了10MB分片、并发2的组合，在稳定性和速度之间取得了平衡。如果是走卫星链路或者网络抖动频繁，建议进一步降低并发数到1，换取更高的可靠性。

5.2 内存管理：读大文件的常见坑

超大文件上传时，最常见的内存问题出现在两个地方：一是MD5计算时把整个文件塞进内存；二是创建Blob切片时由于闭包引用导致整文件无法被回收。

第一个问题的解法是分块读取。计算MD5时，并不是一次性读取整个文件，而是每次读取一个固定大小的分块（例如16MB），更新哈希上下文后释放该分块。

// 以标准Web Crypto API为例，示意分块读取计算摘要 async function calculateFileHash(file) { const chunkSize = 16 * 1024 * 1024; const buffer = await file.arrayBuffer(); const hashBuffer = await crypto.subtle.digest('SHA-256', buffer); // 真实场景应循环读取，而非一次加载整个文件 return Array.from(new Uint8Array(hashBuffer)) .map(b => b.toString(16).padStart(2, '0')) .join(''); }

第二个问题的解法是避免在切片循环中形成对大文件对象的长期引用。每次切片后，把Blob对象交由上传队列处理，处理完即置空。

5.3 进度反馈与用户体验

超大文件传输动辄几十分钟，用户盯着干巴巴的进度条非常难熬。我在插件里做了三件事提升体验：

• 显示总进度、当前分片进度、已上传大小、实时速度、预计剩余时间；
• 网络中断时，不立刻报错，而是进入重试等待状态，倒计时结束后自动重连；
• 允许用户暂停和继续，暂停后保留现场，继续时从断点恢复。

这些功能WebUploader原生API基本都有对应事件，比如progress、uploadProgress、error、uploadComplete，只需要在事件回调里做数据处理和界面渲染。

6. 实测环境中的问题排查与避坑记录

6.1 内存溢出的排查过程

第一次拿真实卫星视频文件（12GB左右）测试时，浏览器标签页在点击上传后约1分钟就崩溃了。控制台报的是ArrayBuffer allocation failed。

排查链路分三步走：

第一步，先确认是不是MD5计算导致的。禁用MD5计算后，上传能正常启动，但进度到约30%时仍然崩溃。说明MD5不是唯一原因，但确实占了很大一块内存。

第二步，排查分片Blob的内存引用。在Chrome DevTools的Memory面板里抓了Heap Snapshot，发现大量Blob对象未被回收，根因是上传队列里持有已完成Blob的引用，导致无法GC。

第三步，针对源码做修改：每个分片上传完成，立即从队列中移除该chunk对象，并手动置空其_blob字段；同时把MD5计算改为Web Worker内部分块处理，避免主线程承担大对象拷贝。

改完后再跑12GB文件，内存曲线平稳，从最高的约1.8GB降到约600MB。

6.2 分片合并后文件损坏的根因

这个坑最隐蔽。断点续传测试中，文件能传完，进度也显示100%，但打开视频发现画面在某个时间点卡死，或者干脆打不开。

起初以为是合并工具的锅，后来一步步排查，发现根因在服务端的合并逻辑。我们最初用"先到先拼"的策略，哪个分片先上传完就先写入最终文件的对应位置。但前端并发上传时，chunk序号和到达服务端的顺序不一致，导致拼接错位。

解决方案是：服务端不要边收边拼，而是先按chunk序号暂存每个分片文件，全部到齐后再按序号顺序流式合并写入最终文件。合并完成后，再对整个文件做一次MD5校验。如果前端提交的MD5和合并后的MD5不一致，直接判定上传失败并清理临时分片。

6.3 老内核浏览器上Object.assign未定义

目标环境里有一批老版本Chromium内核的国产浏览器，控制台报错Object.assign is not a function。这是因为WebUploader源码某些分支用了ES6方法，而组件本身在发布时没有做完整转译。

处理方式是在页面入口统一加载一套兼容垫片（polyfill），同时把改造后的代码用Babel转译成ES5后再打包。这个措施看起来不起眼，但在跨浏览器项目里能省掉后期大半的兼容性反馈。

另一个老内核常见问题是FileReader.readAsArrayBuffer不存在，只有readAsBinaryString。针对这种情况，我在计算MD5时做了分支处理：能走ArrayBuffer就走，不能走就降级。

7. 从插件到工程化：上线前后的安全与运维思考

7.1 服务端校验与数据完整性

军工行业对数据完整性要求高，仅仅靠前端上报MD5不够，服务端必须独立校验。我的做法是：

• 预检测阶段，前端上报文件名、大小、MD5；
• 服务端记录这些元数据，并分配一个上传任务ID；
• 每个分片上传时，服务端记录该分片的大小，并在全部接收后按序号合并；
• 合并完成后，服务端计算整体文件的MD5，与上传前记录的MD5比对；
• 比对通过，才将临时文件移动到正式存储区；比对失败，清理所有临时分片。

这样即使前端代码被篡改（理论上内网系统有应用白名单，但还是要防），服务端也能兜底识别出损坏文件。

7.2 权限控制与操作审计

军工行业系统普遍有等保合规要求，上传操作必须有审计记录。我在上传插件的外围加了一层统一的鉴权逻辑：所有上传接口都要求携带有效的会话令牌，服务端校验通过后才接受分片数据。同时，每次上传的发起人、文件指纹、文件大小、上传起止时间、最终落盘位置都会记录到审计日志表。

这里有一个细节：会话令牌过期时，正在上传的分片该如何处理？我们的方案是，预检测接口返回令牌剩余有效时间，如果预计上传时长会超过令牌过期时间，则在前端主动刷新令牌后再继续传输。避免传了90%因为令牌过期全部失败。

7.3 后续扩展思路

把WebUploader改造稳定之后，后续还可以做几件提升体验的事情：

• 接入对象存储服务（如MinIO、Ceph等），让分片直接上传到对象存储，减轻应用服务器的带宽压力；
• 增加上传任务的可视化管理界面，让运维人员能看到全局的传输任务列表、当前利用率、失败原因统计；
• 把MD5计算升级为xxHash等更快的哈希算法，虽然MD5碰撞概率极低，但性能提升是实打实的。

我个人在实际项目中的体会是，上传组件这种"看起来不起眼、崩起来要人命"的基础能力，值得投入时间把底层原理吃透。WebUploader的源码虽然有些年头了，但它的架构思想放到今天依然有借鉴价值——分片、指纹、状态恢复这些概念，在任何一个现代上传组件里都是地基。军工行业也好，其他高可靠性场景也好，只要你对稳定性、跨浏览器兼容、大文件传输有要求，这套改造方案的大方向都不会变。如果按照这个思路动手改，遇到具体问题卡住了，欢迎来聊实际的踩坑细节。