大文件上传稳定性实战：WebUploader分片上传与断点续传及TS流对齐

银行系统的视频监控文件回传，一直是个让人头疼的环节。监控点位分散在各网点，单文件动辄几百 MB 到几个 GB，链路还要过网闸、跨地域专线，链路质量稍差就直接超时。更麻烦的是监控视频绝大多数是 TS 流格式，对字节边界极其敏感，分片切得不对，合并出来的文件要么花屏，要么压根没法播放。我们部门以前用原生 XMLHttpRequest 硬传，文件一大基本靠运气，日志里隔三差五就是 Connection reset、Request timed out。后来把上传能力整体切到百度 WebUploader 组件，利用它的浏览器端分片能力，配合服务端做断点续传和完整性校验，回传成功率从 70% 多拉到了 99.5% 以上。

这篇内容，我会把这套方案的选型理由、分片参数调优、Chrome 90 等浏览器兼容性处理、TS 分片边界对齐、服务端协同以及生产环境踩过的坑全部展开讲一遍。不管你是正在做银行监控回传，还是在做其他大文件上传场景，里面的配置项和经验都能直接抄走。

1. 银行监控视频上传，暴露的不只是“大文件”这一个问题

银行项目里的监控视频文件，天然带着几道枷锁。监控点位分布在各个网点，视频产生后先汇聚到网点前置机，再由业务系统回传到数据中心。这个链路里既有局域网，也有跨区域专线，不同网点的出口带宽、链路稳定性差异巨大。有些网点链路质量差到令人发指，传一个 2GB 的文件，中途断个七八次都是常事。如果上传方案本身没有针对这种网络环境做设计，运维同事就会被折腾得天天接网点电话。

更麻烦的是视频文件的格式。监控视频基本都是 TS 流（MPEG-2 Transport Stream），数据按 188 字节的定长 packet 组织，内部还嵌套着 PAT/PMT 表和关键帧信息。这种格式对字节位置极其敏感，浏览器端如果只是简单按固定大小把文件切开，合并时又没有检查边界，最终得到的文件就可能在播放时出现无法解析、花屏、拖动卡顿等问题。普通文档上传测试根本测不出这类问题，必须用真实监控视频才能复现，这也是很多团队容易在验收阶段栽跟头的地方。

这套稳定方案解决的核心痛点有三个：一是单文件太大，整体上传容易超时，服务端接收超时断开后整个传输就报废了；二是网络中途断线后，传统方案必须从头重传，浪费带宽也浪费时间；三是服务端无法对“半截文件”做校验，数据完整性得不到保证。WebUploader 的分片机制恰好覆盖了这三点，它会在内部把二进制文件按字节偏移切成多个小块，为每个分片打上序号，服务端按序合并，也可以在任一分片失败时单独补传，不用整个文件重来。

2. 方案选型：为什么是 WebUploader 而不是原生 H5 上传

2.1 原生 XMLHttpRequest 直传的硬伤

先回头看我们为什么放弃原生直传。XMLHttpRequest 加 FormData 的方式，代码确实简单，一个 POST 请求把整个文件塞进去就行，但问题非常集中。单请求承载整个文件，服务端接收超时就会断开连接，前端拿到报错后没有任何补偿手段。断线之后没有续传逻辑，一切归零。浏览器和网关对单请求体大小、时长都有隐式限制，跨网闸链路尤其明显。多个文件同时传时，并发控制还要自己实现，排队的优先级、失败后的重试策略都要从头写。

我整理过一张对比表，可以更直观地看出两种方案的能力差异：

这里面的核心区别在于“失败成本”。直传模式下，任何一次网络抖动都可能让整个文件的传输作废，重试的开销是 GB 级的；分片模式下，单片失败只损失一个 2MB 或 5MB 的小块，重传代价可以忽略不计。银行网点的上行链路普遍不稳定，稳定性的本质其实就是把失败成本不断拆小，拆到少量链路抖动不再影响整体任务完成为止。

2.2 WebUploader 的分片模型与事件机制

WebUploader 对上传稳定性的贡献，来自它对整个上传生命周期的模型化抽象。文件进入队列后，组件根据 chunkSize 配置把文件切成多个 Blob，每个 Blob 是一个独立的上传单位；组件内部维护一个任务队列，同一时间最多只有 threads 个请求在跑；每个分片请求都有独立的进度回调，组件再把所有分片进度汇总成文件级进度。这套模型解决的不只是“传输”本身，还有“调度”，这是手工实现很容易出bug的部分。

