码不停蹄

外观

大文件上传

约 3353 字大约 11 分钟

前端开发大文件上传

2025-10-14

在前端开发中，文件上传是常见需求，但当面对几十MB甚至GB级别的大文件（如视频、压缩包、设计源文件）时，传统的单文件上传方案会暴露出诸多问题：上传速度慢、容易中断、失败后需重新上传、占用带宽过高影响其他业务……

本文将系统梳理大文件上传的核心技术（分片上传、断点续传等），从原理拆解到实践要点，帮助掌握前端大文件上传的完整解决方案。

一、为什么需要“大文件上传”特殊方案？

在了解技术之前，我们先明确“传统单文件上传”的痛点——这正是大文件上传方案存在的意义：

  1. 上传中断风险高：大文件上传耗时久，一旦网络波动、页面刷新或浏览器崩溃，整个上传进程会直接失败，且无法恢复，只能重新上传，用户体验极差；
  2. 服务器压力大：单文件一次性发送到服务器，会导致服务器瞬间接收大量数据，可能触发内存溢出、请求超时等问题，尤其在多用户同时上传时，服务器负载会急剧升高；
  3. 带宽利用率低：单文件上传依赖单一HTTP连接，无法充分利用带宽资源，而大文件传输对带宽的“浪费”会更明显，导致上传速度远低于实际带宽上限；
  4. 进度反馈不精准：传统上传只能获取“整体进度”，无法细化到文件传输的具体阶段，用户无法判断上传是否“卡在中途”。

针对这些痛点，前端大文件上传的核心思路是：“拆分文件、分块传输、可续传、可校验”，而 分片上传 和 断点续传 是实现这一思路的两大核心技术。

二、核心技术1：分片上传（Chunked Upload）

分片上传是大文件上传的“基础”——它将一个大文件切割成多个小的“分片（Chunk）”，再通过多个HTTP请求分别将这些分片上传到服务器，最后由服务器将所有分片合并成原始文件。

1. 分片上传的核心原理

整个流程可分为“前端切割 → 分片上传 → 服务器合并”三步，具体逻辑如下：

  • Step 1：前端切割文件
    利用浏览器的File对象和Blob.slice()方法，将大文件按固定大小（如5MB/10MB，可根据业务调整）切割成多个分片。
    例如：一个20MB的文件，按5MB分片，会切割成4个分片，每个分片都有唯一标识（如“文件ID+分片索引”），方便后续服务器识别和合并。

  • Step 2：分片上传到服务器
    前端通过AJAX或Fetch API，将每个分片作为独立的请求发送到服务器。为了确保服务器能正确合并，每个请求需要携带关键信息：

    • 文件唯一标识（如通过文件MD5、文件名+文件大小生成，确保同一文件的分片归属一致）；
    • 分片索引（如0、1、2、3，标记分片的顺序）；
    • 总分片数（如4，方便服务器判断是否接收完所有分片）；
    • 分片文件本身（通过FormData提交）。

  • Step 3：服务器合并分片
    服务器接收每个分片后，会根据“文件唯一标识”将分片暂存到指定目录（如以文件ID命名的文件夹），并记录已接收的分片索引。当所有分片都接收完成后，服务器会按分片索引顺序将所有分片合并成原始文件，最后删除暂存的分片文件。

2. 前端分片上传的关键代码示例

以下是基于原生JavaScript的分片上传核心逻辑（实际项目中需结合错误处理、进度反馈等）：

// 1. 配置参数
const CHUNK_SIZE = 5 * 1024 * 1024; // 分片大小：5MB
const fileInput = document.getElementById('file-input'); // 文件选择框

// 2. 监听文件选择事件
fileInput.addEventListener('change', async (e) => {
  const file = e.target.files[0];
  if (!file) return;

  // 3. 生成文件唯一标识（建议用MD5，这里简化为“文件名+文件大小”）
  const fileId = `${file.name}-${file.size}-${file.lastModified}`;
  const totalChunks = Math.ceil(file.size / CHUNK_SIZE); // 总分片数

  // 4. 切割并上传所有分片
  for (let chunkIndex = 0; chunkIndex < totalChunks; chunkIndex++) {
    // 切割当前分片：start = 分片索引 * 分片大小，end = 取最小值（避免最后一片超出文件大小）
    const start = chunkIndex * CHUNK_SIZE;
    const end = Math.min(start + CHUNK_SIZE, file.size);
    const chunk = file.slice(start, end);

    // 5. 构造FormData，携带分片信息
    const formData = new FormData();
    formData.append('fileId', fileId);
    formData.append('chunkIndex', chunkIndex);
    formData.append('totalChunks', totalChunks);
    formData.append('chunk', chunk); // 分片文件

    // 6. 上传分片（使用Fetch API）
    try {
      const response = await fetch('/api/upload-chunk', {
        method: 'POST',
        body: formData,
      });
      const result = await response.json();
      if (result.success) {
        console.log(`分片 ${chunkIndex + 1}/${totalChunks} 上传成功`);
        // 这里可添加进度条更新逻辑
      } else {
        console.error(`分片 ${chunkIndex + 1} 上传失败：`, result.message);
        // 分片上传失败：可重试或提示用户
      }
    } catch (error) {
      console.error(`分片 ${chunkIndex + 1} 上传异常：`, error);
    }
  }

  // 7. 所有分片上传完成后，通知服务器合并
  await fetch('/api/merge-chunks', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ fileId, fileName: file.name }),
  });
  console.log('所有分片上传完成，服务器开始合并文件');
});

