大文件分片上传与断点续传：原理、实战与避坑指南

断点续传分片上传大文件上传
于 2026-08-05 06:55:14 修改
·本内容遵循CC 4.0 BY-SA版权协议

1. 从一次失败的上传说起：为什么我们需要断点续传

那天下午，我盯着屏幕上那个卡在99.9%的进度条，感觉血压在飙升。一个3GB的设计源文件，上传了快一个小时，眼看就要大功告成，结果网络波动了一下，页面直接报错“网络连接失败”。更让人崩溃的是，点击重试后，一切又得从零开始。这种经历，但凡处理过大文件的开发者或用户，应该都不陌生。它带来的不仅是时间上的浪费，更是对产品体验和用户耐心的巨大消耗。

这就是我们今天要深入探讨的核心问题：大文件上传如何实现断点续传？ 简单来说，断点续传就是让文件上传过程具备“记忆”能力，即使中途因网络中断、页面刷新、应用崩溃等原因导致上传失败，也能在恢复后从上次中断的地方继续上传，而不是从头再来。这听起来像是魔法，但背后的原理其实是一套非常经典且实用的工程实践。

从技术角度看，断点续传通常与另一个概念紧密绑定：分片上传。你可以把它想象成搬家。你不会把整个衣柜原封不动地搬走，而是会把衣服一件件叠好、分箱打包，然后一箱箱地搬运。分片上传就是这个“分箱打包”的过程，而断点续传则是确保每一箱都贴上标签、做好记录，哪怕中途有几箱没搬完，下次也能精准地接着搬剩下的箱子。

最近的热词，比如“前端使用worker上传大文件”、“uniapp开发的移动端app分片上传视频到oss”、“minio分片上传”，都指向了同一个技术方向：在前端复杂场景和多样化存储后端（如阿里云OSS、MinIO）中，如何稳定、高效、可靠地处理大文件。这不仅仅是前端或后端的单一问题，而是一个涉及前端分片策略、网络传输控制、后端存储校验、状态持久化的完整链路设计。

接下来，我将以一个全栈视角，拆解实现大文件断点续传的完整方案。我会从最核心的原理讲起，然后一步步带你搭建前后端，并分享我在实际项目中踩过的坑和总结的经验。无论你是前端工程师、后端开发者，还是全栈爱好者，这篇文章都能给你一套可直接落地的“抄作业”指南。

2. 核心原理拆解：分片、校验与状态管理

要实现断点续传，我们必须先理解它的三大基石：文件分片、唯一性校验和上传状态管理。这三者环环相扣，缺一不可。

2.1 文件分片：化整为零的艺术

为什么一定要分片？直接上传整个文件不行吗？对于小文件（比如几MB）或许可以，但对于动辄几百MB甚至几个GB的大文件，直接上传面临几个致命问题：

  1. 超时风险：HTTP请求有超时限制，上传一个大文件很容易触发超时。
  2. 内存压力：前端一次性读取整个大文件到内存，可能导致浏览器标签页崩溃。
  3. 无法续传：一旦中断，整个文件进度丢失，必须重头开始。
  4. 网络不稳定：大文件传输过程中网络波动概率更高，整体失败成本巨大。

分片就是将一个大文件切割成多个固定大小（例如1MB或5MB）的小块（Chunk）。这个操作通常在前端利用 File 对象的 slice 方法完成。分片后，每个分片都是独立的HTTP请求，这带来了巨大优势：

  • 并行上传：可以同时发起多个分片的上传请求，充分利用带宽，大幅提升整体速度。
  • 独立重试：某个分片上传失败，只需重试这个分片本身，不影响其他已成功上传的分片。
  • 断点续传基础：记录了哪些分片已上传，哪些未上传，续传时只需上传未完成的分片。

这里有一个关键参数：分片大小。如何选择？这需要权衡：

  • 分片太小（如100KB）：分片数量过多，创建和管理大量HTTP请求的开销（Overhead）会抵消并行上传的优势，且给后端存储和合并带来压力。
  • 分片太大（如100MB）：失去了分片的意义，单个请求失败的成本依然很高，且可能遇到服务器或代理对单个请求体大小的限制。

根据我的经验，对于普通网络环境，1MB到5MB是一个比较理想的区间。对于内网或特别稳定的高速网络，可以适当增大到10MB-20MB。一个实用的技巧是动态分片：根据文件总大小自动计算分片大小，确保分片数量在一个合理范围内（比如100-1000片）。

2.2 唯一性校验：如何识别“同一个文件”

这是断点续传的灵魂。用户第二次选择同一个文件时，系统如何知道这是上次未传完的文件，而不是一个新文件？我们不能依赖文件名，因为用户可能重命名。我们需要一个文件的“指纹”。

最常用的方法是计算文件的 内容哈希（Hash）。通常使用 MD5 或 SHA-256 算法。即使文件被重命名，只要内容字节完全一致，计算出的哈希值就是唯一的。前端在分片前，先读取整个文件的二进制数据并计算其哈希值，将这个哈希值作为文件的唯一标识（fileHash）发送给后端。

但这里有一个性能陷阱：计算一个几GB文件的完整哈希，在前端（尤其是浏览器）是一个同步的、耗时的操作，会阻塞主线程，导致页面“卡死”。解决方案是使用 Web Worker 或浏览器的 异步API（如 crypto.subtle.digest）在后台线程进行计算。这也是“前端使用worker上传大文件”成为热词的原因——Worker可以将繁重的计算任务剥离主线程，保持页面流畅。

