大文件分片上传原理与工程实践：可靠性优先的上传架构-开发者社区

1. 什么是大文件分片上传：不是“传得快”，而是“传得稳、传得全、传得可控”

你有没有遇到过这样的场景：在某个系统里点下“上传”按钮，选中一个2GB的工程视频、一个800MB的医学影像数据包，或者一个1.5GB的CAD三维装配体——进度条刚爬到3%，页面突然弹出“网络错误”或“请求超时”，刷新重试？再试一次，又卡在12%；换浏览器，还是失败；最后只能把文件压缩、拆成十几个小包，挨个上传，再手动在后端拼接……这种体验，不是用户操作不对，而是系统底层压根没为“大文件”设计过上传通路。

大文件分片上传，说白了，就是把一个原本“一口吞不下”的庞然大物，切成若干个“能一口咽下去”的标准小块（比如每块5MB），让每个小块独立走一遍HTTP请求流程：校验、传输、确认。传完所有小块后，再由服务端按顺序把它们严丝合缝地“缝”回原样。它解决的从来不是“速度问题”，而是可靠性、容错性、用户体验和资源调度这四个硬骨头。

我做过不下二十个涉及文件上传的项目，从某高校实验室的显微图像采集平台，到某制造企业的设备IoT日志归档系统，再到某内容平台的创作者高清素材库。凡是单文件超过100MB的，无一例外都必须上分片——不是为了炫技，是被现实逼出来的。因为真实网络环境根本不像实验室里那么理想：手机切4G/5G时信号抖动、Wi-Fi穿墙后带宽骤降、公司防火墙对长连接的主动中断、甚至用户自己手滑关了浏览器标签页……这些都不是Bug，是常态。而传统<input type="file">直传方式，一旦中断，就得从头再来，用户时间、服务器带宽、CDN流量，全在为一次失败买单。

所以，当你看到“大文件分片上传”这个标题，脑子里第一反应不该是“怎么切片”，而应该是：“我的用户会在什么环境下传？传什么类型文件？失败后他们愿不愿意重试？后端能不能扛住并发小块写入？断点续传的元数据存在哪儿才不丢？”——这些才是决定方案成败的隐性门槛。它不是一个前端JS库调个API就完事的“功能”，而是一整套前后端协同的状态管理协议。下面我们就一层层剥开它的筋骨。

2. 整体架构设计与核心思路拆解：为什么非得分片？为什么不能只靠前端？

2.1 分片不是选择题，是必答题：三个绕不开的硬约束

很多新手会问：“我用XMLHttpRequest设置超时时间长一点，再加个重试，是不是也能传大文件？”实测下来，这条路在生产环境走不通。原因有三，且每一个都致命：

HTTP协议层限制：主流Web服务器（如Nginx、Apache）默认对单次请求体（request body）大小设限。Nginx默认是1MB，超出直接返回413 Request Entity Too Large。你当然可以改client_max_body_size 2048m;，但这就把风险全转嫁给服务器——一个恶意用户上传20GB垃圾文件，瞬间吃光磁盘IO和内存，导致整个服务雪崩。分片则让每个请求体稳定在几MB，完全落在安全水位线内。
浏览器内存与稳定性瓶颈：前端读取大文件依赖FileReader或Blob.slice()。当文件达2GB时，FileReader.readAsArrayBuffer(file)会尝试将整个文件载入内存。在低端安卓机或旧版Safari上，极易触发OutOfMemoryError，页面直接崩溃。而分片只需每次处理5~10MB的Blob切片，内存占用恒定在20MB以内，毫无压力。
零容错即零可用：这是最反直觉但最关键的一点。用户上传失败后，90%以上不会主动重试——他们要么放弃，要么换平台。而分片天然支持断点续传：传到第17块失败，下次上传时先向服务端查询“我已经成功传了哪几块？”，然后只补传第18块及之后的。用户感知是“继续上传”，而不是“重新开始”。某在线教育平台上线分片后，1GB课程视频上传成功率从61%跃升至99.2%，客服咨询量下降76%，这就是真实收益。