3. 分片上传的优化点

  • 并发上传：上述示例是“串行上传”（一个分片传完再传下一个），效率较低。实际项目中可使用“并发上传”（如同时上传3-5个分片），但需控制并发数，避免过多请求导致浏览器或服务器压力过大（可借助Promise.allSettled()或第三方库如p-limit控制并发）；
  • 分片大小选择：分片太小会导致请求数过多（如1GB文件按1MB分片，需1000个请求），增加服务器开销；分片太大则失去“分片”意义（如1GB文件按500MB分片，和单文件上传差异不大）。建议根据业务场景选择5MB-20MB，兼顾请求数和容错性；
  • 文件唯一标识生成：上述示例用“文件名+大小+修改时间”简化，实际项目中建议用文件MD5（通过spark-md5等库在前端计算），避免“文件名相同但内容不同”或“内容相同但文件名不同”导致的分片归属错误。

三、核心技术2：断点续传（Resumable Upload）

分片上传解决了“大文件拆分传输”的问题，但如果上传到一半中断（如网络断开、页面关闭），再次上传时仍需重新传所有分片

这就需要“断点续传”—— 记录已上传的分片，再次上传时只传未完成的分片。

1. 断点续传的核心原理

断点续传的关键是“状态记录”，即前端或服务器需要知道“当前文件已上传了哪些分片”，流程如下：

  1. 上传前校验：用户再次选择同一文件（或刷新页面后继续上传）时，前端先向服务器发送“文件唯一标识（如MD5）”，请求查询“该文件已上传的分片列表”；
  2. 筛选未上传分片：服务器返回已接收的分片索引，前端对比“总分片数”和“已上传分片”，筛选出未上传的分片；
  3. 只传未完成分片：前端仅上传未完成的分片，跳过已上传的分片；
  4. 状态持久化：服务器需要持久化存储“文件ID-已上传分片”的映射关系（如用数据库、Redis或文件记录），确保即使服务器重启，已上传的分片状态也不会丢失。

2. 断点续传的前端关键代码（基于分片上传扩展）

// 1. 依赖：计算文件MD5（需引入spark-md5库，处理大文件时用FileReader分片读取）
async function calculateFileMD5(file) {
  return new Promise((resolve) => {
    const spark = new SparkMD5.ArrayBuffer();
    const fileReader = new FileReader();
    const chunkSize = 2 * 1024 * 1024; // 计算MD5时的分片大小（可与上传分片不同）
    let offset = 0;

    fileReader.onload = (e) => {
      spark.append(e.target.result);
      offset += chunkSize;
      if (offset < file.size) {
        readNextChunk(); // 继续读取下一分片
      } else {
        const md5 = spark.end(); // 计算完成，得到文件MD5
        resolve(md5);
      }
    };

    function readNextChunk() {
      const blob = file.slice(offset, offset + chunkSize);
      fileReader.readAsArrayBuffer(blob);
    }

    readNextChunk(); // 开始读取第一个分片
  });
}

// 2. 断点续传核心逻辑
async function resumeUpload(file) {
  // 3. 计算文件唯一标识（MD5）
  const fileId = await calculateFileMD5(file);
  const totalChunks = Math.ceil(file.size / CHUNK_SIZE);

  // 4. 向服务器查询已上传的分片列表
  const response = await fetch(`/api/get-uploaded-chunks?fileId=${fileId}`);
  const { uploadedChunks = [] } = await response.json(); // 已上传的分片索引数组（如[0,1]）

  // 5. 筛选未上传的分片（总分片索引 - 已上传索引）
  const unUploadedChunks = [];
  for (let i = 0; i < totalChunks; i++) {
    if (!uploadedChunks.includes(i)) {
      unUploadedChunks.push(i);
    }
  }

  if (unUploadedChunks.length === 0) {
    console.log('文件已全部上传，无需续传');
    return;
  }

  console.log(`需续传的分片：${unUploadedChunks.join(', ')}`);

  // 6. 只上传未完成的分片（逻辑与分片上传一致，略）
  for (const chunkIndex of unUploadedChunks) {
    const start = chunkIndex * CHUNK_SIZE;
    const end = Math.min(start + CHUNK_SIZE, file.size);
    const chunk = file.slice(start, end);
    const formData = new FormData();
    formData.append('fileId', fileId);
    formData.append('chunkIndex', chunkIndex);
    formData.append('totalChunks', totalChunks);
    formData.append('chunk', chunk);

    try {
      await fetch('/api/upload-chunk', { method: 'POST', body: formData });
      console.log(`续传分片 ${chunkIndex} 成功`);
    } catch (error) {
      console.error(`续传分片 ${chunkIndex} 失败：`, error);
    }
  }

  // 7. 通知服务器合并（同分片上传）
  await fetch('/api/merge-chunks', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ fileId, fileName: file.name }),
  });
}