注意：MD5虽然计算较快，但存在理论上的碰撞可能（不同内容产生相同哈希）。对于安全性要求极高的场景，建议使用SHA-256。但对于文件上传的标识场景，MD5的碰撞概率极低，通常可以接受，性能优势更明显。

2.3 上传状态管理：记住每一片的“足迹”

有了分片和文件指纹，我们还需要一个“账本”来记录每个分片的上传状态。这个账本需要持久化，不能因为页面刷新而丢失。通常有两种思路：

  1. 后端集中式管理：后端维护一个映射表，以 fileHash 为Key，记录该文件的总分片数、每个分片的索引（chunkIndex）及其上传状态（成功/失败）。前端在上传前，先询问后端：“文件ABC123，哪些分片已经传过了？”后端返回已上传的分片索引列表，前端跳过这些分片，只上传未完成的。
  2. 前端本地持久化：利用浏览器的 localStorage、IndexedDB 或 sessionStorage，在前端本地记录每个文件的上传进度。刷新页面后，从本地存储恢复进度，然后向后端验证这些分片是否确实已上传（防止本地记录被篡改或清理）。这种方式减轻了后端的状态管理压力，但依赖客户端存储，在用户清空浏览器数据后会失效。

在实际项目中，我推荐 两者结合 的方式：

  • 后端负责最终权威状态：存储已成功接收并保存的分片信息。
  • 前端负责临时进度与体验：在本地记录实时上传进度，用于展示进度条。在上传开始前，向后端查询该文件的“已上传分片清单”，以此为准决定本次上传任务。

这个状态管理机制，是实现“断点”感知和“续传”决策的核心大脑。

3. 前端实战：从文件选择到分片上传

理论讲完了，我们动手实现前端部分。我们将使用现代浏览器API，并考虑使用Web Worker来处理哈希计算，保证体验流畅。

3.1 环境准备与文件读取

首先，我们需要一个文件输入框和一个展示进度的区域。

HTML
<input type="file" id="fileInput" />
<button onclick="handleUpload()">开始上传</button>
<div>
<p>计算文件哈希中: <span id="hashProgress">0%</span></p>
<p>总上传进度: <span id="uploadProgress">0%</span></p>
<div style="width: 100%; background: #eee;">
<div id="progressBar" style="height: 20px; width: 0%; background: #4caf50;"></div>
</div>
</div>

在JavaScript中，我们监听文件选择，并开始我们的流程。

JAVASCRIPT
// 配置
const CHUNK_SIZE = 1 * 1024 * 1024; // 1MB 分片大小
let file = null;
let fileHash = '';
let chunkList = [];
 
document.getElementById('fileInput').addEventListener('change', async (e) => {
file = e.target.files[0];
if (!file) return;
console.log(`选中文件: ${file.name}, 大小: ${(file.size / 1024 / 1024).toFixed(2)}MB`);
// 1. 计算文件哈希 (使用Web Worker避免阻塞)
const hash = await calculateFileHash(file);
fileHash = hash;
console.log('文件哈希:', fileHash);
// 2. 创建分片列表
chunkList = createFileChunks(file, CHUNK_SIZE);
console.log(`总分片数: ${chunkList.length}`);
// 3. 询问后端已上传分片
const uploadedList = await checkUploadedChunks(fileHash);
console.log('已上传分片索引:', uploadedList);
});

3.2 使用Web Worker计算文件哈希

计算大文件哈希不能阻塞主线程。我们创建一个单独的 hash.worker.js 文件。

JAVASCRIPT
// hash.worker.js
self.onmessage = async (e) => {
const { file } = e.data;
const chunkSize = 2 * 1024 * 1024; // 计算哈希时也用分片读，避免内存溢出
const chunks = Math.ceil(file.size / chunkSize);
let hash = '';
// 这里以计算MD5为例，使用 crypto-js 库。实际中可使用更高效的库如 spark-md5
// 注意：Worker中无法直接访问DOM和部分浏览器API，但可以importScripts
importScripts('https://cdnjs.cloudflare.com/ajax/libs/spark-md5/3.0.2/spark-md5.min.js');
const spark = new self.SparkMD5.ArrayBuffer();
for (let i = 0; i < chunks; i++) {
const start = i * chunkSize;
const end = start + chunkSize >= file.size ? file.size : start + chunkSize;
const chunk = file.slice(start, end);
const buffer = await chunk.arrayBuffer();
spark.append(buffer);
// 向主线程报告进度
self.postMessage({
progress: ((i + 1) / chunks) * 100
});
}
hash = spark.end();
self.postMessage({ hash });
};

主线程中调用Worker：

JAVASCRIPT
function calculateFileHash(file) {
return new Promise((resolve) => {
const worker = new Worker('./hash.worker.js');
worker.postMessage({ file });
worker.onmessage = (e) => {
if (e.data.progress) {
document.getElementById('hashProgress').textContent = `${e.data.progress.toFixed(1)}%`;
}
if (e.data.hash) {
resolve(e.data.hash);
worker.terminate(); // 计算完成，关闭Worker
}
};
});
}

3.3 创建分片与查询上传状态

创建分片列表的函数很简单：

JAVASCRIPT
function createFileChunks(file, chunkSize) {
const chunks = [];
let cur = 0;
let index = 0;
while (cur < file.size) {
chunks.push({
file: file.slice(cur, cur + chunkSize),
index: index++,
hash: fileHash, // 所属文件哈希
chunkHash: '', // 可选，可为每个分片也计算哈希用于秒传和校验
});
cur += chunkSize;
}
return chunks;
}

接着，我们需要向后端发起一个查询，获取该文件已上传的分片列表。

