Vue 实战：利用 IndexedDB 实现前端大文件断点续传

一、背景与痛点

前端下载大文件时，我们通常的做法是一行 fetch 拿到 response，转成 Blob，再丢给一个隐藏的 <a> 标签触发下载。这套逻辑在几十 KB 的图片、几百 KB 的 PDF 上完全没问题。可一旦文件跑到 100MB、1GB，问题就来了：

• 浏览器内存扛不住。 fetch 把整个 response body 读到内存数组里，100MB 的文件就是 100MB+ 的堆内存占用，稍微大一点就直接 OOM。
• 刷新归零。 进度条跑到 80%，用户手滑刷新了页面——从头再来，已经下载的数据全丢了。
• 无法暂停恢复。 浏览器原生没有"暂停下载"的概念，fetch 一旦发起，要么等到结束，要么 abort 掉全部作废。

这背后本质上是两个问题：流式数据怎么持久化，以及已持久化的数据怎么在下次请求时被服务器"认账"。第一个问题用 IndexedDB 解决，第二个问题靠 HTTP Range 请求。

本文基于一个完整的 Vue 2 + Element UI 实战项目，把这两块串起来，讲清楚如何实现一个带持久化存储、支持断点续传、进度精确到小数点后两位的大文件下载方案。

二、核心原理：Range 请求与 206 响应

HTTP 协议从 1.1 开始就定义了一个叫 Range 的请求头，语义很简单：告诉服务器"我只要这个文件的一部分"。

Range: bytes=5000000-

上面这行表示：从第 5,000,000 个字节开始，把后面的内容都给我。服务器如果支持分段传输，会返回 206 Partial Content，同时在 Content-Range 响应头里告诉客户端三件事：本次数据的起止位置，以及文件的完整大小。

Content-Range: bytes 5000000-104857599/104857600

格式是 bytes 起始-结束/总大小。这个 header 是整个断点续传的核心——客户端靠它知道文件有多大，以及自己还差多少。

如果服务器不支持 Range（比如某些 CDN 或静态文件服务器没开这个能力），它会忽略 Range 头，照常返回 200 和完整文件。所以我们的代码需要兼容两种情况：206 就走续传逻辑，200 就清空旧数据从头来。

三、存储方案选型：为什么不用 LocalStorage

有人会想：浏览器不是有 LocalStorage 吗，5MB 够不够？答案是一票否决的——LocalStorage 只能存字符串，不能存二进制数据。

对比维度	LocalStorage	IndexedDB
容量上限	5-10MB	浏览器可用磁盘的 50%-80%
数据类型	仅字符串	String、Blob、ArrayBuffer、File
存储模式	同步（阻塞主线程）	异步（不阻塞 UI）
查询能力	仅 key-value	支持索引、游标遍历

对于大文件下载场景，核心要求有三个：

1. 必须存二进制。 fetch 流式读取出来的是 Uint8Array 二进制块，LocalStorage 根本塞不进去。
2. 容量必须大。 一个 100MB 的测试文件，存进去就是 100MB。LocalStorage 的 5MB 上限连塞牙缝都不够。
3. 必须异步。 你不想每次写盘都卡 UI 渲染。

IndexedDB 是浏览器内置的事务型对象数据库，支持结构化克隆算法，ArrayBuffer 可以直接作为值存入，这些特性让它天然适合做文件分片的持久化。

四、实战代码拆解

4.1 项目架构简述

src/
├── db/downloadDB.js              # IndexedDB 操作封装
├── store/index.js                # Vuex 状态管理
├── App.vue                       # 根实例：核心下载逻辑
└── components/DownloadChild.vue  # 下载按钮子组件

• DownloadChild 通过 Vuex dispatch('requestDownload', { url, filename }) 发起下载指令
• App.vue 通过 computed 属性监听 Vuex 中 downloadTask.timestamp 的变化，触发实际下载
• downloadDB.js 封装所有 IndexedDB CRUD 操作，与业务逻辑解耦

4.2 数据库设计

首先看数据库结构——一个 object store，一个索引，足以支撑整个断点续传：

const DB_NAME = 'DownloadDB'
const STORE_NAME = 'chunks'

