这篇文章会用一个完整的前后端项目，带你从头理解“大文件上传”到底是怎么实现的。

项目使用 React + Vite 做前端，Node.js 原生 HTTP 模块做后端。前端负责选择文件、切片、计算 hash、上传分片、显示进度、暂停继续和失败重试；后端负责判断是否秒传、记录已经上传的分片、流式保存分片、合并文件和返回文件列表。

如果你是初学者，不用担心这套东西看起来名词很多。我们会从最朴素的问题开始讲：为什么普通上传不适合大文件？为什么要切片，为什么要 hash？按理说，为什么能断点续传？后端为什么不能直接把所有数据读到内存里？一步一步拆开之后你会发现大文件上传并不是魔法，而是一组很朴素的工程动作。不过，

目录

1. 为什么普通上传不适合大文件
2. 大文件上传的主要思路
3. 本项目实现了哪些能力
4. 整体流程图
5. 再看前端第一步先，选择文件并切片
6. 从前端接下来来看，用 Web Worker 计算文件 hash
7. 说到前端然后，查询服务端状态，实现秒传和断点续传
8. 说到前端第四步，用 XHR 上传分片并显示实时进度
9. 至于前端第五步，并发上传、暂停、继续和失败重试
10. 后端第一步先这方面。接口设计
11. 后端接下来的观点是，用 Busboy 流式接收分片
12. 从后端然后来看，按 hash 存储分片和最终文件
13. 至于后端第四步，合并分片，并保证合并过程可靠
14. 页面状态和分片状态怎么设计
15. 完整上传流程走一遍
16. 初学者常见问题
17. 这套方案还能怎么调整

. 为什么普通上传不适合大文件

User Pain Point： 使用者往往只看到一个单一进度条，却不知道到底是网络卡住还是服务器忙碌，导致失望与焦虑。

我们先想一个最简单的上传方式。使用者选择一个文件，前端把整个文件塞进

const formData = new FormData;formData.append;await fetch，

如果文件只有几十 KB 或几 MB，这样做当然没问题。很多头像上传、图片上传、普通表单附件都是这么做。

当文件变成 GB 时问题就开始出现了：

- 上传时间太长： 网络稍慢，一个大文件可能要传几分钟甚至几十分钟。中途使用者切换网络、关闭页面或电脑休眠都可能导致失败。老实说，- 失败成本太高： 如果你已经传了 %。结果最终网络抖了一下失败了。普通上传往往只能从头再来已传的数据全白费。- 使用者看不到细节： 使用者只看到一个模糊进度条，对“第几段成功”或“哪一段失败”毫无概念。- 后端压力过大： 若后端一次性读完整个请求体再写磁盘，多并发时容易把内存打爆。*以上痛点让使用者体验极差，也让运维成本飙升！*

大文件上传主要不是“怎么把一个文件传上去”，而是解决一系列工程问题：

- 上传失败后不要从头再传；使用者暂停可以继续，页面刷新也能找回已完成部分；同一份内容已存在时可秒传；前端能显示真实进度，后端能稳定处理大文件，不轻易占满内存。

这就是我们为何要做“分片上传”。想象一下搬箱子——拆成小箱子比一次搬巨箱安全得多。

. 大文件上传的主要思路

User Pain Point： 传统单次提交让人感觉“一次性操作”。但在真实网络环境下常常卡死或崩溃，让开发者抓狂。

主要思路可以一句话概括：

"前端把大文件切成很多小分片。一一或并发地发送给后端，后端逐个保存这些分片，并在全部齐全时按顺序合并成原始文件。"

但真正好用还需要补几个关键能力：

- 文件唯一标识    . - 分片编号    . - 上传前查询状态    . - 上传过程可控   . - 后台流式处理    ..
.

. 本项目实现了哪些能力

- 文件按 MB 切片 - Web Worker + spark-md5 计算 MD5 - 用 hash 做唯一标识 - /api/upload/status 查询服务状态 - 秒传 / 缺失分片补充 - XMLHttpRequest 实时进度反馈 - 并发数可调节 - 暂停/继续/重试机制 - 单个分块最多自动重试 X 次 - 页面展示哈希计算进度与总览 - 后台 Busboy 流式接收 - 分块按 chunks//.part 存储 - 合併时写 .tmp 再 rename 确保完整性 ... …等等，

. 整体流程图