JAVASCRIPT
async function checkUploadedChunks(fileHash) {
try {
const response = await fetch(`/api/upload/check?fileHash=${fileHash}`);
const data = await response.json();
if (data.code === 0) {
return data.data.uploadedList || []; // 假设返回的是已上传分片的索引数组 [0, 1, 3...]
}
return [];
} catch (error) {
console.error('查询已上传分片失败:', error);
return [];
}
}

3.4 并发控制与分片上传

这是前端最核心的部分。我们不能一次性发起几百个HTTP请求，需要控制并发数。

JAVASCRIPT
async function handleUpload() {
if (!file || !chunkList.length) return;
const uploadedList = await checkUploadedChunks(fileHash); // 获取已上传列表
const needUploadList = chunkList.filter(chunk => !uploadedList.includes(chunk.index));
console.log(`需要上传的分片数: ${needUploadList.length}`);
if (needUploadList.length === 0) {
alert('所有分片已上传完毕，正在请求合并文件。');
await mergeFileRequest();
return;
}
const CONCURRENT_LIMIT = 4; // 控制并发数为4
const total = needUploadList.length;
let uploadedCount = 0;
let failedChunks = []; // 记录失败的分片，用于重试
// 进度更新函数
const updateProgress = () => {
const progress = ((uploadedCount + uploadedList.length) / chunkList.length) * 100;
document.getElementById('uploadProgress').textContent = `${progress.toFixed(1)}%`;
document.getElementById('progressBar').style.width = `${progress}%`;
};
// 上传单个分片
const uploadChunk = async (chunk) => {
const formData = new FormData();
formData.append('file', chunk.file);
formData.append('chunkIndex', chunk.index);
formData.append('fileHash', chunk.hash);
formData.append('chunkHash', chunk.chunkHash); // 可选
formData.append('totalChunks', chunkList.length);
try {
const response = await fetch('/api/upload/chunk', {
method: 'POST',
body: formData,
// 注意：不要设置 Content-Type，FormData 会自动设置 multipart/form-data
});
const result = await response.json();
if (result.code === 0) {
uploadedCount++;
updateProgress();
// 可选：将成功上传的分片索引记录到本地存储，用于页面刷新后恢复
saveProgressToLocal(chunk.index);
} else {
throw new Error(result.message);
}
} catch (error) {
console.error(`分片 ${chunk.index} 上传失败:`, error);
failedChunks.push(chunk); // 加入失败队列
}
};
// 并发控制执行器
const runTasks = async (tasks, limit) => {
const executing = new Set();
for (const task of tasks) {
const p = task().then(() => executing.delete(p));
executing.add(p);
if (executing.size >= limit) {
await Promise.race(executing);
}
}
await Promise.all(executing);
};
// 将需要上传的分片包装成任务
const tasks = needUploadList.map(chunk => () => uploadChunk(chunk));
await runTasks(tasks, CONCURRENT_LIMIT);
// 处理失败重试（简单示例，可实现更复杂的重试策略）
if (failedChunks.length > 0) {
console.warn(`${failedChunks.length} 个分片上传失败，开始重试...`);
const retryTasks = failedChunks.map(chunk => () => uploadChunk(chunk));
await runTasks(retryTasks, CONCURRENT_LIMIT);
}
// 所有分片上传完成后，请求合并
if (uploadedCount + uploadedList.length === chunkList.length) {
console.log('所有分片上传完成，请求合并。');
await mergeFileRequest();
} else {
alert('上传未完全完成，可刷新页面继续上传。');
}
}
 
// 请求合并文件
async function mergeFileRequest() {
try {
const response = await fetch('/api/upload/merge', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ fileHash: fileHash, fileName: file.name, totalChunks: chunkList.length }),
});
const result = await response.json();
if (result.code === 0) {
alert(`文件上传并合并成功！访问地址: ${result.data.url}`);
} else {
alert(`合并失败: ${result.message}`);
}
} catch (error) {
console.error('合并请求失败:', error);
}
}
 
// 本地存储进度（示例使用sessionStorage，页面刷新有效）
function saveProgressToLocal(chunkIndex) {
const key = `upload_${fileHash}`;
let progress = JSON.parse(sessionStorage.getItem(key) || '[]');
if (!progress.includes(chunkIndex)) {
progress.push(chunkIndex);
sessionStorage.setItem(key, JSON.stringify(progress));
}
}

4. 后端实现：接收、存储与合并分片

前端把活干完了，后端需要可靠地接收分片、管理状态，并在最后将所有分片合并成完整的文件。我们以Node.js (Express) + 本地文件系统为例，概念同样适用于OSS、MinIO等对象存储。

4.1 项目结构与依赖

创建一个简单的Node.js项目。

BASH
mkdir upload-server && cd upload-server
npm init -y
npm install express multer cors

目录结构：

TEXT
upload-server/
├── server.js
├── uploads/ # 存储上传的分片和合并后的文件
│ ├── chunks/ # 分片临时目录，按fileHash命名子目录
│ └── merged/ # 合并后的文件目录
└── package.json

4.2 核心API设计

我们主要需要三个接口：

  1. GET /api/upload/check：检查文件上传状态，返回已上传分片列表。
  2. POST /api/upload/chunk：接收并保存单个文件分片。
  3. POST /api/upload/merge：合并所有分片为完整文件。
JAVASCRIPT
// server.js
const express = require('express');
const multer = require('multer');
const cors = require('cors');
const fs = require('fs').promises;
const path = require('path');
 
const app = express();
app.use(cors());
app.use(express.json());
 
const UPLOAD_DIR = path.resolve(__dirname, 'uploads');
const CHUNKS_DIR = path.join(UPLOAD_DIR, 'chunks');
const MERGED_DIR = path.join(UPLOAD_DIR, 'merged');
 
