三亩地 三亩地SAN MU DI · CODE DIARY
交流投稿
ARTICLE DETAIL

日记详情

真实记录编程学习的某一天，欢迎挑你感兴趣的翻一翻。

首页/学习日记/日记详情

前端大文件分片上传与断点续传实战指南

发布时间：2026/8/11 6:51:43 三亩地 编程学习日记
前端大文件分片上传与断点续传实战指南

1. 大文件上传的前端挑战与技术选型

在Web应用开发中，文件上传是最基础的功能之一，但当文件尺寸超过100MB时，传统的表单上传方式就会暴露出各种问题。我曾在电商后台管理系统项目中，遇到过用户需要上传3GB以上设计稿的需求，当时用常规方法导致浏览器卡死、进度无法追踪、网络中断后重传困难等一系列问题。

大文件上传的核心痛点在于：

  • 内存压力：浏览器需要将整个文件加载到内存
  • 网络稳定性：长时间传输容易中断
  • 用户体验：缺乏进度反馈和暂停续传能力
  • 服务端限制：Nginx/Apache默认配置通常限制上传大小

目前主流的前端大文件上传方案主要有三种技术路线：

  1. 分片上传：将文件切割为多个小块并行上传
  2. 断点续传：记录已上传部分，支持从中断处继续
  3. 流式上传：通过Stream API逐步发送数据

经过实际项目验证，分片上传+断点续传的组合方案具有最佳的综合效益。下面以这个组合方案为例，详细讲解实现过程。

2. 前端分片上传的核心实现

2.1 文件分片处理

使用File API的slice方法进行分片是最可靠的方式。在我的实践中，分片大小需要权衡：

  • 过小（如1MB）：请求次数过多
  • 过大（如50MB）：失去分片意义

推荐公式：

分片大小 = Math.max(5, Math.min(50, 文件大小/(5*1024))) // 单位MB

具体实现代码：

const chunkSize = 5 * 1024 * 1024; // 5MB let start = 0; let end = Math.min(file.size, start + chunkSize); while (start < file.size) { const chunk = file.slice(start, end); // 上传逻辑... start = end; end = Math.min(file.size, start + chunkSize); }

2.2 分片上传控制

并行上传能提高速度，但需要控制并发量以避免浏览器限制。建议：

  • 普通PC：并发3-5个分片
  • 高性能设备：可提升到8-10个

实现并发控制的代码模式：

const maxConcurrent = 4; const uploading = new Set(); async function uploadChunk(chunk) { if (uploading.size >= maxConcurrent) { await new Promise(resolve => { const check = () => { if (uploading.size < maxConcurrent) resolve(); else setTimeout(check, 100); }; check(); }); } uploading.add(chunk.id); try { await doUpload(chunk); } finally { uploading.delete(chunk.id); } }

3. 断点续传的完整实现方案

3.1 服务端配合设计

断点续传需要服务端支持以下接口：

  1. /check检查已上传分片
  2. /upload上传分片
  3. /merge合并分片

典型的检查接口响应示例：

{ "exists": [1, 3, 5], "chunkSize": 5242880, "totalChunks": 42 }

3.2 前端状态管理

使用localStorage保存上传状态是常见做法，但要注意：

  • 不同浏览器可能有存储限制
  • 清除缓存会导致状态丢失

更健壮的方案是IndexedDB：

const dbPromise = indexedDB.open('uploadDB', 1); dbPromise.onupgradeneeded = (event) => { const db = event.target.result; db.createObjectStore('uploads', { keyPath: 'fileId' }); }; async function saveProgress(fileId, progress) { const db = await dbPromise; const tx = db.transaction('uploads', 'readwrite'); tx.objectStore('uploads').put({ fileId, progress }); }

4. 性能优化与异常处理

4.1 上传速度优化技巧

  1. 动态分片大小：根据网络质量调整

    let chunkSize = navigator.connection.downlink > 10 ? 10 * 1024 * 1024 : 5 * 1024 * 1024;

  2. 压缩分片：对图片/文本使用Pako等库压缩

    const compressed = pako.deflate(chunkData);

  3. Web Worker处理：将分片计算移出主线程

    // worker.js self.onmessage = (e) => { const chunk = e.data.file.slice(e.data.start, e.data.end); postMessage({ id: e.data.id, chunk }); };

4.2 错误处理策略

