基于WebUploader的大文件分块上传与双重MD5校验方案实践

去年在协助某航空制造单位的型号协同平台做三维模型文件上传服务时，我遇到了一类非常典型的需求：研发人员要频繁把动辄几个GB的STEP、OBJ、FBX模型文件上传到Web服务端，供跨地域团队做在线分块评审。浏览器默认上传方式在这种场景下几乎撑不住，网络一抖动，整个文件从头再来；Windows工作站和macOS笔记本混用，文件跨平台流转后还容易出现字节级损坏。后来我基于百度WebUploader做了一套分块上传加双重MD5校验的服务端方案，生产环境稳定跑了半年多。这篇把整个设计思路、接口协议、前后端核心代码和踩过的坑完整记录下来，给同样在处理大文件上传场景的团队一个可直接参考的复现路径。

1. 需求拆解：航空航天场景下三维模型上传的3个核心痛点

1.1 痛点一：文件尺寸不是一般的大

航空航天领域的三维模型文件，和普通互联网产品里的图片、文档完全是两个量级。一个完整的整机结构模型，STEP或IGES格式动辄5GB到20GB，包含数千个零部件的装配体更是家常便饭。即使是单个零件用于工艺审查的OBJ、STL，也常常在几百MB到1GB之间。

文件大了之后，传统表单上传的第一个瓶颈就是HTTP请求体大小。大多数Web服务器默认对单次请求体有限制，Nginx通常是1MB，Tomcat是2MB，想放开到几GB并不是不行，但意味着一次请求要持续几十分钟甚至几个小时。这期间任何一个中间网络节点抖动、客户端休眠、服务器重启，都会导致上传中断，而所有已经传输的数据全部作废。更麻烦的是，几个GB的文件在传输过程中如果被截断，有可能只是末尾少了几个字节，客户端无法感知，服务端拿到的是一个“看起来完整但实际已经损坏”的文件，轻则评审时模型无法加载，重则后续仿真计算出现不可预期的错误。

这个规模的文件，必须用“分块上传”来拆解，每一块可以单独传输、单独校验、单独重传，任何一块失败都不会影响其他已经完成的块。这是解决大文件上传问题的基本前提。

1.2 痛点二：网络中断导致“一夜回到解放前”

型号协同往往分布在多个城市甚至多个国家，研发人员通过跨地域的研发协作网络访问统一平台。这种网络环境的典型特点是：带宽不低，但链路长、中间节点多，偶发性丢包和中断时有发生。我曾经在测试环境用模拟限速工具跑过一个5GB的FBX文件上传，网络抖动率只要超过2%，传统上传方式基本就没戏，连续两天反复失败。

分块上传在这种场景下的价值在于“断点续传”。网络断了，重启后客户端只需要重新上传没有成功的块，已经传完的块直接跳过。要做到这一点，不止是前端把文件“切片”这么简单，更重要的是服务端要记住“哪些块已经完整接收并且校验通过”，前端在恢复上传前要主动向服务端查询已接收块列表，两边一对比就知道从哪里继续。

这也是我当时选型时的硬性要求：不支持断点续传的方案直接不进入对比名单。

1.3 痛点三：跨平台带来的系统差异

航空航天行业的终端环境比互联网公司复杂太多。设计工程师大多在Windows工作站上用CATIA、UG/NX，但工艺部门、质量部门的人可能用macOS笔记本；服务器端为了稳定性和吞吐量，又几乎都是Linux发行版。

这个“跨平台”看起来容易，实际落地全是细节：

第一，文件系统差异。Windows的路径分隔符是\，Linux是/；Windows文件名不区分大小写，Linux区分。如果用原始文件名直接落盘，同一个Model.stp和model.stp在Windows上可能互相覆盖，在Linux上却安然共存，行为不一样就会出线上事故。

第二，编码差异。macOS下文件名通常用NFC规范化，Windows下是NFKC或GBK环境，中文文件名一旦跨平台流转，非常容易出现乱码。服务端存文件时不能依赖客户端提供的文件名，必须自己生成内部唯一标识，原始文件名只作为元数据字段保存。

第三，浏览器差异。WebUploader早期版本依赖Flash做回退，但macOS和主流的Chrome/Edge早已不支持Flash；Safari对超大Blob切片、File对象的支持也有历史坑。跨平台稳定上传，必须强制走HTML5模式，并且对每个平台的浏览器特性做专项测试。

2. 为什么选WebUploader而不是自己造轮子