// 确保目录存在
(async () => {
await fs.mkdir(CHUNKS_DIR, { recursive: true });
await fs.mkdir(MERGED_DIR, { recursive: true });
})();
 
// 配置multer用于接收文件分片
const storage = multer.diskStorage({
destination: function (req, file, cb) {
const { fileHash } = req.body;
const chunkDir = path.resolve(CHUNKS_DIR, fileHash);
// 确保该文件对应的分片目录存在
fs.mkdir(chunkDir, { recursive: true }).then(() => cb(null, chunkDir)).catch(cb);
},
filename: function (req, file, cb) {
const { chunkIndex } = req.body;
// 分片文件以索引命名，例如 0, 1, 2...
cb(null, `${chunkIndex}`);
}
});
const upload = multer({ storage: storage });
 
// 1. 检查上传状态
app.get('/api/upload/check', async (req, res) => {
const { fileHash } = req.query;
if (!fileHash) {
return res.json({ code: 400, message: '缺少fileHash参数' });
}
const chunkDir = path.resolve(CHUNKS_DIR, fileHash);
try {
// 检查分片目录是否存在
await fs.access(chunkDir);
// 读取目录下所有文件（即已上传的分片索引名）
const chunks = await fs.readdir(chunkDir);
// 过滤并转换为数字索引，按顺序返回
const uploadedList = chunks.map(chunk => parseInt(chunk)).sort((a, b) => a - b);
res.json({ code: 0, message: 'success', data: { uploadedList } });
} catch (error) {
// 如果目录不存在，说明该文件从未上传过任何分片
if (error.code === 'ENOENT') {
res.json({ code: 0, message: 'success', data: { uploadedList: [] } });
} else {
console.error('检查上传状态出错:', error);
res.json({ code: 500, message: '服务器内部错误' });
}
}
});
 
// 2. 上传分片
app.post('/api/upload/chunk', upload.single('file'), async (req, res) => {
const { fileHash, chunkIndex, chunkHash } = req.body;
// 这里可以添加分片哈希校验，确保数据传输无误
// if (chunkHash) { ... }
// 分片已通过multer保存到指定目录
console.log(`分片接收成功: fileHash=${fileHash}, chunkIndex=${chunkIndex}`);
res.json({ code: 0, message: '分片上传成功' });
});
 
// 3. 合并分片
app.post('/api/upload/merge', async (req, res) => {
const { fileHash, fileName, totalChunks } = req.body;
if (!fileHash || !fileName || !totalChunks) {
return res.json({ code: 400, message: '缺少必要参数' });
}
const chunkDir = path.resolve(CHUNKS_DIR, fileHash);
const mergedFilePath = path.resolve(MERGED_DIR, `${fileHash}-${fileName}`);
try {
// 检查分片是否齐全
const chunkFiles = await fs.readdir(chunkDir);
if (chunkFiles.length !== totalChunks) {
return res.json({ code: 400, message: `分片数量不完整，期望${totalChunks}，实际${chunkFiles.length}` });
}
// 确保分片按索引顺序排序
chunkFiles.sort((a, b) => parseInt(a) - parseInt(b));
// 创建写入流
const writeStream = fs.createWriteStream(mergedFilePath);
// 按顺序将每个分片读取并追加到最终文件
for (const chunkFile of chunkFiles) {
const chunkPath = path.resolve(chunkDir, chunkFile);
const buffer = await fs.readFile(chunkPath);
writeStream.write(buffer);
}
writeStream.end();
// 等待写入完成
await new Promise((resolve, reject) => {
writeStream.on('finish', resolve);
writeStream.on('error', reject);
});
console.log(`文件合并成功: ${mergedFilePath}`);
// 可选：合并成功后，删除临时分片目录以释放空间
// await fs.rm(chunkDir, { recursive: true, force: true });
// 返回文件访问地址（这里简单返回路径，生产环境应返回CDN或静态服务URL）
const fileUrl = `/merged/${path.basename(mergedFilePath)}`;
res.json({ code: 0, message: '文件合并成功', data: { url: fileUrl } });
} catch (error) {
console.error('合并文件失败:', error);
res.json({ code: 500, message: '文件合并失败' });
}
});
 
// 提供合并后文件的静态访问（简易版）
app.use('/merged', express.static(MERGED_DIR));
 
const PORT = 3000;
app.listen(PORT, () => {
console.log(`Server is running on http://localhost:${PORT}`);
});

4.3 关键细节与优化点

上面的后端代码是一个最简化的示例，在生产环境中还需要考虑以下几点：

  1. 分片完整性校验：前端上传分片时，可以计算该分片的哈希值（chunkHash）一并上传。后端收到分片后，重新计算其哈希进行比对，确保数据传输过程中没有出错。这对于大文件上传的可靠性至关重要。
  2. 异步合并与任务队列：合并大文件是一个IO密集型操作，可能会耗时较长。不应该在HTTP请求线程中同步执行，否则会阻塞请求并可能导致超时。更好的做法是：
    • 接收到合并请求后，立即返回一个“合并任务已提交”的响应。
    • 将合并任务推入一个消息队列（如Redis、RabbitMQ）或数据库。
    • 由单独的后台Worker进程消费队列，执行合并操作。
    • 合并完成后，通过WebSocket、Server-Sent Events (SSE)或让前端轮询另一个状态查询接口，通知用户合并结果。
  3. 存储策略：上述例子使用本地文件系统，不适合分布式部署。生产环境应使用对象存储服务（如阿里云OSS、腾讯云COS、AWS S3、MinIO）。
    • 上传分片：前端直接通过预签名URL（Presigned URL）将分片上传到对象存储的指定位置（如 chunks/{fileHash}/{chunkIndex}）。
    • 查询状态：后端通过对象存储的API列出 chunks/{fileHash}/ 下的所有对象，得到已上传分片列表。
    • 合并文件：对象存储通常提供“分片上传（Multipart Upload）”的API，其“完成上传”操作本质上就是合并。对于不支持此操作的存储，可能需要后端下载所有分片到临时位置合并后再上传，或使用云函数/Lambda处理。
  4. 安全性：
    • 身份验证：所有上传接口必须进行用户身份校验（如JWT），防止恶意上传。
    • 文件类型和大小限制：在后端严格校验文件的MIME类型和总大小。
    • 防重放攻击：可以为每个上传请求生成一次性令牌。
    • 清理机制：设置定时任务，清理长时间未完成合并的临时分片目录，避免存储空间浪费。