我实际项目里最常用的几个事件是 beforeFileQueued、fileProgress、chunkUploaded、fileUploaded、error。其中 chunkUploaded 事件非常关键，它在每一个分片上传完成后触发，可以在里面把服务端返回的接收校验信息和本地记录进行比对。这个钩子是我们后来实现“零丢失上传”的关键位置。如果没有这个事件，分片是否真正落盘就只能靠猜，断点续传的准确性也会打折扣。

2.3 为什么在银行私有化环境里敢选它

选择 WebUploader 有三个原因。第一，它的运行环境完全在浏览器端，不依赖外部 CDN，压缩包丢到静态资源目录就能用，对银行这种要求资产包自管理的环境天然合适。第二，它对老版本浏览器有明确的适配路径，虽然 Flash 兜底模式在 Chrome 90 里已经不可用，但只要 H5 模式配置正确，浏览器兼容性是有保证的。第三，它的 API 面小，事件驱动模型简单，出了问题团队能快速定位，不像一些企业级上传框架那样黑盒化，出了问题根本不知道从哪查起。

我也对比过 vue-simple-uploader、uppy 等组件。最终没有选它们，并不是说这些组件不好，而是银行项目的选型原则是低风险、少依赖、易审计，WebUploader 在这些维度上的综合得分最高，团队也有多年使用经验。在技术选型这件事上，稳定性和可控性往往比功能丰富重要得多，尤其是一个要跑在生产环境、还要长期维护的上传组件。

3. 影响稳定性的三个关键参数怎么调

3.1 分片大小：默认 512KB 不适合视频文件

WebUploader 默认的 chunkSize 是 512KB，这个值适合常规文档和小文件，但对 GB 级监控视频并不合适。分片太小，分片总数会爆炸，服务端合并时文件系统调用次数剧增，整体 IO 开销非常大；分片太大，单片失败时重传的惩罚成本变高，断点续传的优势就被稀释了。我们拿一个 2GB 的真实 TS 视频做过对比测试，结果很有参考价值。

• 512KB 分片：约 4096 片，服务端合并阶段明显变慢，整体耗时比 2MB 分片慢约 20%。
• 2MB 分片：约 1024 片，在网关链路质量一般的网点，单片失败率中等，重传开销可控。
• 5MB 分片：约 410 片，单片传输时间适中，即使失败重传，代价也只有 5MB 流量。
• 10MB 以上：单片成功后吞吐最大，但弱网环境下单片失败率显著上升，用户体验反而变差。

最终我们默认值定在 5MB，并由后端按网点上下发配置，链路质量差的网点自动切到 2MB。分片大小的选择不能只从传输效率一个维度出发，要综合“失败惩罚、重传代价、服务端合并开销”三重因素来平衡。视频文件尤其不能往小设，因为 TS 流的对齐本身要求一定粒度，分片次数过多还会放大边界校验的开销。

3.2 并发线程数：稳定性的隐形杀手

WebUploader 的 threads 参数控制同时上传的分片数量。我见过有同事一上来就设 10，理由是传得快，但实测在银行跨网闸链路上，线程并发超过 5 之后带宽并没有涨，反而因为浏览器和网闸之间 TCP 连接数过多触发限流或丢包，整体速度打折，失败率上升。线程数不是越大越好，它和网络环境之间存在一个平衡点，过了这个点，收益曲线掉头向下。

我们根据网点的实际链路情况整理了一张推荐表：

另一个容易被忽视的点是 threads 和 chunkSize 的组合效应。总吞吐约等于 threads 乘以单分片带宽，在链路质量一般的场景，宁可用“小分片加中等并发”，也不要“大分片加高并发”。大分片加高并发一旦触发链路限流，所有分片同时卡住，重试风暴马上就来。我们在一次参数调整中把 threads 从 8 降回 3，成功率提升了 5 个百分点，这就是活生生的教训。

3.3 超时与重试：自动重试必须有指数退避

WebUploader 在默认配置下，分片请求失败后会抛出 error 事件，但不会自动重传。银行场景里网络抖动是常态，让用户手动点重传根本不现实，所以我在这层封装了一个重试队列。每个失败分片自动重传，最多重试 3 次，重试间隔按指数退避，第 1 次失败等 2 秒，第 2 次等 4 秒，第 3 次等 8 秒。连续失败超过 6 次的，暂停整个上传队列，提示操作员检查网络。指数退避的核心作用是防止重试风暴，如果没有退避间隔，重试请求会在网络恢复前连续撞击链路，把原本就脆弱的路由彻底堵死。