提示：分片上传的本质，是用“空间换时间、用复杂度换鲁棒性”。它把一个高风险的原子操作，拆解为一组低风险的幂等操作。每一小块上传都是独立事务，失败不影响其他块，重试成本趋近于零。

2.2 前后端职责必须划清：谁管切片？谁管合并？谁管状态？

一个常被忽视的坑是：把分片逻辑全堆在前端。结果上线后发现，用户A传到一半关机，三天后回来接着传，系统却提示“文件已过期”；用户B用两台设备同时上传同一文件，后端把块混在一起拼出了乱码……这些都不是代码bug，是职责错配。

我们团队沉淀出一套被验证有效的分工模型：

前端只做三件事：
1. 按固定大小（如5MB）将File对象切片为Blob数组；
2. 为每个切片生成唯一标识（推荐file_id + chunk_index + total_chunks哈希）；
3. 并发上传切片，携带chunk_index、total_chunks、file_name、file_hash（全文件MD5）等元数据。
后端必须承担四重责任：
1. 会话管理：为每次上传创建唯一upload_id，关联file_name、file_hash、total_chunks、expire_time（建议24小时）；
2. 块级校验：接收切片时，校验chunk_index是否越界、file_hash是否匹配、该块是否已存在（防重复提交）；
3. 状态持久化：将“upload_id下哪些块已接收”存入Redis（高性能）或数据库（强一致性），而非内存；
4. 合并调度：当received_chunks == total_chunks时，触发异步合并任务，用cat命令（Linux）或fs.appendFile（Node.js）按序拼接，并生成最终文件URL。

这个分工的核心逻辑是：前端是执行者，后端是裁判员和记分员。前端不保存任何状态，所有决策权交给后端。这样即使用户刷新页面、切换设备，只要带着upload_id回来，就能无缝续传。

2.3 为什么不用WebSocket？为什么不用WebRTC？

常有人提议用更“先进”的协议替代HTTP分片。实测结论很明确：在绝大多数业务场景下，这是过度设计。

WebSocket确实能实现双向实时通信，但它的优势在于“服务端主动推送”，而上传是典型的“客户端单向灌入”。为上传单独建WS连接，反而增加了连接管理复杂度（心跳、重连、鉴权），且CDN、WAF等中间件对WS支持远不如HTTP成熟，故障排查难度指数级上升。
WebRTC的DataChannel理论上带宽更高，但它需要P2P打洞，在企业内网、校园网等NAT严格的环境下，连接成功率低于40%。某高校项目曾尝试，最终因30%的学生无法建立通道而回滚。

HTTP分片的真正优势在于极致的兼容性与可观察性：它跑在标准80/443端口，能穿透所有防火墙；每个请求都是标准HTTP POST，可以用Chrome DevTools逐帧调试；Nginx日志里清晰记录每个块的耗时、状态码；Prometheus能直接抓取/metrics暴露的上传成功率指标。在工程落地中，“能被所有人看懂”比“技术参数漂亮”重要十倍。

3. 核心细节解析与实操要点：从切片策略到哈希校验，一个都不能少

3.1 切片大小怎么定？5MB不是玄学，是算出来的

网上教程千篇一律写“切片5MB”，但没人告诉你为什么。其实这是一个需要平衡三组矛盾的计算题：

影响因素	过小（如512KB）	过大（如50MB）	黄金区间（5~10MB）
HTTP请求数量	2GB文件需4000+请求 → TCP握手、TLS协商开销巨大，首字节延迟高	2GB仅需40请求 → 并发数低，带宽利用率不足	2GB约200请求 → 并发可控，延迟与吞吐均衡
内存占用	每次处理0.5MB，内存友好	单次加载50MB Blob，低端机OOM风险高	5MB在所有现代浏览器中均安全
断点续传粒度	失败后重传0.5MB，恢复快但网络往返多	失败后重传50MB，用户等待感强	5MB符合“心理阈值”：用户觉得“就几秒”