• 使用者选择 → 获取 File 对象 • 前面根据固定大小切块 • Web Worker 按块读取算 MD5 • 根据 Hash 请求 /status 判断是否秒/断点 • 缺失块逐个 Upload 并实时绘制进度 • 所有块完成 → 调用 merge 合併 • 完成 → 刷新列表展示结果

. 前端第一步先：选择 & 切片

• File 对象为特殊 Blob。可 slice 截取区间 • 定义 CHUNK_SIZE = MB • 根据 size 和 CHUNK_SIZE 切出若干 chunk • getChunkSize 为最终一块校正尺寸 • 为每个 chunk 创建 ChunkItem 状态对象 { index,size,progress,retries,status } • ChunkStatus 可为 pending|uploading|success|retrying|failed|skipped • 明确状态方便队列调度与 UI 展示

. 接下来：Web Worker 算 MD5 哈希

• 主线程创建 worker： js const worker = new Worker,{type:'module'});• worker.onmessage 接收 progress 与 done js worker.onmessage = e=>{ const p=e.data;if setHashProgress;怎么说呢，if{ resolve;} } • worker 内部循环读取每块 buffer 并 append 到 spark-md5，接下来 postMessage progress。按理说，*痛点* ：主线程算哈希会卡顿。让按钮无反应甚至页面冻结——**Web Worker** 把耗时任务移到后台解决。其实，

---

. 然后：查询服务器状态。实现秒/断点续传

• GET /api/upload/status?fileHash=... • server 检查 final file 是否已存在 → 秒传 • 若未完成，再列出已有 chunk -> 返回 uploadedChunks • 前面返回应答决定：
• 已完整 -> 跳过 Upload 步骤；
• 部分已送 -> 跳过已存在 chunk，只补齐缺失部分。

痛点 ：每次手动重新 Upload 都浪费时间且易错——通过预查询减少重复工作。

---

. 第四步：XHR 上传单个 chunk 并实时跟踪

js function uploadChunkByXhr{ return new Promise=>{ const start=item.index*CHUNK_SIZE;说起来，const end=Math.min;const form=new FormData;form.append，…・真正发送的是 `currentFile.slice` ——仅该 block 的字节。・每个请求携带 fileHash 与 chunkIndex，让 server 知道保存位置。不过，・xhr.upload.onprogress 给出 `event.loaded` — 实时更新此 block 与总 progress。*痛点* ：fetch 无法获得精确 upload progress → XHR 必不可少。

---

. 第五步：并发控制 + 暂停/继续 + 重试

- 并发数滑杆范围 默认4。

• “任务队列 + worker 函数”模式不断拉取 pendingQueue 中 nextChunk 且 await uploadChunkWithRetry。

• pauseUpload 把 pausedRef=true 并 xhr.abort 所有正在请求。

• resumeUpload 查询 status，只补齐缺失 block。

• MAXRETRYCOUNT=6。每次失败延迟指数退避，直至达到上限才 mark failed。说起来，

痛点 ：网络波动频繁导致大量重连—退避机制平衡速度与稳定性。

---

. 后段第一部：接口设计简述

方法	方法	作用
GET	/api/health
GET	/api/upload/status
POST	/api/upload/chunk
POST	/api/upload/merge
GET	/api/files

---

status 接口

js const existingFile = await getMergedFile;if{sendJson} else{ const uploadedChunks = await listUploadedChunks; sendJson，}

chunk 接口

---

merge 接口

---

---

从后段第二部来看，Busboy 流式接收

js import busboy from 'busboy';export function readMultipartChunk{ return new Promise=>{ const fields={};const bb=new busboy({ headers:req.headers。limits:{files:1,fileSize:1024*1024*200},});bb.on=>fields=val);bb.on=>{ if{stream.resume;return，} onChunk;})，req.pipe;}) }

• Busboy 不会把整个 multipart 全部读入内存。而是直接提供 stream，可边写磁盘。

---

存储结构

server/storage/ ├─chunks/ │ └─/ // 临时目录。每份对应 hash │ ├─0.part // 按索引命名 │ ├─1.part ... │ └─N.part └─files/ └─.suffix // 最终合併后的原始 名 └─.json // 元数据 JSON

• 同一份内容无论命名为何，都落到同一目录 => 避免重复存储。其实，

• .tmp 写临时再 rename 防止半成品留存。

---

合併逻辑