超时设置同样要细心。WebUploader 依赖 jQuery 的 ajax 配置，我们把 timeout 设为 60 秒，超过这个时间主动 abort，让请求进入重试逻辑。timeout 如果太短，比如设成 30 秒，在跨网闸传输 5MB 分片时很容易误判，因为慢链路下单片的实际传输时间可能确实超过 30 秒。误判引发的重试如果追不上网络恢复速度，就会陷入“永远在重试”的死循环，日志里全是重复错误，用户感知就是传了一天也没传完。

4. 浏览器端兼容性工程：Chrome 90 和 TS 分片的两个大坑

4.1 银行终端的 Chrome 90 环境，需要注意什么

银行办公终端的浏览器版本普遍滞后，我们部门大量终端锁在 Chrome 90，既不允许自动升级，也不允许回退。Chrome 90 这种版本对于 WebUploader 而言，有两点和其他浏览器版本不同。第一，Flash 上传路径在 Chrome 84 之后逐步被封禁，到 90 版本已经彻底不能作为兜底；第二，V8 引擎对 Blob 内存的回收策略和其他更新版本有差异，GB 级大文件长时间上传时，内存占用会持续累积，而且回收效率明显不如 Chromium 的新版本。

这两个差异在我们项目里引发过两个实际问题。一个是旧版 WebUploader 0.1.5 在 Chrome 90 上有概率出现分片索引错位，chunk 序号和实际 Blob 内容对不上；一个是连续传完两三个 GB 级文件后，页面内存占用直冲上限，卡到无法操作。这两个问题单独拿出来都能解决，但叠加在 Chrome 90 环境里，排查难度就上了一个台阶。后来我们升级到 WebUploader 2.x 的稳定版，把并发 threads 降到 3 到 5 之间，并在每个分片请求的 formData 里显式带上 start、end 字节偏移，才彻底把错位问题压住。

Chrome 90 的 Blob 切分还有一个记忆深刻的细节。Blob 对象在切分文件时，并不是复制文件内容，而是创建对底层文件字节范围的引用。这意味着大量分片对象会一直持有原文件的字节范围引用，即使上传完成，GC 也不一定能立即回收。解决办法只能是“用完即弃”：每个分片成功后释放对应引用，整个文件传完后调用 uploader.reset()，业务层实现“一个文件一个组件实例”，传完就销毁重建，不让组件复用。

4.2 TS 视频分片，为什么必须做边界对齐

监控视频使用 TS 流封装，数据按 188 字节定长 packet 组织，内部还嵌套着 PAT/PMT 表和 IDR 关键帧。WebUploader 只按字节切文件，完全不会理解 TS 包的内部结构，所以我们必须自己保证“切出来的分片恰好落在完整 TS 包的起始位置”。理想的分片边界有两个要求：分片起始位置是 188 的整数倍；如果条件允许，尽量让分片从 IDR 关键帧开始，方便服务端做视频索引。

如果边界对齐没做好会发生什么？直接表象是合并文件能播放，但拖动进度条时卡顿明显，严重时播放器直接报 “No data available” 或花屏。银行监控文件是留证材料，通常要保存三个月以上，这种数据一旦出问题，影响就不是一个网点的事了。

我们的做法是：在文件预处理阶段，用 FileReader 读取分片起始位置的几个字节，检查是否为 TS 同步字 0x47，不是的话就向前回退到最近一个 0x47 的位置，把该分片的实际起始偏移记录下来，和分片数据一起传给服务端。服务端合并时严格按照“分片序号加字节偏移加数据长度”来组装，并校验偏移的连续性。这里我要强调一下，WebUploader 默认只传 chunk 和 chunks 两个参数，不会告诉服务端每个分片在原文件里的字节范围，所以自定义 formData 里的 start、end 字段必须自己加。这个设计帮我们拦截了好几次“高分片成功率掩盖的低级丢片”问题。

4.3 一个必须处理的隐性坑：重复上传与文件 MD5

浏览器端分片稳定还有一个容易忽略的方向：重复上传。操作员看到页面卡顿，下意识又点了一次上传，队列里就会出现两个相同的文件，服务端收到两套相同分片，如果没有去重逻辑，合并时就会出现分片内容互相打架的情况。WebUploader 的 duplicate 参数默认允许重复文件进入队列，我建议在业务里显式设置 duplicate: false，同时在上传前用 spark-md5 对文件计算 MD5，得到 fileMd5 后传到服务端。服务端发现相同 MD5 的文件已有完成记录，直接返回“文件已存在”，前端弹出提示，不再触发二次传输。