我们团队的实测数据：在4G网络（平均15Mbps）下，5MB切片的平均单块上传耗时为2.8秒，标准差0.6秒；而50MB切片耗时28秒，标准差飙升至4.3秒。这意味着后者有更高概率撞上网络抖动窗口。

实操心得：切片大小应作为可配置项暴露给业务方。例如，面向移动端的App可设为2MB（适配弱网），面向企业内网的桌面端可设为10MB（压榨千兆带宽）。我们的通用方案是：前端读取navigator.connection.effectiveType（如'4g'、'wifi'），动态调整CHUNK_SIZE。

3.2 文件唯一标识怎么做？MD5够用吗？SHA256要不要上？

文件去重和完整性校验，是分片上传的“安全阀”。常见错误是只用文件名判断——同名文件不同内容怎么办？或者只传lastModified时间戳——用户改了文件又改回去呢？

我们采用三级校验体系：

前端预计算全文件Hash：
使用SparkMD5（轻量、支持流式计算）在浏览器端计算整个文件的MD5。关键技巧：不要用FileReader.readAsArrayBuffer()一次性读全，而要用分块读取+增量计算。伪代码如下：

const spark = new SparkMD5.ArrayBuffer(); const file = document.querySelector('input[type=file]').files[0]; const chunkSize = 2 * 1024 * 1024; // 2MB chunks let offset = 0; const readChunk = () => { const reader = new FileReader(); reader.onload = e => { spark.append(e.target.result); offset += chunkSize; if (offset < file.size) { readNextChunk(); } else { const hash = spark.end(); // 得到全文件MD5 startUpload(hash); } }; const blob = file.slice(offset, offset + chunkSize); reader.readAsArrayBuffer(blob); };

这样即使2GB文件，内存峰值也仅2MB，且计算过程可取消（用户点击取消上传时）。

后端二次校验：
合并完成后，用crypto.createHash('md5')在服务端重新计算最终文件MD5，与前端传来的file_hash比对。不一致则删除文件，返回500 Internal Error并告警。
业务层语义去重（可选）：
对于用户反复上传同一份设计稿的场景，可将file_hash作为数据库唯一索引。当检测到重复时，直接返回已有文件URL，节省存储。

注意：MD5在密码学上已被破解，但用于文件完整性校验（防传输损坏、非恶意篡改）依然足够可靠，且计算速度快。若业务涉及金融级安全要求，可升级为SHA256，但前端计算耗时增加3倍，需权衡。

3.3 并发控制怎么做？10个请求一起发，服务器会不会炸？

前端并发上传是提升速度的关键，但盲目开高并发等于自毁长城。我们踩过的坑包括：Nginx报503 Service Unavailable、Node.js进程CPU 100%卡死、MySQL连接池耗尽。

解决方案是双层限流：

前端层：固定窗口并发数
使用Promise.allSettled()配合队列。例如维持4个并发槽位：

const uploadQueue = []; const MAX_CONCURRENT = 4; for (let i = 0; i < chunks.length; i++) { uploadQueue.push(() => uploadChunk(chunks[i], i)); } while (uploadQueue.length > 0) { const batch = uploadQueue.splice(0, MAX_CONCURRENT); await Promise.allSettled(batch.map(fn => fn())); }

后端层：按upload_id限流
在Nginx配置中，对/api/upload/chunk路径启用limit_req：
```
limit_req_zone $http_upload_id zone=per_upload:10m rate=5r/s; location /api/upload/chunk { limit_req zone=per_upload burst=10 nodelay; proxy_pass http://backend; }
```
这表示：每个upload_id每秒最多处理5个块请求，突发允许10个。既防止单个大文件霸占全部资源，又保障正常上传流畅。