2.1 WebUploader的核心能力盘点

百度WebUploader是一款很老但非常成熟的富媒体上传组件。它的核心能力正好覆盖了上面的三个痛点：

分块上传是内建能力，设置chunked: true和chunkSize之后，它会自动把大文件切片成固定大小的块，每个块用独立的multipart请求发送到服务端。

并发控制做得比较省心，threads参数控制同时上传的块数量，不用自己维护异步队列。

队列管理、重试、进度条、拖拽上传、粘贴上传这些功能都是开箱即用，减少了大量重复开发。

它还带了一个MD5计算插件，基于SparkMD5实现，可以在上传前计算整个文件的MD5值，为服务端做最终校验提供依据。

虽然百度后来停止了持续更新，但核心的API设计和HTML5实现非常稳定，社区里大量项目仍在生产环境使用。对一个需要快速落地、长期维护的行业项目来说，“稳定”比“花哨”重要得多。

2.2 与原生实现和第三方框架的对比

自己用XMLHttpRequest或Fetch实现分块上传，不是不行，但工程量远比想象中大：文件切片、块队列调度、并发控制、失败重试、进度上报、断点续传状态持久化、MD5计算、与服务端的状态同步，至少一到两人周起步。而且这些逻辑分散在各处，出一两个边界问题排查起来非常痛苦。

用Plupload也是一条路，它是WebUploader的前身，同样支持分块和队列。但Plupload的维护活跃度更低，HTML5优先级配置需要额外处理。用目前流行的uppy或resumable.js，功能确实更现代，但对服务端的协议约束比较强，需要更多适配工作。

对于当时项目的约束条件来说，WebUploader是“够用且正好”的选择：它有完整的HTML5分块协议，前端只需关注业务层，服务端只需实现接收分块和合并的接口，不依赖它库特定的运行环境要求。

2.3 整体架构：四层协作

我最终确定的整体架构分为四层：

• 浏览器端：WebUploader负责切片、并发上传、进度与重试；SparkMD5计算全文件MD5；
• 接入服务：负责接收单个分块，实时计算分块MD5并校验，记录每个块的上传状态；
• 状态存储：用数据库（MySQL/PostgreSQL）记录上传任务的元信息和分块完成情况，实现断点续传和并发合并控制；
• 文件存储：分块先落到临时目录，全部校验通过后按序合并到最终目录，合并完成后再做整文件MD5校验。

分层的原因是为了让每一层职责单一。接入服务不直接碰最终文件，只和临时分块打交道；状态存储独立出来后，多个接入实例可以共享同一个上传任务状态，为将来水平扩展留了余地。

3. 校验链路设计：从分块到合并的两次MD5

3.1 为什么用MD5而不是CRC32或SHA-1

校验算法选型时，团队内部有过一轮讨论，我最终选了MD5作为主校验算法，辅助用文件长度。三者的对比：

这里要澄清一个常见的认识误区：MD5确实在密码学场景下被认为不安全，因为它存在碰撞攻击的可能性。但我们用MD5的目的不是“防恶意篡改”，而是“检测网络传输过程中的随机损坏”。对于网络丢包、字节错位这类非对抗性错误，MD5的128位校验几乎不会漏判，计算速度又比SHA-1明显更快。几个GB的文件，用流式计算MD5，耗时通常控制在几秒到十几秒，这个成本完全可以接受。

3.2 fileKey生成：快速抽样的文件指纹

断点续传时，服务端需要识别“同一个文件”。直接用文件名肯定不行，同名不同内容、同内容不同名的情况在行业项目里都出现过。整个文件计算MD5是最准确的，但一个10GB的文件，上传前要花几十秒先算一遍MD5，会让用户在进度条完全停住的情况下等待，体验很差。

我采用了抽样指纹方案作为fileKey，生成规则是：

fileKey = md5(fileSize + "_" + 首块1MB的MD5 + "_" + 末块1MB的MD5)

这样只需要读取文件头部1MB和尾部1MB，配合文件总大小，就能在几百毫秒内生成一个基本唯一的指纹。实测下来，对于正常的三维模型文件，这个指纹的区分度足够高，能够覆盖“不同文件同名”“同一文件改名”“内容相同但元数据不同”等常见场景。当然，为了极致严谨，最终合并完成后仍会计算整个文件的MD5做最终确认，抽样指纹只是用来快速定位上传任务，不承担最终校验职责。