``js for{ if) missing.push;} if throw {msg:${missing.length} 个缺失`,statusCode:400};

const tempPath=${finalPath}.tmp;const out=createWriteStream;// 顺序读取 .part 写入 out，end:false 防止 auto close。// 完整写完 -> rename await rename;

合併鎖

js const merging=new Set;if) throw {msg:'正在合併中...',statusCode:409};merging.add，// ...after merge finished remove from set...

---

页面阶段与 Chunk 状态

ts type UploadPhase ='idle'|'hashing'|'checking'|'uploading'|'paused'|'merging'|'done'|'error';type ChunkStatus ='pending'|'uploading'|'success'|'retrying'|'failed'|'skipped';

每个阶段对应 UI 提示，如 hashing 显示 “计算哈希…”，error 显示错误信息。

---

完整流程演练

1️⃣ 选择 → File 对象 & 初始化 ChunkItem 列表 若 file.size =100MB 且 CHUNK_SIZE=10MB，则创建10 个 Pending

2️⃣ 开始 → phase=hashing → WebWorker 开始计 MD5

- 显示 “计算哈希 …” 百帧更新

✅ 完成 ⇒ 得到 eaf61ae66c4fb863053f0b892abb258c

⚙️ 查询 /api/upload/status?fileHash=eaf61...

📦 响应 若未存在且没有任何 .part => shouldUpload:true

⚙️ 逐块 Upload via XHR ➜ 实时更新每 Block 与总 Progress

🤝 暂停 ➜ abort 所有 XHR，保留已成功 .part

🚀 继续 ➜ /status 检查缺失 Block。仅补齐其余

🔄 重试 如某 Block 超时 -> 自动 retry up to MAXRETRYCOUNT

🛠️ Merge 请求 /api/upload/merge -> Backend 检查齐全 -> 写 .tmp ➜ rename 成最终 file 🎉

📋 最终页面刷新 -> 展示 “已完成” 与下载链接

---

初学者常见疑问 & 痛点评价

问题	痛点	解答
为什么不能仅靠名称判断？	名称易变导致误判	用内容 Hash 更稳妥
MD5 会冲突吗？	理论上可能，但概率极低	常规业务足够安全。可选 SHA 系列
为什么放 WebWorker 算哈希？	主线程卡顿导致 UI 无响应	背景线程保持界面流畅
为何不用 fetch 上报进度？	fetch 无 onprogress 支持	XHR 提供精细控制
为什么使用 Busboy 而非标准解析器？	标准解析一次性读完内存巨大	Busboy 能流式处理降低峰值内存
暂停之后还能恢复吗？	已成功 .part 保持在服务侧	下一轮 status 查询即可恢复
页面刷新的恢复能力有限怎么办？	浏览器不允许持久 File 对象	可将最近一次记录保存在 localStorage。仅提示检测续签

---

性能进一步提高方向

1️⃣ 引入 User/Auth，以区分不同使用者的数据权限。2️⃣ 将 metadata 存于数据库而非 JSON 文件，以便更高效查询。3️⃣ 清理过期 .part 临时目录以节省硬盘空间。4️⃣ 将最终 file 放至对象存储 S3/Oss/Cos，只留签名与元数据。5️⃣ Redis 或 DB 锁替代内存 Set，支持多实例部署。6️⃣ 并发率，根据实际网络状况自适配。7️⃣ 支持 SHA‑256 或 SHA‑512，以兼顾安全需求。8️⃣ 多任务队列支持同时管理多个 File 的 Upload Flow。9️⃣ 支持目录递归压缩批量导入。🔟 自动回滚缺失 Block 并提醒使用者手动修复错误情况。

---

User Pain Points 汇总:

• 单次提交让人焦虑与等待；按理说，
• 大量网络波动导致频繁重连；
• 页面无法精准显示哪一步卡住；说起来，
• 内存暴涨致服务崩溃；
• 未实现秒/断点续传浪费时间；

A solution that solves all:

1. 切割: 把巨型 파일 拆成小碎粒；
2. 唯一标识: 用内容 Hash 防止误判；
3. 预检: status 接口决定秒或断点；
4. 实时反馈: XHR onprogress 展示细腻 Progress；
5. 容错: 自动重试 + 暂停恢复；怎么说呢，
6. 后台友好: Busboy 流式写 disk。无需一次性读全体，
7. 安全拼装: 按顺序拼接 .tmp 再 rename 保证完整；

只记住这个链路：

选择→切割→算 Hash→查询→送缺失→合併→完成!

这样就能清晰讲解“大 文件 上传”的全部技术细节。也能快速定位遇到的问题所在——无论是 UX 卡顿还是服务器崩溃，都有对应方法！

祝你玩转大型附件！🚀