这几十年里我经手过很多文件上传类的项目但真正让我觉得上传组件这东西不能拿来就用的是那次军工行业的卫星视频接入任务。客户环境是涉密内网数据不能出域终端五花八门单个视频文件动辄十几GB偶尔还有几十GB的主战装备试验记录。最开始拿原生WebUploader直接上传一半网络抖动整个上传任务报废只能从头再来。那种挫败感相信做过大文件传输的人都懂。后来我基于WebUploader做了一整套改造核心就是把分片上传和断点续传真正打通适配国产化终端和各类浏览器最后封装成独立插件业务系统接入成本极低。这篇文章就把整个改造过程、踩过的坑、还有前后端联调时容易忽略的细节一次说清楚。如果你也在做超大附件上传尤其是政企内网、卫星遥感数据、视频监控录像这类对完整性和稳定性要求极高的场景这套方案可以直接参考。1. 军工卫星视频上传的真实痛点为什么现成组件接不住先说需求。卫星视频和普通文件不一样它的单文件体量大、编码格式特殊、对完整性要求极高。一个小时的卫星视频码率稍高一点就是几个GB起步长周期的遥感影像拼接视频甚至能到上百GB。这种文件在公网上传都费劲放到带宽受限、还经常有网络波动的涉密内网里难度直接翻倍。我踩的第一个坑是把WebUploader原版配置完就丢给测试了。当时想着WebUploader本身支持分片上传应该能扛住。结果测试环境模拟了一次断网网页一刷新上传记录全部丢失文件又从0%开始。业务方直接急了——几十GB的文件传一次要好几个小时断一次就全白费这活儿根本没法干。1.1 需求拆解不是一个上传组件是一套可靠传输方案把这个需求拆开看真实要解决的问题有这么几层超大文件必须分片不能整文件上传。服务端和浏览器都有内存限制整传必挂。断点续传网络中断、浏览器崩溃、电脑重启后上传任务能从中断位置继续而不是从头再来。跨浏览器军工内网终端环境复杂Chrome、Firefox、旧版Edge、国产化信创浏览器基于Chromium内核的麒麟、UOS等都要能跑。完整性校验卫星视频传完后必须确认每一个分片都正确、合并后的文件没有损坏。视频文件一旦数据损坏后期解译分析就全废了。涉密安全全程在内网环境运行不能依赖任何外部服务所有逻辑必须可控可审计。这些需求叠加在一起直接套现成组件是不够的。WebUploader本身只是个上传库它给了你分片、并发的壳子但断点续传的服务端配合、文件指纹校验、失败重试策略、国产化浏览器兼容都要自己补齐。1.2 为什么坚持在WebUploader基础上改而不是重写你可能觉得WebUploader官方都停止维护好几年了为什么不干脆用Resumable.js或者自研一套我做这个判断的时候其实有现实的考量。军工项目的技术选型有一条潜规则优先用经过验证的技术而不是最新的技术。WebUploader虽然是老东西但它的分片机制、上传队列、UI组件都是现成的项目团队对它也熟悉维护成本低。而自研一套上传内核从文件切片、并发控制、进度计算到失败重试没有一两个月打磨不出一版稳定的还不算测试成本。再一个WebUploader的架构其实很清晰上传逻辑和UI逻辑是解耦的。我完全可以用它的Uploader实例管理文件队列把底层的分片读取、MD5计算、续传逻辑替换成自己写的。这样业务系统接入时前端调用方式基本不变改动面控制到最小。这是典型的换心脏不换外壳思路。骨架保留但核心的传输策略、校验机制全部重写。2. WebUploader原版的边界哪些能力能用哪些必须替换既然决定在WebUploader基础上改造第一步就是摸清它的家底。我梳理了原版组件的核心能力边界这里直接给结论。2.1 原版能做什么HTML5 Flash双内核适配老版本依赖Flash做降级不过Flash已死现在基本只走HTML5路线。分片上传通过chunked: true开启支持配置分片大小chunkSize。并发控制threads属性控制同时上传的分片数。MD5计算内置了SparkMD5的封装可以算文件MD5实现秒传逻辑。上传队列文件选择后进队列有进度、成功、失败等事件。这些能力在普通文件上传场景下够用但放到几十GB的卫星视频面前就有几个致命短板。2.2 原版的三大致命短板短板一MD5计算方式在超大文件场景下不可用。WebUploader的MD5计算是一次性加载整个文件来算的。一个30GB的视频文件加载进内存直接浏览器崩溃就算内存扛得住算完MD5也得几十分钟。这期间UI完全卡死用户根本没法操作。所以原版秒传机制在超大文件面前是个摆设必须换成增量计算或者抽样指纹方案。短板二断点续传依赖服务端而且续传标识不可靠。WebUploader的续传思路是上传前计算文件MD5传给服务端查重服务端返回已上传的分片信息。这个思路本身没错但MD5计算问题没解决续传就无从谈起。另外文件的唯一标识如果只用文件名同名文件会在很多业务场景下互相覆盖需要外加文件大小、修改时间等维度。短板三对超大文件的内存管理有缺陷。原版在上传过程中会持有队列里每个文件的引用分片数据也常驻内存。传几十个分片可能没事但传几百个分片时浏览器的内存占用会一路飙升到最后直接白屏。这就是典型的能跑demo扛不住生产。2.3 改造范围界定我在动手前画了一条明确的边界线保留WebUploader的UI组件、文件队列管理、上传进度事件、文件选择逻辑。这些是成熟稳定的重写它们纯属浪费时间。替换文件MD5计算逻辑改增量抽样、分片上传前的断点查询逻辑、分片失败后的重试策略、内存释放机制。新增分片大小的动态调整策略、和服务端的check/merge接口约定、断点信息在浏览器本地持久化存储。这条边界线很重要。没有边界地乱改会让组件变得不可维护边界划得太小又解决不了真正的痛点。按这个范围改造大概一个月就能出一版能进内网测试的插件。3. 分片策略与文件指纹超大文件先算全量MD5是想不开这一章是整个改造的核心也是我耗费最多时间反复调优的部分。分片策略和文件指纹算法直接决定了上传的稳定性和续传的可靠性。3.1 分片大小不能固定必须按文件体量动态调WebUploader默认的chunkSize是2MB小文件没问题但放在30GB的视频文件上会产生上万个分片。分片数量一多服务端要为每个分片创建临时文件、记录写入状态前端也要处理海量的进度事件效率和稳定性双输。我按文件大小做了分片动态策略规则很简单文件大小分片大小预估分片数 2GB2MB≤ 10242GB ~ 10GB10MB200 ~ 100010GB ~ 50GB20MB500 ~ 2500 50GB50MB按实际体量这里有一个权衡逻辑。分片越大分片数量越少服务端临时文件管理和前端进度事件压力越小但单分片失败后重试的代价也越大。我实测下来50MB分片在内网千兆环境下传输很稳重试成本完全可接受。如果是公网环境建议分片控制在10MB以内因为公网丢包率高大分片失败概率显著上升。实现上我在初始化WebUploader之前根据文件大小动态计算分片配置function calcChunkConfig(fileSize) { let chunkSize 2 * 1024 * 1024; // 默认2MB if (fileSize 10 * 1024 * 1024 * 1024) { chunkSize 50 * 1024 * 1024; } else if (fileSize 2 * 1024 * 1024 * 1024) { chunkSize 20 * 1024 * 1024; } else if (fileSize 500 * 1024 * 1024) { chunkSize 10 * 1024 * 1024; } return { chunked: true, chunkSize: chunkSize, threads: 3 }; }threads并发数我也固定推荐3。原版默认是3实际上这个值在内外网环境都算均衡。并发太高会占满内网带宽影响其他业务系统太低则无法充分利用带宽。3.2 文件唯一标识放弃全量MD5改用组合指纹文件唯一标识是断点续传的基础服务端要凭它识别这是同一个文件。原版方案是全量计算文件MD5这在超大文件场景下行不通。我采用的方案是组合指纹文件大小 文件名 最后修改时间 抽样分片MD5这个思路的核心是用元数据信息快速锁定候选文件再用少量抽样分片的MD5做二次校验。比如取文件的第一个分片、中间一个分片和最后一个分片分别计算MD5拼到一起。这样算一个几十GB文件的指纹耗时只在毫秒级因为最多只读取几个分片的数据量。async function generateFileFingerprint(file, chunkSize) { const sampleCount 3; // 抽样3个分片 const totalChunks Math.ceil(file.size / chunkSize); const sampleIndexes [0, Math.floor(totalChunks / 2), totalChunks - 1 ]; const sampleMd5s []; const md5 new SparkMD5.ArrayBuffer(); for (const index of sampleIndexes) { const blob file.slice(index * chunkSize, (index 1) * chunkSize); const buffer await blob.arrayBuffer(); md5.append(buffer); } const sampleHash md5.end(); return ${file.size}-${file.name}-${file.lastModified}-${sampleHash}; }这里有个细节为什么不像原版一样直接对整个文件做MD5除了性能原因还有一个可靠性考虑。全量MD5要等整个文件读完才能生成而在断点续传场景中我们希望在用户选择文件后、开始上传前就立刻查询续传信息。抽样指纹可以在几百毫秒内完成用户几乎无感知。当然抽样指纹的碰撞概率比全量MD5高但对于断点续传这个用途足够了——就算指纹碰撞导致误判最多是让一个分片被错误跳过最终合并时我们还有全量校验兜底。3.3 传输后的完整性校验全量MD5后置很多人会忽略这一点分片上传完成后怎么确认整个文件没损坏我的方案是在服务端合并完所有分片之后再异步计算合并文件的MD5并和前端计算的全量文件MD5做比对全量MD5可以在上传后台线程计算不阻塞主流程。如果一致标记文件上传成功不一致触发重新上传整个文件。这个校验后置的方案既避开了上传前计算全量MD5的性能问题又保证了卫星视频这类对完整性要求极高的文件的传输质量。4. 断点续传实现前后端联动的完整链路断点续传不是前端单独能完成的事情它需要前端和服务端形成一套完整的协议。这一章我把完整的链路拆开讲。4.1 前后端接口约定我设计了三组接口分工非常明确查询接口POST /api/upload/check前端上传前调用传入文件指纹服务端返回该文件的md5、已上传分片序号列表。分片上传接口POST /api/upload/chunk前端逐个上传分片分片和文件信息放在表单里。合并接口POST /api/upload/merge所有分片上传完成后调用服务端按分片序号合并临时文件。接口入参我用的是分片序号chunkIndex而不是字节范围byteRange。分片序号更直观也更容易做数据去重。但分片大小如果中途调整过字节范围会错位所以分片大小在文件指纹里就固定下来前端和服务端共用同一套配置。4.2 前端的关键逻辑查已传、跳分片、续传每次选择文件后前端生成文件指纹然后调用check接口查询已传分片。服务端返回类似这样的数据{ code: 0, data: { fileId: abc123, uploadedChunks: [0, 1, 2, 5, 6, 9], md5: } }前端拿到uploadedChunks列表后在初始化上传队列时直接把已传的分片从待上传列表中剔除。WebUploader默认不支持跳过指定分片我改造时是监听uploadStart事件在分片开始前判断uploader.on(uploadStart, function(file) { const chunkList uploader.getChunks(file); chunkList.forEach(function(chunk, index) { if (uploadedChunks.includes(index)) { // 标记该分片已完成跳过上传 uploader.skipChunk(file, index); } }); });这里有一个容易被忽略的问题如果不做任何处理用户不知道哪些分片已经被跳过进度条会从0%重新开始。我在插件里做了叠加处理——把已传分片的字节数直接加到初始进度上用户刷新后看到的是已上传62%剩余38%继续体验上就顺畅很多。4.3 服务端合并的实现要点服务端合并逻辑是整个续传的收官环节。我见过不少项目在合并阶段出问题核心原因就是分片落盘顺序和合并顺序不一致。我的方案是每个分片上传时以{fileId}_{chunkIndex}.part命名落盘到临时目录。合并时按chunkIndex升序遍历所有分片文件用文件流追加写入最终文件。合并完成后校验文件大小是否等于所有分片大小之和再异步计算MD5。// Java服务端伪代码 public boolean mergeChunks(String fileId, String fileName, long totalSize) { File tmpDir new File(uploadTmpPath / fileId); File[] partFiles tmpDir.listFiles((dir, name) - name.matches(.*\\.part$)); Arrays.sort(partFiles, (a, b) - { int aIdx Integer.parseInt(a.getName().split(_)[1]); int bIdx Integer.parseInt(b.getName().split(_)[1]); return Integer.compare(aIdx, bIdx); }); try (FileOutputStream fos new FileOutputStream(finalPath / fileName)) { for (File part : partFiles) { Files.copy(part.toPath(), fos); part.delete(); } } // 合并完成后校验大小 File finalFile new File(finalPath / fileName); return finalFile.length() totalSize; }这个逻辑不算复杂但非常重要。分片上传是并发的服务端接收分片的顺序完全随机如果不按chunkIndex排序就合并视频文件必然损坏。4.4 断点状态在前端的持久化服务端已经能通过check接口返回已传分片列表那前端还需要持久化状态吗我建议在浏览器本地也存一份用IndexedDB不用localStorage——localStorage容量上限一般是5MB从几万个分片状态轻而易举就撑爆了。本地状态存什么文件指纹、当前分片进度、上传时间。这样即使用户在check服务端不可用的情况下比如内网临时故障也能在前端手动恢复大部分续传状态双保险。5. 跨浏览器与国产化终端适配兼容细节一箩筐跨浏览器这个词在公网项目里可能只是指Chrome和Safari但在军工内网里它是一个非常沉重的词。我列一下实际遇到的终端环境Windows 7/10上的Chrome 70、Firefox 68、旧版Edge以及基于Chromium的国产化信创浏览器麒麟、UOS。IE11在部分老机器上还存在但我们已经明确不重点支持只保证能选文件、能提示升级浏览器。5.1 Blob.slice的兼容陷阱WebUploader内部使用Blob.slice()方法切片这个API在几乎所有现代浏览器都支持。但在老版本Firefox上可能需要mozSlice老版本Chrome上可能是webkitSlice。我在改造时写了一个兼容函数const blobSlice File.prototype.slice || File.prototype.mozSlice || File.prototype.webkitSlice;这一行代码能救很多老终端。另外某些终端环境尤其是国产系统的浏览器对Blob.slice的边界处理有细微差异比如最后一个分片不足chunkSize时有些浏览器可能返回空切片。所以每个分片在读取后要判断一下实际字节数再决定是否上传。5.2 FileReader的性能与兼容读取分片数据时我用的是FileReader.readAsArrayBuffer这是最通用的方式。要注意readAsDataURL会把二进制数据转成Base64体积膨胀约33%上传流量白白多出三分之一在超大体量文件上必须避开。在国产化浏览器上FileReader对ArrayBuffer的内存管理有时会有问题我遇到过一个情况连续读取几十个50MB的ArrayBuffer浏览器内存只升不降最终崩溃。排查发现是浏览器内核没有及时回收FileReader的缓存。解决方法是显式将读取完的Buffer置为null并调用reader.abort()释放内部状态。5.3 分片状态存储localStorage不够用前面提到用IndexedDB存储前端续传状态这里展开讲一下。IndexedDB是异步API代码复杂度比localStorage高不少很多人嫌麻烦就直接用localStorage直到某天传10GB文件时发现localStorage被写满、所有状态丢失才追悔莫及。我用IndexedDB封装了一个非常轻量的存储模块只存状态对象的JSON序列化读写都是毫秒级。如果嫌IndexedDB操作麻烦也可以用idb-keyval这类不到1KB的小工具库它能帮我们规避兼容性坑。5.4 信创浏览器的专项验证国产化终端这块我的经验是基于Chromium内核的信创浏览器HTML5上传能力基本没问题但有两个坑需要提前做兼容一是版本号判定不可靠。很多信创浏览器把自己的UA伪装成Chrome但实际Chromium版本很老。我建议不要依赖UA做兼容判断而是直接做特性检测比如检测File.prototype.slice是否存在。二是大文件上传时浏览器可能出现假死。信创终端一般用的是国产CPU龙芯、飞腾、鲲鹏性能比主流x86差一截。在大文件的ArrayBuffer读取和MD5计算时建议用Web Worker在后台线程处理避免主线程卡顿。我对比过用Web Worker计算MD5一个大分片的计算时间从300ms降到10ms而且UI完全无卡顿。6. 实测踩坑记录军工内网环境下最隐蔽的五个问题这个章节不讲流程只讲真相。下面五个问题每一个我都真实遇到过每一个都能让看起来正常的上传任务在半夜突然失败。6.1 内存爆炸分片Blob引用不释放导致的浏览器崩溃现象上传10GB视频时浏览器内存持续攀升到50%左右直接标签页崩溃。根因WebUploader内部在分片上传时会持有每个分片的Blob引用。1000个分片的Blob全部堆在内存里每个50MB就是50GB的虚拟内存占用不崩才怪。解决我在上传流程中做了两件事。第一每次读取分片后立即把该分片从队列中标记为已释放实际上就是把引用设为null。第二在uploadFinished事件中主动调用uploader.removeFile(file, true)让WebUploader彻底释放该文件的所有内部状态。验证改造后上传30GB文件浏览器内存稳定在2GB以内长时间运行无崩溃。6.2 MD5计算卡死UI用户以为程序死了现象测试反馈选完文件后页面就死了鼠标都动不了。根因虽然我们用了抽样指纹方案但在计算抽样分片的MD5时还是在主线程里做的。几个分片的ArrayBuffer加起来几十MBSparkMD5计算时一次性遍历主线程被阻塞。解决把指纹计算整体放入Web Worker。计算过程中UI完全无感计算完成后通过postMessage把指纹返回主线程。验证即使抽样分片达到150MB30GB文件的5%即15个100MB分片计算也在几百毫秒内完成UI零卡顿。6.3 分片乱序合并导致视频花屏、中断现象偶尔出现合并后的视频文件大小正确但播放到某个时间点就花屏或者直接跳帧。根因服务端合并时直接按文件系统遍历临时目录的顺序合并没有按chunkIndex排序。并发上传下分片落盘的顺序和写入顺序不一致导致合并后的文件内部数据错位。解决合并前必须解析分片文件名中的chunkIndex按升序排序后再合并。同时增加了合并前的元数据校验先校验分片总数是否等于预期总数再校验每个分片的大小是否符合预期。验证加入排序校验后连续测试了20次随机中断再续传合并后的视频文件哈希全部一致无一次花屏。6.4 临时分片碎片堆积服务器磁盘被塞满了现象内网服务器运行一个月后磁盘满了。查下来发现临时上传目录里有几十GB的.part文件。根因用户传一半不传了或者上传失败后没有清理临时分片。服务端只负责收分片和合并没有处理孤儿分片。解决服务端增加了两级清理机制。第一级合并成功后立即删除分片文件。第二级定时任务每天扫描临时目录删除超过24小时尚未合并的分片文件。同时在前端增加了取消上传时主动通知服务端清理分片的接口。验证清理机制上线后临时目录的占用稳定在几百MB以内。注意这个清理逻辑要谨慎配置24小时这个阈值——内网用户经常传一半就下班走了第二天接着传如果我清理得太激进会把续传的底料给铲了。6.5 duplicate重名问题同名文件无法再次上传现象业务同事反馈同一个视频文件传第二次前端直接提示文件已存在无法重新上传。根因WebUploader默认通过文件名大小判断重复文件duplicate属性默认值为false即不允许重复文件加入队列。但卫星视频经常有同一镜头多次回传的场景文件名可能相同但内容不同时间戳在文件名里但业务方可能会手误重命名。解决在初始化时设置duplicate: true同时用我们的文件指纹来区分文件如果指纹不同即使文件名相同也视为新文件。指纹相同的情况下直接走秒传校验不占用带宽。验证同名不同内容文件可正常排队上传同名同内容文件秒传符合业务预期。7. 插件封装与业务接入把改造能力固化成标准API完成所有底层改造后最后一步是把这个改造过程固化成标准插件让业务系统不用关心内部实现细节直接调用就能用。这部分功夫花在接口设计上比在业务代码里塞一堆底层逻辑强得多。7.1 对外API设计插件对外暴露的方法非常简洁尽可能贴近业务方的直觉const uploader new SatelliteUploader({ server: /api/upload/chunk, checkServer: /api/upload/check, mergeServer: /api/upload/merge, accept: .mp4,.ts,.avi,.mxf }); uploader.on(uploadProgress, function(percent, file) { console.log(${file.name}: ${percent.toFixed(2)}%); }); uploader.on(uploadComplete, function(file) { console.log(${file.name} 上传完成); }); uploader.upload(file);底层初始化WebUploader、文件指纹计算、断点续传逻辑、重试策略全部封装在插件内部。业务方只需要关心三个事件progress、complete、error。7.2 事件体系与失败重试策略事件体系我参考了WebUploader的设计但简化了一层。对外暴露的核心事件uploadStart文件开始上传。uploadProgress上传进度返回百分比。uploadComplete上传完成包含服务端的校验结果。uploadError上传失败包含错误码和重试信息。uploadRetry自动重试通知。失败重试这里我采用了渐进式重试。分片失败首先立即重试1次如果仍然失败等待10秒后重试第2次再失败等待30秒重试第3次。3次重试后仍然失败上报错误并暂停该文件上传。这个策略在弱网环境下比较有效既不会因为频繁重试而加重网络负担也不会因为不重试而让用户手动操作。7.3 插件集成时的注意事项业务系统接入插件时有几个细节容易遗漏跨域配置内网系统如果前后端分离分片上传接口的CORS要配置允许带自定义Header比如X-File-Id否则大文件请求会直接失败。请求超时时间分片上传请求的超时时间建议设置在5分钟以上。内网虽然有波动但正常上传一个50MB分片也就几十秒5分钟足够宽裕。Nginx上传大小限制如果业务系统前面挂了Nginx默认的client_max_body_size是1MB不调大分片上传必然失败。这个坑我帮别人排查过很多次。7.4 插件的扩展方向这个插件做完之后我还在持续迭代目前有几个方向已经验证过秒传能力文件指纹一致的情况下前端直接跳过上传服务端将已有文件关联到当前用户秒级完成。断点下载既然上传能断点续传下载也可以做对称的分片下载和合并这套逻辑稍作调整就能复用。上传加密在分片读取时对数据进行AES加密服务端合并前解密满足更高的安全要求。卫星视频、遥感影像、试验记录这类超大体量文件未来只会越来越多。上传组件不是简单的UI控件它本质上是一套分布式可靠传输的最小闭环。我把这套改造方案沉淀成插件后业务系统的接入成本从原来的几天降低到半小时故障率也显著下降。如果你手头也有类似的需求建议参考这个思路先把传输可靠性这四个字吃透再动手写代码。