3.3 分块MD5与合并后全文件MD5的“双重保险”

整套校验机制是两层：

第一层，每个分块上传时，服务端边接收边流式计算该块内容的MD5，与前端传上来的chunkMd5比对。不一致就立即返回失败，前端自动重传该块。这一层解决的问题是“单块在传输过程中损坏”。

第二层，全部分块上传完成后，服务端按块序号升序合并文件，合并过程中以二进制流方式写入，绝不允许文本模式或任何字符集转换。合并完成后，对整个最终文件再做一次流式MD5，与上传前客户端算好的fileMd5比对。这一层解决的问题是“分块之间在切割、合并过程中可能出现整体错位”。

为什么合并后还要再校验一次？因为分块上传存在一个隐蔽风险：分块之间可能重复、丢失、或以错误顺序合并。分块1、2、3如果某个块内容装错序号，单块校验全部能通过，合并出来的文件却与原始文件完全不同。只有整文件MD5比对才能发现这一类整体性问题。

双重校验意味着，任何一个问题块都能被精准定位，不会被模糊地归因为“文件坏了”，这对三维模型评审这种对数据质量要求极高的场景非常关键。

4. 服务端落地：分块接收、合并与跨平台适配

4.1 接口协议设计（init/chunk/merge）

服务端建议拆成三个接口，语义清晰，也便于后期扩展：

init接口的返回值中包含服务端生成的uploadId，这个uploadId是后续所有操作的唯一凭证，比前端传来的文件名可靠得多。chunk接口负责落盘分块和记录状态，merge接口在做完全部合并和校验后再把状态改成已完成。三个接口拆开的好处是，任何一个环节失败都可以独立重试，不会把状态搅成一团。

上传任务的状态表设计大致如下：

upload_task - upload_id: varchar(64) 主键 - file_key: varchar(64) 抽样指纹 - original_name: varchar(255) 原始文件名 - file_size: bigint - file_md5: varchar(64) 前端计算的全文件MD5 - total_chunks: int - received_chunks: json 已接收成功的分块索引数组 - status: enum(initializing, uploading, merging, completed, failed) - created_at, updated_at

分块明细可以单独一张表，也可以像上面这样用JSON数组记录，取决于你的分块数量和数据库类型。几百个块用JSON完全没问题，上万个块就需要独立的分块表，避免单行数据过大。

4.2 幂等与并发控制

分块上传天然是并发请求，同一时刻可能有多块到达，网络超时后前端重试也可能导致同一块被提交两次。服务端必须做幂等处理。

我的策略是：以(upload_id, chunk_index)为唯一键，分块落盘前先查询该索引是否已经存在。如果存在且校验通过，直接返回成功，不再重复写盘；如果存在但MD5不一致，说明产生了冲突，返回冲突错误码，由前端重新计算后决定是否清理重传。

合并接口的并发控制更要小心。同一个uploadId如果被多个请求同时触发合并，可能造成文件写一半被另一个进程覆盖。我用状态机加数据库乐观锁解决：合并前执行UPDATE upload_task SET status='merging' WHERE upload_id=? AND status IN ('uploading','completed')，受影响行数为0说明已经被其他请求接管，直接返回“合并中”的状态让前端轮询。

这里有一个我实际踩过的坑：如果直接把全部块索引放在一个JSON字段更新，高并发写入很容易出现覆盖丢失。最终我选择了两种方式之一，块数少的用JSON整体更新，块数多的则用独立的分块明细表，每次只插入单块记录，合并且根据明细表判断是否全部就绪。

4.3 跨平台文件系统适配

服务端文件存储的目录结构我建议按如下方式组织：

/data/upload_root/ {upload_id}/ chunks/ 0001.tmp 0002.tmp ... final/ {uuid}.stp

所有临时文件和最终文件都使用upload_id或UUID命名，原始文件名只保存在数据库里。这样彻底规避了Windows/Linux之间的路径分隔符、大小写敏感性、中文编码等问题。最终文件入库时，文件路径也统一用相对路径，数据库里存/upload_root/{upload_id}/final/{uuid}.stp这种格式。

文件名本身不要直接用前端传过来的值拼接到路径里，必须经过服务端的编码过滤。前端传入时可以用encodeURIComponent(fileName)，服务端再解码，同时过滤掉\ / : * ? " < > |等非法字符，防止路径穿越攻击。