实测数据：4并发时，2GB文件上传总耗时比单并发缩短68%，而服务器负载平稳在CPU 45%、内存60%。开到8并发，耗时仅再降7%，但错误率上升至3.2%（主要是Nginx503）。

4. 实操过程与核心环节实现：从零搭建一个可运行的分片上传Demo

4.1 前端切片与上传模块（React Hooks实现）

我们以React为例，封装一个useChunkUpload自定义Hook，屏蔽底层复杂度：

// hooks/useChunkUpload.ts import { useState, useCallback } from 'react'; import SparkMD5 from 'spark-md5'; interface UploadProgress { uploaded: number; // 已上传块数 total: number; // 总块数 percent: number; // 进度百分比 } interface UploadResult { fileId: string; url: string; } export const useChunkUpload = (options: { apiUrl: string; chunkSize?: number; // 默认5MB }) => { const [progress, setProgress] = useState<UploadProgress>({ uploaded: 0, total: 0, percent: 0 }); const [isUploading, setIsUploading] = useState(false); const calculateChunks = useCallback((file: File, chunkSize: number) => { const chunks: Blob[] = []; for (let i = 0; i < file.size; i += chunkSize) { chunks.push(file.slice(i, i + chunkSize)); } return chunks; }, []); const computeFileHash = useCallback((file: File): Promise<string> => { return new Promise((resolve, reject) => { const spark = new SparkMD5.ArrayBuffer(); const fileReader = new FileReader(); fileReader.onload = (e) => { if (e.target?.result) { spark.append(e.target.result as ArrayBuffer); resolve(spark.end()); } }; fileReader.onerror = reject; fileReader.readAsArrayBuffer(file); }); }, []); const upload = useCallback(async (file: File): Promise<UploadResult> => { if (!file) throw new Error('No file selected'); setIsUploading(true); const chunkSize = options.chunkSize || 5 * 1024 * 1024; const chunks = calculateChunks(file, chunkSize); const totalChunks = chunks.length; const fileHash = await computeFileHash(file); // Step 1: 初始化上传会话 const initRes = await fetch(`${options.apiUrl}/init`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ fileName: file.name, fileSize: file.size, fileHash, totalChunks, }), }); const { uploadId } = await initRes.json(); // Step 2: 并发上传所有块 const uploadPromises = chunks.map((chunk, index) => uploadChunk({ chunk, index, totalChunks, uploadId, fileHash, apiUrl: options.apiUrl, }) ); try { await Promise.all(uploadPromises); setProgress({ uploaded: totalChunks, total: totalChunks, percent: 100 }); // Step 3: 合并文件 const mergeRes = await fetch(`${options.apiUrl}/merge`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ uploadId }), }); const result = await mergeRes.json(); return result; } catch (err) { console.error('Upload failed:', err); throw err; } finally { setIsUploading(false); } }, [calculateChunks, computeFileHash, options.apiUrl]); return { upload, progress, isUploading, }; }; // utils/uploadChunk.ts export const uploadChunk = async ({ chunk, index, totalChunks, uploadId, fileHash, apiUrl, }: { chunk: Blob; index: number; totalChunks: number; uploadId: string; fileHash: string; apiUrl: string; }) => { const formData = new FormData(); formData.append('chunk', chunk, `chunk_${index}`); formData.append('chunkIndex', index.toString()); formData.append('totalChunks', totalChunks.toString()); formData.append('uploadId', uploadId); formData.append('fileHash', fileHash); const res = await fetch(`${apiUrl}/chunk`, { method: 'POST', body: formData, }); if (!res.ok) { const error = await res.json(); throw new Error(`Chunk ${index} failed: ${error.message}`); } };

使用时极其简洁：