5. 进阶场景与深度优化

基础功能跑通后，我们可以追求更极致的体验和更强的鲁棒性。这里分享几个我在实际项目中用到的进阶技巧。

5.1 秒传与增量上传

这是断点续传的“升级版”，能极大提升用户体验。

  • 秒传：在上传前，前端将文件的完整哈希发送给后端。后端在文件系统中或数据库里查找，是否已存在相同哈希的文件。如果存在，则直接返回该文件的访问地址，跳过上传和合并过程。这依赖于后端存储了“文件哈希->存储路径”的映射。
  • 增量上传：这比秒传更复杂。不仅计算整个文件的哈希，还为每个分片计算哈希。上传前，后端不仅返回已上传分片的索引，还可能返回每个分片的哈希。前端将本地分片哈希与后端对比，如果哈希一致，则证明该分片内容未变，无需重新上传；如果哈希不同，即使索引已上传过，也需要重新上传该分片。这适用于文件部分内容被修改后的重新上传场景。

实现秒传，需要在合并成功后，将 fileHash 和最终文件存储路径的对应关系持久化到数据库（如MySQL、Redis）。

JAVASCRIPT
// 在合并成功后
async function saveFileRecord(fileHash, filePath, fileName, size) {
// 存入数据库
// INSERT INTO file_records (hash, path, filename, size, created_at) VALUES (?, ?, ?, ?, NOW())
// ON DUPLICATE KEY UPDATE ... (如果哈希是唯一索引)
}
// 在检查状态接口 /check 中，先查询数据库
const record = await db.query('SELECT path FROM file_records WHERE hash = ?', [fileHash]);
if (record) {
// 文件已存在，秒传！
return res.json({ code: 0, message: '文件已存在', data: { uploadedList: [], needMerge: false, url: record.path } });
}

5.2 更健壮的上传控制与错误处理

前文示例的并发控制和错误重试比较简单。一个工业级的方案需要考虑更多：

  • 动态并发控制：根据网络状况和服务器响应动态调整并发数。例如，当连续多个请求失败或超时时，自动降低并发数；当上传速度稳定时，可以尝试增加并发数。
  • 分片上传优先级：不一定按顺序上传。可以优先上传文件中间的分片，这样能更快地让用户看到进度推进（因为进度条通常是线性的）。
  • 断网检测与自动重连：利用 navigator.onLine API 和 online/offline 事件监听网络状态变化。断网时暂停所有上传请求，待网络恢复后自动从断点继续。
  • 更精细的重试策略：对于失败的分片，采用指数退避策略进行重试（如第一次等待1秒后重试，第二次等待2秒，第三次等待4秒...），并设置最大重试次数。
  • 暂停与继续：除了网络中断，用户也可能主动暂停。我们需要提供一个 pause() 方法，它能取消所有正在进行的上传请求（使用 AbortController），并保存当前进度。继续时，重新调用 checkUploadedChunks 获取最新状态，然后继续上传剩余分片。

5.3 适配移动端与UniApp

“uniapp开发的移动端app分片上传视频到oss”这个热词点出了移动端的特殊场景。在移动端（尤其是Hybrid App或UniApp）实现分片上传，原理与Web端一致，但有以下几点需要注意：

  1. 文件选择：使用UniApp的 uni.chooseFile 或 uni.chooseVideo API获取文件对象。注意，在部分平台（如微信小程序）获取到的可能是临时文件路径，需要先通过 uni.getFileSystemManager().readFile 读取为 ArrayBuffer 才能进行分片。
  2. 计算哈希：移动端计算大文件哈希同样耗性能。可以考虑使用原生插件（如用C++编写的哈希计算库）来提升速度，或者如果后端支持，可以跳过前端计算，由后端在接收第一个分片时进行流式哈希计算（但这会损失秒传能力）。
  3. 网络状态：移动网络更不稳定，需要更积极的断点续传和重试逻辑。可以利用UniApp的网络状态监听API。
  4. 上传到OSS：通常不建议通过业务服务器中转大文件分片，这会给服务器带来巨大带宽和IO压力。最佳实践是：
    • 业务服务器提供一个接口，为每个分片生成一个OSS的预签名上传URL（Policy和Signature）。
    • 前端/移动端直接向OSS地址发起PUT请求上传分片数据。
    • 所有分片上传完成后，业务服务器再调用OSS的 CompleteMultipartUpload API完成合并。
    • 这种方式下，业务服务器只处理轻量的签名生成和状态管理请求，文件数据流不经过业务服务器，架构更清晰，性能更好。

5.4 与MinIO等S3兼容存储的集成

MinIO是一个高性能的、与S3 API兼容的开源对象存储。集成MinIO进行分片上传非常方便，因为它原生支持S3的多部分上传（Multipart Upload） API。