临时目录的清理也不能忽略。分块上传过程中，如果用户中途放弃，临时分块会一直留在磁盘上。我加了一个定时任务，定期清理超过7天且状态不是completed的临时目录，避免磁盘被填满。刚开始没做这个清理，半个月后测试环境磁盘就被撑爆过一次，教训很深刻。

4.4 合并与整文件校验的代码实现

服务端我用的Node.js实现，核心的合并逻辑可以拆成三步。需要注意，整个合并且必须使用流式写入，直接fs.readFileSync一次性读入大文件会瞬间打爆内存。

以下是一个参考实现：

const fs = require('fs'); const crypto = require('crypto'); const { promisify } = require('util'); const pipeline = promisify(require('stream').pipeline); async function mergeChunks(uploadId, totalChunks, chunkDir, finalPath) { const writeStream = fs.createWriteStream(finalPath); for (let i = 0; i < totalChunks; i++) { const chunkPath = path.join(chunkDir, `${String(i).padStart(4, '0')}.tmp`); if (!fs.existsSync(chunkPath)) { throw new Error(`chunk ${i} missing`); } await pipeline(fs.createReadStream(chunkPath), writeStream, { end: false }); } writeStream.end(); const md5 = crypto.createHash('md5'); const finalStream = fs.createReadStream(finalPath); for await (const chunk of finalStream) { md5.update(chunk); } return md5.digest('hex'); }

这里pipeline的end: false参数很关键，它让每个分块的读流写完自己后不关闭写入流，这样才能把所有分块追加到同一个文件后面。合并完成后，再对整个目标文件单独算一次MD5。MD5计算也是流式读取，不把文件整体载入内存。

单个分块接收时的MD5校验，逻辑也类似。用流式哈希边收边算，而不是等整个分块落盘后再去读文件算：