// components/FileUploader.tsx import { useChunkUpload } from '../hooks/useChunkUpload'; const FileUploader = () => { const { upload, progress, isUploading } = useChunkUpload({ apiUrl: 'https://your-api.com', chunkSize: 5 * 1024 * 1024, }); const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => { const file = e.target.files?.[0]; if (file) { upload(file) .then(result => console.log('Upload success:', result)) .catch(err => console.error('Upload error:', err)); } }; return ( <div> <input type="file" onChange={handleFileChange} disabled={isUploading} /> {isUploading && ( <div> <progress value={progress.uploaded} max={progress.total} /> <span>{Math.round(progress.percent)}%</span> </div> )} </div> ); }; export default FileUploader;

4.2 后端服务端实现（Node.js + Express + Redis）

后端采用Express框架，用Redis存储上传状态（高性能、支持过期），文件存储在本地磁盘（生产环境应替换为OSS/S3）：

// server.js const express = require('express'); const multer = require('multer'); const crypto = require('crypto'); const fs = require('fs').promises; const path = require('path'); const Redis = require('redis'); const app = express(); const redisClient = Redis.createClient(); const UPLOAD_DIR = path.join(__dirname, 'uploads'); // 确保上传目录存在 fs.mkdir(UPLOAD_DIR, { recursive: true }); // 存储配置 const CHUNK_DIR = path.join(UPLOAD_DIR, 'chunks'); const FINAL_DIR = path.join(UPLOAD_DIR, 'final'); fs.mkdir(CHUNK_DIR, { recursive: true }); fs.mkdir(FINAL_DIR, { recursive: true }); // Multer配置：仅处理chunk上传，不限制大小（由Nginx控制） const storage = multer.diskStorage({ destination: (req, file, cb) => { cb(null, CHUNK_DIR); }, filename: (req, file, cb) => { const { uploadId, chunkIndex } = req.body; cb(null, `${uploadId}_${chunkIndex}`); } }); const upload = multer({ storage }); // 1. 初始化上传会话 app.post('/init', async (req, res) => { try { const { fileName, fileSize, fileHash, totalChunks } = req.body; const uploadId = crypto.randomUUID(); const expireTime = 24 * 60 * 60; // 24小时 // 写入Redis：uploadId -> {fileName, fileSize, fileHash, totalChunks, uploadedChunks: []} await redisClient.setex( `upload:${uploadId}`, expireTime, JSON.stringify({ fileName, fileSize, fileHash, totalChunks, uploadedChunks: [], createdAt: Date.now(), }) ); res.json({ uploadId }); } catch (err) { res.status(500).json({ error: err.message }); } }); // 2. 接收单个切片 app.post('/chunk', upload.single('chunk'), async (req, res) => { try { const { uploadId, chunkIndex, totalChunks, fileHash } = req.body; const chunkIndexNum = parseInt(chunkIndex, 10); const totalChunksNum = parseInt(totalChunks, 10); // 校验uploadId是否存在 const uploadInfoStr = await redisClient.get(`upload:${uploadId}`); if (!uploadInfoStr) { return res.status(400).json({ error: 'Invalid uploadId' }); } const uploadInfo = JSON.parse(uploadInfoStr); // 校验chunkIndex范围 if (chunkIndexNum < 0 || chunkIndexNum >= totalChunksNum) { return res.status(400).json({ error: 'Invalid chunk index' }); } // 校验fileHash一致性 if (uploadInfo.fileHash !== fileHash) { return res.status(400).json({ error: 'File hash mismatch' }); } // 检查该块是否已存在（幂等） const chunkPath = path.join(CHUNK_DIR, `${uploadId}_${chunkIndex}`); if (await fs.access(chunkPath).then(() => true).catch(() => false)) { // 已存在，直接返回成功 res.json({ success: true, message: 'Chunk already exists' }); return; } // 移动临时文件到目标位置 const tempPath = req.file.path; await fs.rename(tempPath, chunkPath); // 更新Redis中的已上传块列表 uploadInfo.uploadedChunks.push(chunkIndexNum); await redisClient.setex( `upload:${uploadId}`, 24 * 60 * 60, JSON.stringify(uploadInfo) ); res.json({ success: true }); } catch (err) { res.status(500).json({ error: err.message }); } }); // 3. 合并所有切片 app.post('/merge', async (req, res) => { try { const { uploadId } = req.body; const uploadInfoStr = await redisClient.get(`upload:${uploadId}`); if (!uploadInfoStr) { return res.status(400).json({ error: 'Invalid uploadId' }); } const uploadInfo = JSON.parse(uploadInfoStr); // 检查是否所有块都已上传 if (uploadInfo.uploadedChunks.length !== uploadInfo.totalChunks) { return res.status(400).json({ error: 'Not all chunks uploaded', missing: uploadInfo.totalChunks - uploadInfo.uploadedChunks.length }); } // 按序读取所有块并拼接 const finalFilePath = path.join(FINAL_DIR, `${uploadId}_${uploadInfo.fileName}`); const writeStream = fs.createWriteStream(finalFilePath); for (let i = 0; i < uploadInfo.totalChunks; i++) { const chunkPath = path.join(CHUNK_DIR, `${uploadId}_${i}`); const chunkData = await fs.readFile(chunkPath); await writeStream.write(chunkData); } await writeStream.end(); // 计算最终文件MD5 const finalFileData = await fs.readFile(finalFilePath); const finalHash = crypto.createHash('md5').update(finalFileData).digest('hex'); if (finalHash !== uploadInfo.fileHash) { await fs.unlink(finalFilePath); return res.status(500).json({ error: 'Final file hash mismatch' }); } // 清理临时块 for (let i = 0; i < uploadInfo.totalChunks; i++) { const chunkPath = path.join(CHUNK_DIR, `${uploadId}_${i}`); await fs.unlink(chunkPath).catch(() => {}); } // 返回可访问URL const fileUrl = `/files/${uploadId}_${uploadInfo.fileName}`; res.json({ fileId: uploadId, url: fileUrl, size: uploadInfo.fileSize, name: uploadInfo.fileName, }); } catch (err) { res.status(500).json({ error: err.message }); } }); // 静态文件服务 app.use('/files', express.static(FINAL_DIR)); app.listen(3000, () => { console.log('Server running on http://localhost:3000'); });