流程如下：

  1. 初始化分片上传：前端请求后端，后端调用MinIO的 createMultipartUpload API，获取一个全局唯一的 uploadId。
  2. 上传分片：前端根据 uploadId 和分片索引（partNumber，从1开始），请求后端生成该分片的预签名上传URL，然后直传分片到MinIO。MinIO会返回每个分片的 ETag。
  3. 查询已上传分片：后端可以调用 listParts API，根据 uploadId 查询已上传的分片列表及其 ETag。
  4. 完成上传：所有分片上传后，前端通知后端，后端调用 completeMultipartUpload API，提供所有分片的 partNumber 和 ETag 列表，MinIO会自动合并文件。
  5. 取消上传：如果中途放弃，可以调用 abortMultipartUpload 清理临时分片。

使用MinIO/S3的原生多部分上传API，省去了我们自己管理分片文件和合并的麻烦，可靠性也由存储服务本身保障，是更推荐的生产环境方案。

6. 避坑指南：那些我踩过的“坑”

纸上得来终觉浅，绝知此事要躬行。下面分享几个我在实现断点续传时真实踩过的坑，希望能帮你绕过去。

6.1 分片大小与服务器限制的冲突

问题：我将分片大小设置为5MB，测试一切正常。上线后，有用户上传一个特殊格式的文件时，后端始终收不到最后一个分片。 排查：查看Nginx日志，发现对于那个特定的请求返回了 413 Request Entity Too Large。检查发现，该用户文件的最后一个分片虽然逻辑上是5MB，但由于编码或压缩问题，在组成为 multipart/form-data 后，请求体略微超过了服务器配置的 client_max_body_size（默认可能是1MB或10MB）。 解决：

  1. 调整Nginx配置：client_max_body_size 20m;（根据实际情况调整）。
  2. 调整后端框架（如Express）的body解析限制。
  3. 更稳健的做法：将分片大小设置得略小于常见的服务器限制，例如4MB。并在前端上传时，如果某个分片请求失败且返回413错误，可以尝试自动将分片大小减半后重试该分片。

6.2 文件哈希计算的内存与性能陷阱

问题：在计算一个4GB视频文件的MD5时，页面直接卡死，甚至崩溃。 排查：最初我是在主线程同步计算哈希，一次性将整个文件的 ArrayBuffer 读入内存，导致内存峰值过高，阻塞主线程。 解决：

  1. 使用Web Worker：如前面示例所示，将计算任务移到后台线程。
  2. 流式/增量计算：不要一次性读取整个文件。使用 File 对象的 stream() 方法获取一个 ReadableStream，然后分块读取并增量更新哈希值。像 spark-md5 这样的库就支持增量更新。
  3. 考虑牺牲秒传：对于超大型文件，如果计算哈希的耗时和体验损耗超过了秒传带来的收益，可以考虑不计算完整文件哈希，而是使用“文件大小+修改时间+前1MB数据的哈希”作为弱标识，或者完全依赖后端的分片列表状态管理。

6.3 并发数设置过高导致的上传失败

问题：为了提高速度，我将并发数设置为10。在用户网络环境较好时，速度确实快。但在一些网络一般的用户端，出现了大量分片上传超时或失败。 分析：浏览器对同一域名下的并发HTTP请求数有限制（HTTP/1.1通常是6个，HTTP/2可以更多）。但即使没有达到浏览器限制，过高的并发数也会在用户带宽有限的情况下造成TCP连接竞争，导致每个请求的速度都很慢，更容易超时。 解决：不要将并发数设为一个固定值。一个好的实践是设置一个保守的默认值（如3-4），并实现一个简单的自适应逻辑：统计最近几个分片上传的平均速度，如果速度持续很快且没有失败，可以缓慢增加并发数；如果出现失败或速度下降，则立即降低并发数。

6.4 本地进度存储与后端状态不一致

问题：用户上传到一半，刷新了页面。前端从 localStorage 恢复了进度，显示已上传50%。但继续上传时，后端返回错误，说某些分片已存在。 排查：发现是本地存储的进度信息“脏”了。可能的原因有：1) 用户手动清理了浏览器数据；2) 同一文件被不同标签页同时上传，导致状态混乱；3) 后端在合并后或清理任务中删除了临时分片，但前端不知道。 解决：

  1. 后端状态为权威来源：这是最重要的原则。前端在每次续传时，必须首先调用 /check 接口，用后端返回的已上传列表来校正本地的进度。本地存储仅用于提升用户体验（如刷新后快速显示一个大概进度），不能用于业务逻辑决策。
  2. 使用更稳定的存储：考虑使用 IndexedDB 代替 localStorage 存储进度，它容量更大，且是异步操作，不会阻塞主线程。
  3. 添加上下文标识：在存储进度时，不仅存储文件哈希和分片索引，还存储一个“上传会话ID”（如开始上传时的时间戳）。这样，可以区分同一文件的不同上传会话，避免冲突。

6.5 合并大文件时的服务器超时

问题：用户上传了一个包含1000个分片的10GB文件。点击合并后，前端请求长时间挂起，最后超时失败。 排查：后端在同步地、流式地将1000个小文件读取并写入一个大文件。这个过程耗时可能超过30秒，而HTTP服务器或负载均衡器（如Nginx）的默认代理超时时间可能只有30秒或60秒。 解决：

  1. 异步合并：如前文所述，合并操作必须异步化。接收到合并请求后，立即返回一个 202 Accepted 响应和一个任务ID。
  2. 状态轮询：前端定期轮询一个如 GET /api/upload/merge-status/:taskId 的接口，获取合并任务的状态（处理中、成功、失败）。
  3. 使用流式API：在合并时，使用 fs.createReadStream 和 fs.createWriteStream 的管道（pipe）操作，避免一次性加载所有分片数据到内存。
  4. 调整超时设置：如果必须同步合并（不推荐），务必调整后端应用服务器和上游代理（Nginx）的读写超时设置。