const hash = crypto.createHash('md5'); req.on('data', (chunk) => { hash.update(chunk); }); req.on('end', () => { const receivedMd5 = hash.digest('hex'); if (receivedMd5 !== expectedMd5) { // 删除接收到的临时文件，返回错误 } });

这样能提前到“写盘之前”发现问题，避免把脏数据留在临时目录里。

5. 前端实操：WebUploader配置与核心代码

5.1 初始化参数怎么调（含推导逻辑）

WebUploader初始化时，有几个参数是分块场景的关键，我直接把生产环境用的配置贴出来并解释原因：

var uploader = WebUploader.create({ swf: '/static/Uploader.swf', server: '/api/upload/chunk', pick: '#picker', accept: { title: 'Models', extensions: 'stp,step,igs,iges,obj,fbx,stl,prt,asm,3dxml', mimeTypes: '*/*' }, chunked: true, chunkSize: 10 * 1024 * 1024, // 10MB threads: 3, fileVal: 'file', formData: { token: getToken() }, auto: false });

分块大小chunkSize选了10MB，这是综合权衡后的结果。块太小，比如1MB，一个10GB的文件会产生10240个请求，服务端压力大，数据库记录量大，合并时遍历开销也高；块太大，比如100MB，网络抖动时重传代价又被放大变高。10MB在普通办公网和跨地域链路上都比较均衡，单个块传输时间短，失败重传成本低，同时请求数量控制在几千以内，服务端完全扛得住。

并发数threads选了3而不是10。很多人以为并发越高速度越快，但在跨地域长链路场景下，高并发反而加剧丢包。实测10并发时，路由器或网关的缓冲被打满，重传率上升，吞吐量反而下跌。3到4个并发在弱网环境是性价比最高的区间。

auto: false很重要。因为上传前需要先做全文件MD5计算，如果开启自动上传，文件一旦加入队列马上开始传，MD5还没算完，后面就没法做fileMd5比对。我采用的做法是：文件加入队列后先计算MD5，算完再手动调用uploader.upload(file)。

5.2 上传前如何增量计算MD5

WebUploader官方有md5插件，但直接用SparkMD5手动控制进度的方式是更透明的，也更容易自定义进度提示。核心思路是分片读取文件，边读边更新哈希，避免一次性把整个文件读入内存。

function computeFileMD5(file) { return new Promise((resolve, reject) => { const blobSlice = File.prototype.slice || File.prototype.mozSlice || File.prototype.webkitSlice; const chunkSize = 2 * 1024 * 1024; const fileSize = file.size; const spark = new SparkMD5.ArrayBuffer(); const reader = new FileReader(); let currentChunk = 0; reader.onerror = function (e) { reject(new Error('read file error')); }; reader.onload = function (e) { spark.append(e.target.result); currentChunk++; if (currentChunk * chunkSize < fileSize) { loadNext(); } else { const md5 = spark.end(); resolve(md5); } }; function loadNext() { const start = currentChunk * chunkSize; const end = Math.min(start + chunkSize, fileSize); reader.readAsArrayBuffer(blobSlice.call(file, start, end)); } loadNext(); }); }

这里读取块大小设为2MB，是为了MD5计算的进度更新更平滑。读入的每一块ArrayBuffer都会被SparkMD5累积，内存占用始终控制在2MB左右，不会出现大文件把浏览器内存吃到崩溃的情况。

MD5计算完成再上报服务端，然后调用uploader.upload(file)开始分块上传。

5.3 断点续传：本地缓存加服务端状态的双漏斗

断点续传的核心不是本地记住“我传到了第几块”，而是“服务端到底完整收到了哪些块”。前端在上传前向服务端查询已接收块列表，过滤掉已经传完的块，只传剩余的部分。

实现方式是在init接口之后增加一个查询任务状态的步骤。init如果发现相同fileKey且状态为uploading的上传任务，直接返回已有任务的uploadId和receivedChunks列表。前端拿到列表后，对WebUploader的分块队列做过滤。

// 服务端返回的 uploadTask 中包含 receivedChunks 数组 const missingChunks = []; for (let i = 0; i < totalChunks; i++) { if (!uploadTask.receivedChunks.includes(i)) { missingChunks.push(i); } } // 把剩余需要上传的块信息记录在当前文件对象上 file.__missingChunks = new Set(missingChunks);

WebUploader没有内建的“跳过指定块”的API，常用的折中方案是：为分块请求增加一个额外的接口，在服务端判断该块已存在时直接返回成功。也就是说，前端不用真正跳过块，而是正常发起请求，服务端根据幂等逻辑“秒回成功”，代价只是一次额外请求，对加载和管理来说反而更简单。

前端本地也可以把已传块列表缓存到localStorage，但只作为加速展示用途，不能替代服务端状态。我实际使用中的体会是：以上传任务状态查询的结果为准，本地缓存出现偏差时以服务端为准，最终一致性由服务端保证。

5.4 分块失败处理：uploadAccept回调里的重传逻辑

WebUploader给每个分块请求提供了uploadAccept事件，可以从服务端响应中解析校验结果。如果服务端返回校验不通过，需要让这个块进入重试队列。

uploader.on('uploadAccept', function (file, response) { if (response && response.code === 'CHUNK_MD5_MISMATCH') { // 返回 false 会触发该分块的重传 return false; } });

注意这个回调的返回值很关键，返回false会让WebUploader自动重传当前块，不需要自己额外写重传逻辑。重传次数可以在初始化配置里用chunkRetry控制，我设为3，超过3次就把文件标记为上传失败，在前端给出明确提示，避免用户无感地反复失败。

服务端返回的协议最好固定成统一格式：

{ "status": true, "data": {} }

失败时返回：

{ "status": false, "code": "CHUNK_MD5_MISMATCH", "msg": "分块校验不通过" }

统一协议无论是开发调试、日志排查还是后续对接其他上传组件，都会省很多事。

6. 踩坑实录：5个真实问题与排查思路

6.1 合并后MD5不一致：先查这四步

这个坑我们大概花了半天才定位。现象是前端上传的所有分块都返回成功，但合并后整个文件的MD5和前端计算的fileMd5对不上。

排查顺序我建议按链路一步步来：

第一步，检查所有分块是否真的完整。在分块明细表中核对每个索引是否有记录，尤其是最后一个块。某个分块确实没传成功，但服务端状态记录因为数据库事务没提交而被误判为成功，这种低级错误真的出现过。

第二步，核对每个分块的实际MD5与预期是否一致。如果某一块MD5不一致但当时接口返回了成功，说明服务端的边收边算逻辑有问题，很可能是读取流的边界处理错误。

第三步，检查合并代码是否以二进制追加方式合并。用过fs.writeFile配合'a'模式是正常的，但如果中间有字符集转换操作，比如先解码成UTF-8字符串再写入，就一定会破坏二进制文件。三维模型文件中包含大量非文本字节，任何字符编码转换都会致命。

第四步，确认合并顺序是正确的。排序时不要用字符串排序，"10"会排在"2"前面，必须转成数字后再升序排列。

我当时发现的问题就出在第四步，一个临时脚本里用了字符串排序，小尺寸文件测试时块数少不暴露，真上了9GB的模型才暴雷。

6.2 浏览器内存暴涨和页面卡顿

上线前用2GB模型做验收测试，Chrome的内存占用一路飙到1.5GB，页面明显卡顿。定位后发现是MD5计算方案有问题。

一开始为了图省事，用了FileReader.readAsDataURL读取整个文件，这会一次性把整个文件读成Base64字符串，内存占用是文件体积的1.37倍，2GB文件直接吃掉2.7GB内存，浏览器不崩才怪。

换成readAsArrayBuffer加2MB分片增量读取之后，内存占用稳定在几十MB以内。另一个关联问题是：如果同时有多个大文件排进队列并全部触发MD5计算，内存会叠加。解决方式是在我的业务逻辑里加了全局限制，同一时间只允许一个文件处于MD5计算阶段，其他的排队等待。

6.3 并发合并导致文件错乱

内部测试时，我用一个脚本同时向合并接口发送了3个并发请求模拟极端情况。结果最终文件被写坏，两个请求同时在写同一个目标文件，互相覆盖。

就是前面说的状态机加数据库乐观锁解决的问题。关键不是锁本身多复杂，而是需要把“是否允许合并”的判定放在一条原子的UPDATE语句里完成，不要把“查状态”和“改状态”拆成两步。两步操作之间永远有窗口期，并发时一定出事。

UPDATE upload_task SET status = 'merging' WHERE upload_id = ? AND status IN ('uploading', 'completed');

受影响行数为0时，直接返回“合并已在进行中”，前端轮询最终结果即可。

6.4 macOS Safari上传静默失败

Safari浏览器在部分版本下，File.slice对文件末尾块的处理有兼容性问题。现象是最后一块偶尔只有几KB大小，但WebUploader没有报错，服务端也正常接收，最终合并出的文件和原始文件大小差了几个字节。

这个问题的排查很费劲，因为它是偶发性的，而且不同版本的Safari行为不同。最后在代码里加了一个防御性校验：前端发出每个分块请求时，都带上该块的期望字节数chunkSize服务端在接收完成后校验实际字节数是否一致，不一致直接报错。这个校验对所有浏览器都生效，弥补了部分浏览器在分块边界处理上的不可靠性。

6.5 上传网关反代超时

虽然分块请求本身很小，但合并请求要持续一段时间。当文件特别大时，合并出最终文件加上全文件MD5计算的时间可能超过反代服务器的超时时间，导致合并请求被切断，但服务端的合并任务其实还在后台执行。

解法是把合并接口改成异步任务：合并请求只负责创建合并任务并立即返回，服务端后台执行合并和校验，前端通过轮询任务状态获取最终结果。这样即使反代超时，也不影响合并过程。这个改造投入不大，但收益很明显，整个上传流程从“同步长请求”变成了“任务驱动”，可靠性和用户体验都上了一个台阶。

7. 一点实操体会：如果重新做一遍，我会提前做好的三件事

分块上传加双重校验这套方案跑下来，整体上稳住了，但也走了一些弯路。如果现在让我重新做一遍，有三件事我一定会放到设计阶段就完成。

第一，把合并任务从一开始就做成异步。不要觉得“大多数场景几个GB合并很快”就图省事用同步接口。网络环境不会给你省心，异步化是应对超时、断连、并发问题的统一解，后期再改反而容易动到状态机的细节。

第二，建一套临时分块的自动清理巡检。用户中途放弃上传、浏览器崩溃、任务异常终止，都会在临时目录留下残留分块。定期清理任务看起来不起眼，实际能避免磁盘空间被逐渐耗尽的事故。我上线初期就吃过这个亏，生产服务器磁盘被一个月积累的临时块塞满。

第三，把分块上传和校验的全链路日志完整记录下来。具体来说，每个分块的接收时间、客户端IP、块索引、块大小、块MD5，都要留日志。出了问题排查时，这些日志是唯一能精确还原“文件到底在哪一步坏的”的线索。生产环境没有全链路日志，靠猜是猜不出来的。

最后再分享一个小技巧：前端不要把业务字段一股脑塞进分块请求的formData里，尤其是动态变化的token。WebUploader的formData在初始化时固定，运行中变更会导致某些分块带上旧值。业务参数统一放进URL查询串或请求头，避免分块请求之间的状态不一致。这个细节当时调试了好一阵子，网上资料也少，希望能帮后来的人避开。