function openDB() {
  return new Promise((resolve, reject) => {
    const request = indexedDB.open(DB_NAME, 1)
    request.onupgradeneeded = (e) => {
      const db = e.target.result
      if (!db.objectStoreNames.contains(STORE_NAME)) {
        const store = db.createObjectStore(STORE_NAME, {
          keyPath: 'id',
          autoIncrement: true
        })
        store.createIndex('filename', 'filename', { unique: false })
      }
    }
    request.onsuccess = (e) => resolve(e.target.result)
    request.onerror = (e) => reject(e.target.error)
  })
}

每条记录包含五个字段：id（自增主键）、filename（用于索引查询）、chunkIndex（分片序号，用于最终排序合并）、data（ArrayBuffer，实际二进制数据）、size（当前分片的字节数，用于进度累加）。

选择 autoIncrement 主键而非 [filename, chunkIndex] 复合主键，是因为 IndexedDB 的复合主键在游标遍历时性能不如单字段索引，而我们的 clearChunks 操作依赖游标删除，这是写入频率较高的路径。

4.3 核心下载流程：Range 请求 + 流式持久化

整个 startDownload 方法是断点续传的核心，我按执行顺序拆成五个阶段来讲解。

阶段一：查询已下载字节

let loadedSize = await getDownloadedSize(filename)

这里遍历 IndexedDB 中该文件的所有 chunk，累加 size 字段求和。即使之前页面刷新过、甚至浏览器重启过，只要 IndexedDB 中的数据还在，就能准确拿到已经下载了多少字节。

阶段二：构造 Range 请求

const headers = {}
if (loadedSize > 0) {
  headers['Range'] = `bytes=${loadedSize}-`
}

const response = await fetch(url, {
  signal: this.abortController.signal,
  headers
})

如果 loadedSize 为 0（首次下载或之前已清理），就不带 Range 头，服务器返回完整文件。如果大于 0，告诉服务器"从第 N 个字节开始给我"。

这里同时传入 AbortController 的 signal，方便用户取消下载时中断 fetch。

阶段三：处理 206 vs 200

let totalSize