实现大文件断点续传，是一个融合了前端文件处理、网络编程、后端存储管理和状态设计的综合性课题。从简单的分片上传，到考虑秒传、并发控制、错误恢复，再到与云存储服务的深度集成，每一步都需要仔细权衡和设计。希望这篇超过五千字的详细拆解，能为你提供一个清晰、可落地的实现蓝图。记住，没有一劳永逸的方案，最好的方案总是根据你的具体业务需求、技术栈和用户场景打磨出来的。在实际动手时，不妨先从最核心的分片上传和断点续传做起，跑通流程，再逐步叠加秒传、更优的并发控制等进阶特性。

分片上传及断点续传原理深入分析及示例Demo
本文详细解析了分片上传和断点续传的原理与实现，阐述了在网络环境不佳时如何通过分片上传提高文件上传效率，以及在上传中断后如何通过断点续传继续上传未完成的部分。
DreamMakers
39150
Vue实现大文件分片上传，包括断点续传以及上传进度条
文章详细介绍了分片上传的原理和步骤，包括文件切片、MD5加密、断点续传、并行上传和错误处理。通过使用Promise和axios，实现了文件上传过程中的进度跟踪、错误恢复和文件完整性校验。还讨论了如何与后端协作以支持秒传和断点续传功能。
叶落如梦星
23388
Java如何实现大文件分片上传,断点续传和秒传
本文聚焦文件上传模块中大文件上传难题，介绍了秒传、分片上传和断点续传的概念、应用场景及实现方法。前端对文件MD5加密并分片，校验后进行秒传或分片上传，后端校验MD5值写入数据。还提及Java后端实现的前置知识，如RandomAccessFile、MappedByteBuffer等。
Binary Oracle
4807
Vue3 + Express 实现大文件分片上传、断点续传、秒传
本文介绍了使用Vue3和Express实现大文件分片上传、断点续传和秒传的方法。先阐述了分片上传原理，可降低失败风险、加快速度。接着说明了项目搭建、获取文件、分片、计算hash值、上传及合并的实现步骤，最后讲解了秒传和断点续传的前端与后端实现。
贫僧法号依平
2153
SpringBoot实现文件分片上传+断点续传，一文搞定大文件上传痛点
本文详细解析如何使用SpringBoot实现大文件的分片上传与断点续传功能，解决传统上传方式中内存溢出、请求超时及无法续传等问题。通过分片处理、Redis状态管理及异步合并策略，构建高可用上传系统，并提供前后端实现要点与常见避坑指南。
北风朝向
2255
前端大文件分片上传详解 - Spring Boot 后端接口实现
在Web应用中，一次性上传大文件存在诸多问题。本文介绍基于前端原生JavaScript和Spring Boot实现大文件分片上传的方法，包括实现思路、前后端完整方案，还可扩展断点续传。此外，提供分片秒传优化、并行合并加速、安全增强等高级优化方案，提升上传稳定性和用户体验。
Micro麦可乐
7662
java springBoot 一个demo搞定大文件上传 分片上传 断点续传 秒传
该博客聚焦于Java Spring Boot和JS实现文件上传，阐述小文件上传方法，重点介绍大文件分片上传、断点续传和秒传技术。分析简单文件上传大文件的隐患，详细说明各特性实现原理与流程，包括前后端代码及注意事项，以提升文件传输效率。
跑快点，懦夫！
9309
【前端面试系列】大文件上传以及分片上传与断点续传
本文围绕大文件上传，介绍了分片上传和断点续传的概念、原理、特性对比。阐述了其在大文件加速、网络差等场景的应用，分析了优缺点。还给出面试题及解答，包括概念、场景、陷阱解决和性能优化等方面，助力提升大文件上传性能与用户体验。
徐白1177
2214
iOS大文件分片上传和断点续传
本文详细介绍了如何在iOS应用中实现大文件的分片上传和断点续传功能。首先，通过UIImagePickerController获取大文件，然后将文件分片，利用本地状态记录每片上传进度。在网络中断后，可以从断点处继续上传，提高上传效率。同时，文章提到了文件管理、状态标记以及并发上传的重要性，确保大文件上传的可靠性和效率。
9559
【高频考点精讲】前端大文件上传方案：分片上传、断点续传实现原理
本文介绍前端大文件上传的分片上传与断点续传方案。分片上传可突破请求大小限制、实现续传和提升速度；断点续传类似游戏存档。还给出基于Vue+Axios的完整实现方案，提及服务端配合要点、性能优化技巧及实际应用场景，最后留了课后思考题。
全栈老李技术
1146
Vue3大文件分片上传与断点续传实战（万字长文详解）
本文围绕Vue3大文件分片上传与断点续传展开。介绍了大文件上传痛点及技术方案，确定前端用Vue3等、后端用Node.js等的技术栈。详细阐述实现原理、前端和服务端实现，给出高级优化策略和生产环境注意事项，还进行效果演示并解答常见问题，最后总结成果与后续优化方向。
北辰alk
4524
大文件分片上传：原理、实现与最佳实践
现代应用中，用户上传大文件需求增长，传统上传方式存在痛点。大文件分片上传技术将文件拆分为小块逐个上传，解决了这些问题。本文解析其原理、实现方法，给出代码示例和最佳实践，还介绍了适用场景、限制与解决方案，能提升上传可靠性和用户体验。
vvilkin的学习备忘
2336
前后端大文件分片上传、断点续传和秒传
本文详细描述了如何在项目开发中实现小文件上传、大文件分片上传、断点续传以及秒传的功能，包括前端使用JavaScript和SpringBoot后端的实战代码示例。
月轩居士
1287
基于SpringBoot和WebUploader实现大文件分块上传.断点续传.秒传
本文详细介绍了一种基于SpringBoot和WebUploader的大文件分片上传方案，包括分片上传、断点续传及秒传技术的实现原理和具体流程。通过前端分片上传和后端合并分片的方式提高大文件上传效率。
萤火AI百宝箱
8164
RuoYi-Vue大文件上传：分片上传与断点续传
本文介绍了如何在RuoYi-Vue框架中实现大文件的分片上传与断点续传功能。针对大文件上传面临的网络不稳定、服务器限制及用户体验问题，详细讲解了分片上传的工作流程、前端与后端的具体实现，并提供完整的实施步骤和测试方法。
纪栋岑Philomena
1037
【大前端】 断点续传 + 分片上传（大文件上传优化） 的前端示例
本文介绍了大文件上传的优化方案，包括分片上传和断点续传技术。通过将文件切分为固定大小的分片并逐个上传，结合唯一标识和已上传分片校验，实现高效上传和断点续传。文章还讲解了分片上传的原理、流程、优势及注意事项，并提供了前端实现示例及后端接口约定。
柯南二号
1739
SpringBoot - 大文件分片上传系统：从原理到实践的完整指南
本文介绍了基于SpringBoot的大文件分片上传系统的实现方法。通过将大文件拆分为多个小块进行传输，解决了传统上传方式存在的超时、内存溢出等问题，并支持断点续传、并发上传等功能。文章涵盖了系统架构设计、核心技术实现及部署优化等内容。
小小工匠
2022
Java 大文件上传实战：从底层原理到分布式落地（含分片 / 断点续传 / 秒传）
本文深入讲解Java大文件上传的底层原理与实战实现，涵盖分片上传、断点续传和秒传机制。基于Spring Boot、MyBatis-Plus、MinIO和Redis构建系统，详细解析前后端协同流程及关键技术选型，提供完整的代码结构与测试方案，适用于高可用、高性能文件服务场景。
一叶飘零_sweeeet
1536
告别上传失败！Dio分片上传与断点续传实战指南
本文详解基于Dio实现大文件分片上传与断点续传的技术方案，涵盖分片原理、Stream API应用、CancelToken控制上传流程、错误重试机制及性能优化策略，显著提升大文件上传成功率，适用于Flutter与Dart应用场景。
荣杏姣Samantha
1010
java实现大文件上传分片上传断点续传.zip
本项目"java实现大文件上传分片上传断点续传.zip"提供了一个基于SpringBoot框架的解决方案，它实现了大文件的分片上传和断点续传功能。以下是关于这个项目的关键知识点的详细说明：1.
6725
springboot大文件分片上传
springboot 大文件上传，支持分片并发上传、断点续传、秒传，已经测试过1.2G的文件，最大支持理论无限制博文链接:https://blog.csdn.net/haohao123nana/art
haohao123nana
4745
php+html5实现无刷新上传，大文件分片上传，断点续传
一旦所有分片成功上传，再在后台合并成原始文件。3. **断点续传**： 断点续传是在上传过程中，如果因为网络问题中断，可以从上次断开的地方继续上传，而不是重新开始。
橙虚缘
2901
基于minio webuploader实现的分片上传 断点续传
断点续传原理： 断点续传技术主要依赖于服务器端保存每个分片的上传状态。在上传过程中，客户端会记录每个分片的上传进度，并将其发送到服务器。如果上传中断，客户端可以根据这些信息请求服务器恢复未完成的上传。
qq_30935015
7675
springboot+vue 大文件上传 包括断点续传 秒传 分片上传.zip
本项目"springboot+vue 大文件上传 包括断点续传 秒传 分片上传.zip"提供了一套完整的解决方案，针对大文件上传进行了优化，确保了上传的高效性和可靠性。
千元小钢蹦
3054
SpringBoot 中大文件（分片上传）断点续传与极速秒传功能的实现
SpringBoot 中大文件（分片上传）断点续传与极速秒传功能的实现在本文中，我们将探讨如何在 SpringBoot 框架中实现大文件（分片上传）断点续传与极速秒传功能。
weixin_38623255
5727
大文件上传支持断点续传springboot版
因此，分片上传是解决这个问题的关键。这种技术将大文件分割成多个小块，逐个上传，即使上传过程中出现中断，也可以通过记录已上传的文件片断，下次从断点继续上传，提高了上传的成功率。
一切都只是开始
3458
java大文件分片上传示例
本示例将详细介绍如何使用Java实现大文件的分片上传。首先，理解大文件分片上传的概念：将一个大文件分割成多个小块（称为“片”），然后逐个上传这些片，最后在服务器端将这些片重新组合成原始文件。
weixin_37816323
2662
MinIo最佳性能分片上传、断点续传方案
**分片原理**：当上传大文件时，将其分割成多个小块（称为分片），然后逐个上传。这种方式可以提高上传速度，因为多个分片可以并发上传，同时降低了单个网络问题导致整个文件上传失败的风险。2.
苹榆枫
2677
springboot+vue实现超大文件分片极速上传与下载完整前后端源码
这个系统结合了Spring Boot后端框架和Vue.js前端框架，以实现文件的分片上传与下载功能，同时具备断点续传和秒传特性，为用户提供了流畅的文件操作体验。
weixin_52041354
2924