必须处理的典型错误场景：

  1. 网络中断：自动重试3次后暂停
  2. 服务端错误：记录错误分片最后重试
  3. 文件变更：检测文件最后修改时间

实现示例：

async function uploadWithRetry(chunk, retries = 3) { try { await uploadChunk(chunk); } catch (error) { if (retries > 0) { await new Promise(r => setTimeout(r, 1000)); return uploadWithRetry(chunk, retries - 1); } throw error; } }

5. 企业级方案进阶

5.1 秒传技术实现

通过文件hash值判断是否已存在：

async function calculateHash(file) { const buffer = await file.slice(0, 1024 * 1024).arrayBuffer(); const hashBuffer = await crypto.subtle.digest('SHA-256', buffer); return Array.from(new Uint8Array(hashBuffer)) .map(b => b.toString(16).padStart(2, '0')) .join(''); }

5.2 跨域上传方案

当CDN和API不同域时：

  1. 使用CORS预检请求
  2. 或通过后端代理上传

推荐配置：

location /upload { add_header 'Access-Control-Allow-Origin' '*'; add_header 'Access-Control-Allow-Methods' 'POST, OPTIONS'; add_header 'Access-Control-Allow-Headers' 'Content-Type'; if ($request_method = 'OPTIONS') { return 204; } }

5.3 大文件预览技术

在上传前预览大文件的技巧：

  1. 使用URL.createObjectURL生成临时链接
  2. PDF.js处理大PDF文件
  3. 视频使用<video>的preload="metadata"
function previewLargeImage(file) { return new Promise((resolve) => { const img = new Image(); img.onload = () => { URL.revokeObjectURL(img.src); resolve(img); }; img.src = URL.createObjectURL(file); }); }

6. 实际项目中的经验教训

在金融行业文档管理系统项目中，我们遇到几个关键问题：

  1. 内存泄漏：未及时释放File对象导致

    // 错误做法 const chunks = []; for (let i = 0; i < total; i++) { chunks.push(file.slice(start, end)); } // 正确做法 function getChunk(file, index) { return file.slice(start, end); }

  2. 进度计算误差：应该基于字节数而非分片数

    // 不准确 progress = uploadedChunks.length / totalChunks; // 准确 progress = uploadedBytes / totalBytes;

  3. 文件类型欺骗：必须验证实际文件类型

    async function checkFileType(file) { const header = await file.slice(0, 4).arrayBuffer(); const view = new DataView(header); const signature = view.getUint32(0, false).toString(16); return signatures[signature] || file.type; }

  4. 大文件Hash计算优化：抽样计算+Web Worker

    // 抽样2MB数据计算 const sampleSize = 2 * 1024 * 1024; const samples = [ file.slice(0, sampleSize/4), file.slice(file.size/2, file.size/2 + sampleSize/4), file.slice(file.size - sampleSize/2) ];

7. 现代浏览器的优化方案

7.1 使用Streams API

流式上传可以显著降低内存占用：

async function streamUpload(file) { const stream = file.stream(); const reader = stream.getReader(); while (true) { const { done, value } = await reader.read(); if (done) break; await uploadChunk(value); } }

7.2 Background Fetch API

后台持续上传即使页面关闭：

navigator.serviceWorker.ready.then(async (reg) => { const id = await reg.backgroundFetch.fetch('big-upload', [ new Request('/upload', { method: 'POST', body: file }) ], { title: '大文件上传中...', icons: [...], downloadTotal: file.size }); });

7.3 性能监测与自适应

根据设备性能调整策略：

const deviceMemory = navigator.deviceMemory || 4; // GB const concurrency = deviceMemory > 4 ? 6 : 3; const connection = navigator.connection || { effectiveType: '4g' }; const chunkSize = connection.effectiveType.includes('4g') ? 10 * 1024 * 1024 : 5 * 1024 * 1024;

8. 服务端最佳实践

8.1 分片存储方案

推荐目录结构：

/uploads/ temp_<fileId>/ chunk_001 chunk_002 ... merged/ final_file

8.2 合并分片优化

使用高效合并方法（Linux示例）：

# 比cat更快的合并方式 dd if=/dev/zero of=merged_file bs=1M count=0 seek=1024 # 预分配空间 for chunk in chunks/*; do dd if=$chunk of=merged_file bs=1M seek=$offset conv=notrunc offset=$((offset + $(stat -c%s $chunk)/1024/1024)) done

8.3 清理策略