MD5 计算对 GB 级文件确实有性能开销，完整读一遍文件可能要几十秒，但这个开销换来的稳定性是值得的。而且把 fileMd5 放在 formData 里，每个分片请求都会带上同一个值，服务端可以据此做分片归属校验，避免两个文件的分片互相串扰。我们线上出过一起“串片”事故，根源就是两个文件并发上传时，分片被写进了同一个上传任务目录，加了 fileMd5 和 taskId 双重校验后，这个问题彻底消失。

5. 稳定的另一半：服务端协同与断点续传闭环

5.1 四个基础接口，把分片和合并规范化

前端调得再稳，没有服务端的配合，稳定性也只是一句空话。我们围绕分片上传在服务端抽象了四个接口，全部基于常规的 Java Web 框架就能实现，不需要引入复杂中间件。第一个是 init 接口，接收 fileMd5、fileName、fileSize、chunkSize 参数，返回一个 uploadId 和已接收的分片列表；第二个是 chunk 接口，接收 uploadId、chunkIndex、start、end 以及分片数据，完成单片的接收和落盘；第三个是 complete 接口，前端确认所有分片发送完毕后触发，服务端做完整性校验和文件合并；第四个是 status 接口，用于断点续传时查询接收进度。

分片临时文件的命名规则是 uploadId 加 chunkIndex 加 start 加 end 的组合，后缀是 .part。合并时按 chunkIndex 排序，逐个二进制追加。追加之前必须先检查 start 偏移是否连续，任何一个缺口都可能导致最终视频花屏。合并完成后，服务端要重新计算整个文件的 MD5，和前端传入的 fileMd5 比对，一致才向业务系统返回成功。同时把合并时间、操作人、文件大小、MD5、分片数量全部写入审计表。银行系统必须留痕，这块虽然是额外的开发成本，但绝不能省。

5.2 断点续传的完整时序

断点续传是整个稳定性方案里体验提升最明显的部分。刷新页面或进程中断后，用户重新进入上传页面，前端从 localStorage 恢复任务列表，调用 status 接口拿到服务端已接收的分片索引集合，然后只补传缺失的分片。整体的时序可以拆成四步：第一步，前端读取本地缓存的上传任务，拿到文件的基本信息；第二步，调 init 接口，服务端返回 uploadId 和已完成的分片列表；第三步，前端通过 uploader.option('formData') 注入 uploadId 和 skip 列表，把组件状态切到续传模式；第四步，队列启动后，每一个分片请求都带上当前 chunkIndex，服务端发现该片已存在就直接返回成功，前端跳过，其他分片照常传输。

这里有个关键细节：断点续传时不能用组件的自动模式，因为组件默认会把所有分片从头到尾传一遍。我们的做法是在 beforeFileQueued 或 fileQueued 事件里动态注入 skipChunks 参数，服务端在 chunk 接口里判断当前 chunkIndex 是否已接收，已存在的分片直接返回“已接收”状态，前端也就不会再传这个分片的字节。用这种方式，续传流量只会集中在缺失分片上，几乎不浪费带宽。这套机制上线后，网点上行链路抖动导致的失败，从“整个文件重传”变成“只补最后几个分片”，回传成功率稳定在 99% 以上。

5.3 配置示例和一把关键参数

把前面讲的内容落到配置上，大概就是下面这个样子的。前端初始化 WebUploader 的配置，核心参数是 chunked、chunkSize、threads、duplicate 这几个：

var uploader = WebUploader.create({ swf: '/resources/Uploader.swf', server: '/api/upload/chunk', pick: '#picker', accept: { title: 'TS Video', extensions: 'ts', mimeTypes: 'video/mp2t' }, chunked: true, chunkSize: 5 * 1024 * 1024, threads: 3, duplicate: false, auto: false, formData: { fileMd5: '', uploadId: '' }, fileVal: 'file' });

文件进入队列时计算 MD5 并注入 formData：

uploader.on('beforeFileQueued', function (file) { var fileMd5 = computeFileMd5(file); uploader.option('formData.fileMd5', fileMd5); });

NGINX 侧需要放开上传体积限制和超时时间，否则分片请求也会被代理层挡下来：

client_max_body_size 10m; proxy_http_timeout 300s; proxy_send_timeout 300s;

这些参数在银行场景下的价值，最终体现为“可排查、可审计、可复现”。尤其可复现这一点很关键，生产环境出了问题，能够按相同步骤还原场景，才能谈得上后续的优化和整改。

6. 生产环境常见问题与排查实录

6.1 “传完花屏”的典型案例与定位过程