3. 断点续传的注意事项

  • 文件MD5计算性能：大文件（如GB级）在前端计算MD5会消耗CPU和时间，可能导致页面卡顿。优化方案：
    • 用Web Worker在后台计算MD5，避免阻塞主线程；
    • 若服务器支持，可由服务器计算文件MD5（前端先传小分片获取MD5，再续传后续分片）；
  • 状态过期清理：服务器存储的“已上传分片”状态需要设置过期时间（如24小时），避免大量未完成的分片占用存储空间；
  • 跨设备续传：若需支持“手机上传一半，电脑继续传”，需将“文件ID-用户ID-已上传分片”绑定存储，确保不同设备能查询到同一用户的上传状态。

四、其他辅助技术：提升大文件上传体验

除了分片和断点续传，还有一些技术可以进一步优化大文件上传的稳定性和用户体验：

1. 上传进度反馈

用户需要知道“上传了多少”，前端可通过XMLHttpRequest.upload.onprogress或Fetch API的ReadableStream监听上传进度：

// 基于XHR的进度监听（Fetch的进度监听需借助ReadableStream，兼容性稍差）
const xhr = new XMLHttpRequest();
xhr.open('POST', '/api/upload-chunk');
xhr.upload.onprogress = (e) => {
  if (e.lengthComputable) {
    const chunkProgress = (e.loaded / e.total) * 100; // 当前分片的上传进度
    // 计算整体进度：(已上传分片大小 + 当前分片已传大小) / 文件总大小
    const totalUploadedSize = uploadedChunks.reduce((sum, idx) => sum + CHUNK_SIZE, 0);
    const currentChunkUploaded = e.loaded;
    const overallProgress = ((totalUploadedSize + currentChunkUploaded) / file.size) * 100;
    console.log(`整体上传进度：${overallProgress.toFixed(2)}%`);
    // 更新页面进度条（如document.getElementById('progress-bar').style.width = `${overallProgress}%`）
  }
};
xhr.send(formData);

2. 分片重试机制

网络波动可能导致个别分片上传失败，前端需要实现“自动重试”逻辑：

  • 重试次数限制（如最多重试3次），避免无限重试；
  • 重试间隔递增（如第一次间隔1秒，第二次2秒，第三次4秒），减少服务器压力；
  • 若重试多次仍失败，提示用户“手动重试”或“检查网络”。

3. 大文件上传库推荐

实际项目中，无需重复造轮子，可使用成熟的开源库简化开发：

  • Resumable.js：经典的断点续传库，支持分片、并发上传、进度监听，兼容性好；
  • Uppy：功能全面的文件上传工具，支持大文件分片、断点续传、云存储（如S3）集成，且有丰富的UI组件；
  • Tus.js：基于Tus协议（一种专为断点续传设计的协议），支持跨平台、跨语言，适合需要高度标准化的场景；
  • Element Plus Upload：Vue生态的组件库，内置了分片上传和断点续传功能，适合Vue项目快速集成。

五、总结：大文件上传的技术选型建议

根据业务需求选择合适的方案，是前端大文件上传的关键：

  • 小文件（<10MB）：无需分片，直接使用传统上传即可，简单高效；
  • 中文件（10MB-100MB）：推荐使用“分片上传”，解决上传中断后重新传的问题，无需复杂的断点续传；
  • 大文件（>100MB）：必须结合“分片上传+断点续传”，并搭配进度反馈、重试机制，确保上传稳定性；
  • 跨设备/高并发场景：使用成熟库（如Uppy、Tus.js），并在服务器端用Redis存储分片状态，提升扩展性。

大文件上传的核心是“拆分与续传”，前端负责“拆”和“传”，服务器负责“存”和“合”——只有前后端协同，才能真正解决大文件上传的痛点，给用户带来流畅的体验。

© 2025 try-catch.life