建议实现：

  1. 超过24小时未完成的上传自动清理
  2. 成功合并后立即删除临时分片
  3. 定期扫描孤儿文件

9. 测试与监控

9.1 自动化测试方案

使用Cypress测试上传流程：

describe('大文件上传', () => { it('成功上传500MB文件', () => { cy.fixture('large-file.bin', 'binary') .then(Cypress.Blob.binaryStringToBlob) .then(blob => { cy.get('input[type=file]').attachFile({ fileContent: blob, fileName: 'test.bin', mimeType: 'application/octet-stream' }); cy.contains('上传成功').should('be.visible'); }); }); });

9.2 性能监控指标

关键监控点：

  1. 分片上传平均耗时
  2. 合并操作耗时
  3. 内存占用峰值
  4. 失败重试次数

实现示例：

const perfMetrics = { start: performance.now(), chunks: [], logChunk(id, size, duration) { this.chunks.push({ id, size, duration }); }, getStats() { return { totalTime: performance.now() - this.start, avgChunkTime: this.chunks.reduce((a,c) => a + c.duration, 0) / this.chunks.length, throughput: this.chunks.reduce((a,c) => a + c.size, 0) / (performance.now() - this.start) * 1000 }; } };

10. 安全防护措施

10.1 防恶意上传

关键防护点：

  1. 限制文件类型白名单
  2. 扫描文件内容（如ClamAV）
  3. 限制上传频率

Express中间件示例：

app.use('/upload', (req, res, next) => { const ip = req.ip; const count = uploadCounts[ip] || 0; if (count > 100) { return res.status(429).send('上传次数过多'); } uploadCounts[ip] = count + 1; next(); });

10.2 内容安全检查

使用WebAssembly进行前端预检：

// 加载wasm病毒扫描模块 const scanner = await WebAssembly.instantiateStreaming( fetch('/scanner.wasm') ); function checkFileSafety(file) { const buffer = await file.slice(0, 1024).arrayBuffer(); const result = scanner.exports.scan(new Uint8Array(buffer)); return result === 0; }

11. 跨平台解决方案

11.1 微信小程序方案

使用分片上传API：

wx.uploadFile({ url: 'https://example.com/upload', filePath: file.tempFilePath, name: 'file', formData: { chunkIndex: 0, totalChunks: 10 }, success(res) { console.log('分片上传成功', res); } });

11.2 React Native实现

使用react-native-fs和fetch：

import RNFS from 'react-native-fs'; const chunkSize = 5 * 1024 * 1024; const stats = await RNFS.stat(filePath); const totalChunks = Math.ceil(stats.size / chunkSize); for (let i = 0; i < totalChunks; i++) { const start = i * chunkSize; const end = Math.min(stats.size, start + chunkSize); const chunk = await RNFS.read(filePath, end - start, start, 'base64'); await fetch('https://example.com/upload', { method: 'POST', body: JSON.stringify({ index: i, data: chunk }) }); }

12. 未来趋势与替代方案

12.1 WebRTC点对点传输

适用于内网环境的大文件分享：

const pc = new RTCPeerConnection(); const dc = pc.createDataChannel('fileTransfer'); dc.onmessage = (event) => { // 处理接收到的分片 }; file.stream().pipeThrough(new TransformStream({ transform(chunk, controller) { dc.send(chunk); controller.enqueue(chunk); } }));

12.2 WebTransport协议

基于QUIC的新一代传输方案：

const transport = new WebTransport('https://example.com/upload'); await transport.ready; const writer = transport.datagrams.writable.getWriter(); await writer.write(new Uint8Array([...]));

12.3 服务端签名直传

前端获取签名后直传OSS：

async function directUpload(file) { const { signature, policy, host } = await getOssSignature(); const formData = new FormData(); formData.append('key', 'uploads/${filename}'); formData.append('policy', policy); formData.append('OSSAccessKeyId', 'your-key-id'); formData.append('signature', signature); formData.append('file', file); await fetch(host, { method: 'POST', body: formData }); }

在实际项目中，我发现大文件上传最关键的不仅是技术实现，更需要考虑异常场景的健壮性。曾经因为忽略了一个小细节——没有验证分片上传顺序，导致合并后的文件损坏。后来我们增加了分片校验机制：每个分片上传后返回其MD5值，合并前再次校验，彻底解决了这个问题。

编程学习 学习日记 实战经验
← 返回列表