我们线上出过一次典型的“传完花屏”问题。运维反馈某网点上传的监控视频有 1 秒多的花屏，用户换了几台机器重传都一样，基本排除了播放器和终端的问题。我先让后端把所有分片的 start、end 记录打印出来比对，发现两片 start 相同但字节内容不同，说明同一时间有两个不同文件的同名分片混进了同一个 uploadId。进一步排查，是操作员先后拖了两个文件进队列，两个文件的分片在网络层并发交错，恰好写入了同一个 uploadId 的临时目录。

这个问题的根因不在 WebUploader 组件本身，而在业务层没有做上传任务互斥。我们随后加了全局锁：队列里已有任务时，新任务只能等待，不能并发。排查途中最有价值的动作，其实是把服务端落盘日志和前端 formData 日志对齐，通过对比上传时的 taskId 和 fileMd5 定位到“是谁的数据写进了谁的任务”。这次排障让我意识到，浏览器端分片稳定性问题中很大一部分来自任务编排，而不是传输链路，组件只提供能力，业务流程的边界还得自己守。

6.2 内存飙升问题的定位与组件销毁策略

连续传完三个 GB 级文件后，页面卡到无法交互。这个问题在 Chrome 90 环境里尤为明显，因为 Blob 的对象引用机制和 V8 的回收策略共同作用，内存只增不减。用 DevTools 的 Memory 面板拍了两张 heap snapshot 做对比，发现 WebUploader.File 对象和 Blob 对象各占了几百 MB，内存迟迟不释放。

解决方案分三层：第一，每个分片成功后，显式释放本地 Blob 引用；第二，整个文件完成后调用 uploader.reset()，清空内部队列；第三，每个文件独立使用一个组件实例，传完就销毁重建，不跨文件复用。这套策略在 Chrome 90 上效果尤其明显，因为我们实测过相同逻辑在新版 Chrome 上内存回收要快得多，而在 90 版本里，只有主动销毁才靠得住。

6.3 NGINX 的 413 问题，分片也被坑

分片请求按理说体积不大，但我们差点被 NGINX 的默认配置坑了。client_max_body_size 默认值是 1MB，当分片大小 5MB 加上 multipart 编码膨胀之后，请求体很容易超过 1MB，NGINX 直接返回 413，前端没做对应处理时，现象就是“传一下就断了”，而且日志里看不到明显的报错，因为 413 被前端误读成了通用失败。我们后来把 client_max_body_size 调到 10MB，proxy_http_timeout 调到 300 秒，这个问题才彻底解决。

这也是一个提醒：分片不代表一定不会触发代理层的体积限制，设置代理层时，要按“单片大小加编码膨胀加一定冗余”来计算，不能想当然觉得分片之后请求体就肯定很小。我们在排查这个问题时还发现，个别网点走的代理链路上还有一层自定义网关，这层网关的超时设置也需要一并检查，否则 NGINX 放行了，网关又给断了。

6.4 常见问题速查表

最后把生产环境里遇到过的问题和对应解法整理成一张速查表，方便以后排查时直接对照：

7. 一点亲历的体会

这套方案刚上线时，我以为最大的挑战会来自服务端合并性能或者前端兼容性，但真正做完才发现，稳定性问题大多不是单一因素造成的，而是“前端参数、服务端校验、业务编排、浏览器环境”四条线同时作用的结果。每一个环节单独看都说得过去，合在一起就暴露出各种边角问题。比如分片大小和并发线程之间、超时设置和重试策略之间、Blob 内存和组件生命周期之间，都有隐藏的联动关系，只调一个参数往往会按下葫芦浮起瓢。

我个人的操作习惯是，任何参数改动，都要在真实监控视频上跑一遍“断网-恢复-续传”用例，然后对比服务端记录的 start/end 偏移日志和文件 MD5，确认没有边界问题才放行到生产。这个验证流程帮我拦下了至少两轮“测试通过但线上花屏”的回归事故。测试用的样本也很有讲究，不能只拿一个短片反复测，要覆盖不同码率、不同时长的真实录像，才能把边界情况暴露出来。

另外还想说一句，WebUploader 本身是个老组件了，但它所代表的“浏览器端分片上传”思路并不过时。在银行这种对稳定性和可控性要求极高的环境里，把分片粒度调适中、并发数调克制、重试加上退避、TS 边界对齐、服务端校验完整、断线可续传、内存释放干净，这几件事组合起来才叫真正的稳定性工程。工具只是顺手的一环，真正稳住的是围绕它设计的工程规范。