4.3 Nginx关键配置：为分片上传保驾护航

没有Nginx的合理配置，再好的代码也撑不住真实流量。以下是生产环境必备配置：

# /etc/nginx/conf.d/upload.conf upstream backend { server 127.0.0.1:3000; } server { listen 80; server_name your-domain.com; # 关键：增大请求体限制（必须！） client_max_body_size 100M; # 单个chunk最大100MB，留足余量 # 关键：延长超时时间（分片上传耗时长） proxy_connect_timeout 300; proxy_send_timeout 300; proxy_read_timeout 300; send_timeout 300; # 关键：启用缓冲，避免大文件阻塞worker proxy_buffering on; proxy_buffer_size 128k; proxy_buffers 4 256k; proxy_busy_buffers_size 256k; # 关键：按upload_id限流，防止单用户打爆 limit_req_zone $http_upload_id zone=per_upload:10m rate=5r/s; location /api/upload/ { limit_req zone=per_upload burst=10 nodelay; proxy_pass http://backend; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } # 静态文件直出，不走Node.js location /files/ { alias /var/www/uploads/final/; expires 1h; add_header Cache-Control "public, immutable"; } }

注意：client_max_body_size必须大于单个chunk大小（如5MB），否则Nginx会在代理前就拒绝请求，后端根本收不到。我们通常设为100M，既满足需求，又防止单次恶意大请求。

5. 常见问题与排查技巧实录：那些文档里不会写的坑

5.1 典型问题速查表

