[!info] related notes

• 所属 MOC: 前端工程化 MOC
• 前置概念: 前端切片与并发控制, 后端状态管理与分块合并
• 并列概念: 秒传机制
• 关系笔记: 大文件传输系统设计

断点续传机制

一句话定义

断点续传是在上传中断后，通过前端本地保存的上传上下文和后端返回的已上传 chunk 列表，只重传未完成的部分。

核心内容

基本原理

断点续传依赖两个关键点：

1. 前端本地保存上传上下文
2. 后端记录每个 chunk 的上传状态

前端状态保存

可存在 localStorage 或 IndexedDB：

保存内容：

• fileHash：文件唯一标识
• uploadId：上传任务 ID
• chunkSize：分块大小
• 文件名
• 上传时间

恢复流程

1. 用户重新进入页面
2. 前端读取本地保存的上传上下文
3. 调用 /upload/init 或 /upload/status 查询
4. 后端返回已上传 chunk 列表：[0, 1, 2, 3, 7, 8, 9]
5. 前端只上传剩余 chunk：4, 5, 6, 10…

关键限制

浏览器刷新后原 File 对象丢失，通常需要：

• 用户重新选择同一个文件
• 因为 hash 一致，系统能识别并继续上传剩余块

前端暂停/恢复实现

暂停：

• 停止继续派发新的 chunk
• 用 AbortController 中止正在进行的请求
• 记录当前状态

恢复：

• 查询已上传 chunk
• 从剩余 chunk 继续传

const controller = new AbortController();

// 暂停
controller.abort();

// 恢复时重新查询状态，继续上传

边界与易混淆点

• 断点续传 ≠ 分块上传：分块是基础能力，断点续传是在分块基础上的状态恢复机制
• 前端 vs 后端断点续传：HTTP Range 请求是下载侧的断点续传，上传侧需要专门设计
• hash 不一致问题：如果文件内容变了（hash 变了），之前的上传进度无法复用，需要重新上传

Related notes

• 前端切片与并发控制
• 大文件传输概述
• Uppy
• tus 协议