if (response.status === 206) {
  const contentRange = response.headers.get('Content-Range')
  totalSize = parseInt(contentRange.split('/')[1])
} else if (response.status === 200) {
  if (loadedSize > 0) {
    await clearChunks(filename)
    loadedSize = 0
  }
  totalSize = +response.headers.get('Content-Length')
} else if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${response.statusText}`)
}

这是整个方法里最容易踩坑的分支逻辑：

• 206：服务器认了 Range，返回部分内容。我们从 Content-Range: bytes 5000000-104857599/104857600 中取斜杠后面的 104857600 作为文件总大小。注意不是 Content-Length——206 响应中的 Content-Length 只表示本次返回的 body 大小，不是完整文件大小。
• 200：服务器不支持 Range。如果此时 IndexedDB 里还有旧数据，必须清空，因为之前存的 chunk 和现在返回的完整数据会产生重叠和错乱。
• 其他非 2xx：直接抛异常，交给 catch 处理。

阶段四：流式读取并逐块写入 IndexedDB

const reader = response.body.getReader()
let chunkIndex = await getChunkCount(filename)

while (true) {
  const { done, value } = await reader.read()
  if (done) break

  await saveChunk(filename, chunkIndex++, value)
  loadedSize += value.length
  this.downloadPercent = parseFloat(
    ((loadedSize / totalSize) * 100).toFixed(2)
  )
}

response.body.getReader() 拿到的是 ReadableStream 的 reader，每次 read() 返回一个 { done, value } 对象，value 是一个 Uint8Array，大约是几 KB 到几十 KB 不等的二进制块。

关键细节在 saveChunk 里：

export async function saveChunk(filename, chunkIndex, data) {
  const db = await openDB()
  return new Promise((resolve, reject) => {
    const tx = db.transaction(STORE_NAME, 'readwrite')
    const store = tx.objectStore(STORE_NAME)
    const buffer = new Uint8Array(data).buffer  // 拷贝一份
    store.add({ filename, chunkIndex, data: buffer, size: buffer.byteLength })
    tx.oncomplete = () => { db.close(); resolve() }
    tx.onerror = (e) => { db.close(); reject(e.target.error) }
  })
}

new Uint8Array(data).buffer 这一步一定要做。reader.read() 返回的 Uint8Array 可能共享一个更大的底层 ArrayBuffer，直接存入 IndexedDB 会导致数据不完整或错乱。做一个拷贝，虽然多花了一点内存，但保证了数据的正确性。

阶段五：合并分片，触发下载，清理

async mergeAndSave(filename) {
  const chunks = await getAllChunks(filename)
  const blob = new Blob(chunks, { type: 'application/octet-stream' })
  const url = URL.createObjectURL(blob)
  const a = document.createElement('a')
  a.href = url
  a.download = filename
  document.body.appendChild(a)
  a.click()
  document.body.removeChild(a)
  URL.revokeObjectURL(url)

  await clearChunks(filename)
}

从 IndexedDB 按 chunkIndex 升序取出所有分片，每个分片还原成 Uint8Array，直接传给 Blob 构造函数。Blob 可以接受 Uint8Array[] 数组，会自动拼接。

下载完成后务必调用 clearChunks——既释放用户磁盘空间，也避免下次下载时 IndexedDB 里残留旧数据。清理逻辑使用游标遍历删除：

export async function clearChunks(filename) {
  const db = await openDB()
  return new Promise((resolve, reject) => {
    const tx = db.transaction(STORE_NAME, 'readwrite')
    const store = tx.objectStore(STORE_NAME)
    const index = store.index('filename')
    const cursorReq = index.openCursor(IDBKeyRange.only(filename))
    cursorReq.onsuccess = (e) => {
      const cursor = e.target.result
      if (cursor) {
        cursor.delete()
        cursor.continue()
      }
    }
    tx.oncomplete = () => { db.close(); resolve() }
    tx.onerror = (e) => { db.close(); reject(e.target.error) }
  })
}

这里用游标而不是 index.getAll() + 逐条 store.delete() 的原因有两个：一是游标一次只持有当前记录，内存友好；二是游标删除在一次事务内完成，要么全部成功要么全部回滚。

4.4 取消即保存

注意代码中 startDownload 的 catch 分支：

catch (err) {
  if (err.name === 'AbortError') {
    this.progressStatus = 'exception'
    return   // 不清理 IndexedDB
  }
  // ...
}

AbortError 代表用户主动取消——此时 IndexedDB 中的数据不会被清理。用户下次点击下载按钮，getDownloadedSize 会读到之前累积的字节数，自动从断点继续。

4.5 进度精度：为什么是 toFixed(2)

进度计算公式本身很简单：

this.downloadPercent = parseFloat(((loadedSize / totalSize) * 100).toFixed(2))

toFixed(2) 把百分比控制到两位小数，这样 100MB 文件的最小分辨率约为 1MB × 0.01% ≈ 10KB。每次 reader.read() 返回的 chunk 大约是几十 KB，进度条每隔几个 chunk 就会有一次肉眼可见的变化，不会出现"卡在 99% 不动"的体感。

配合 Element UI 的 el-progress 组件，用 format 属性自定义显示文本：

<el-progress
  :percentage="downloadPercent"
  :stroke-width="20"
  :text-inside="true"
  :format="percentFormat"
/>

percentFormat(pct) {
  return pct.toFixed(2) + '%'
}

这样进度条内部会显示 33.56% 这样的精确数值，而不是默认的 34%。

五、总结

这套方案本质上做了一件事：把浏览器的持久化存储能力和 HTTP 协议的分段传输能力结合起来，让大文件下载从"一次性内存操作"变成"可暂停、可恢复、状态可持久化的流式管道"。

实战中值得记住的几个点：

• fetch + ReadableStream 是流式处理二进制数据的基础设施，response.body.getReader() 是拿到这块能力的入口。
• IndexedDB 是前端唯一能存大容量二进制数据的方案，但它基于事务，有并发限制，封装时要注意 Promise 化并确保每次操作后关闭连接。
• 断点续传的关键在于对 206 和 200 的分支处理，尤其是"服务器不支持 Range 时要清空旧数据"这个逻辑，遗漏了就会导致文件损坏。
• 进度条只是 UI 层面的反馈，真正的可靠性在于 IndexedDB 中的数据完整性——每一块 chunk 存入前做一次独立的 ArrayBuffer 拷贝，代价很小，收益是绝对的确定性。