问题现象	可能原因	排查命令/方法	解决方案
上传卡在99%，始终不完成	后端合并时`uploadedChunks.length !== totalChunks`，但Redis里显示已全传	`redis-cli get "upload:xxx"`查看JSON结构	检查前端是否漏传某块（如网络超时未捕获）、Redis是否因OOM被驱逐
同一文件多次上传，生成多个副本	前端未校验`file_hash`，或后端未启用去重	`ls -la uploads/final/ \| grep "xxx_hash"`	在`/init`接口中，先查Redis是否有相同`file_hash`的`uploadId`，有则直接返回
Chrome下上传速度极慢（<100KB/s）	浏览器对`FormData`中大Blob的序列化性能差	Chrome DevTools → Network → 查看每个chunk请求的`Time`	改用`fetch`+`ArrayBuffer`+`Uint8Array`手动构造二进制请求体（需后端配合解析）
Safari iOS上传失败，报`NotAllowedError`	iOS Safari对`FileReader`有严格限制，尤其后台tab	在`beforeunload`事件中保存进度到localStorage	前端监听`visibilitychange`，页面隐藏时暂停上传，恢复时续传
Nginx日志大量`503 Service Unavailable`	`limit_req`配置过严，或burst值太小	`tail -f /var/log/nginx/error.log \| grep "limiting requests"`	调大`burst`值，或改用`nodelay`（立即拒绝超限请求，不排队）

5.2 我踩过的三个深坑与独家解法

坑一：Redis内存泄漏，上传会话永不释放
现象：运行一周后，Redis内存暴涨至90%，INFO memory显示used_memory_human: 9.2G。排查发现upload:*键未自动过期。
原因：setex命令在Redis集群模式下，若key被重命名或迁移，过期时间可能丢失。
解法：双重保险——除setex外，在/merge成功后主动DEL upload:xxx；同时添加定时任务，每天凌晨扫描KEYS upload:*，对createdAt超24小时的key强制清理。

坑二：合并时文件损坏，MD5校验失败
现象：2GB文件合并后，服务端计算的MD5与前端不一致，概率约0.3%。
原因：Node.jsfs.writeFile在高并发下，对同一文件的多次append操作存在竞态，部分数据被覆盖。
解法：改用流式追加。不调用writeFile，而用createWriteStream并设置flags: 'a'（append），确保原子性：

const writeStream = fs.createWriteStream(finalFilePath, { flags: 'a' }); for (const chunkPath of chunkPaths) { const data = await fs.readFile(chunkPath); await writeStream.write(data); // write()是异步，但流内部保证顺序 } await writeStream.end();

坑三：用户上传超时后重试，后端收到重复块但未去重
现象：用户网络中断，30秒后重试，后端日志显示同一uploadId下chunk_5被写了两次，但Redis里uploadedChunks只存了一个5。
原因：前端重试时未加idempotency-key请求头，后端也未校验。
解法：引入幂等Key。前端每次上传块时，生成X-Idempotency-Key: ${uploadId}_${chunkIndex}_${timestamp}，后端用此Key在Redis中存一个idempotent:${key}标记，存在则跳过写入。这是支付系统级的严谨做法，对上传同样适用。

5.3 性能压测实录：200并发下，系统能扛多久？

我们用Artillery对上述Node.js服务进行压测（4核8G服务器，Redis单机）：

# test.yml config: target: 'http://localhost:3000' phases: - duration: 60 arrivalRate: 200 scenarios: - flow: - post: url: "/api/upload/init" json: fileName: "test.mp4" fileSize: 2147483648 # 2GB fileHash: "d41d8cd98f00b204e9800998ecf8427e" totalChunks: 400 - post: url: "/api/upload/chunk" multipart: chunk: "{{ filePath }}" chunkIndex: "{{ randomInt(0, 399) }}" totalChunks: "400" uploadId: "{{ jsonPath($, '$.uploadId') }}" fileHash: "d41d8cd98f00b204e9800998ecf8427e"

结果：