纯客户端数据安全备份：Web Streams API 实现超大 IndexedDB 数据无感流式导出

在践行「本地优先（Local-First）」与「数据主权完全属于用户」的手账工具开发中，最核心的一道安全生命线就是：数据导出与离线归档备份。

用户在你的离线手账里写了半年日记、存了几百张手绘水彩插画与各种导出长图，数据全部保存在浏览器底层的 IndexedDB 中。这时候用户会产生一种极其强烈的本能诉求：「我能不能把我的所有数据完整下载成一个本地 .json 备份文件，存到我的 U 盘或者机械硬盘里？」

在过去，很多前端开发者的导出代码都写得很原始：

// 极其危险的内存自杀式导出写法
const allData = await localDB.getAllNotes();
const jsonString = JSON.stringify(allData); // 内存瞬间暴涨！
const blob = new Blob([jsonString], { type: 'application/json' });
const url = URL.createObjectURL(blob);
// 模拟 <a> 标签下载…

当数据只有几十条时，这段代码运转良好。但当用户的数据库膨胀到几百兆（包含高分辨率画作 Base64 或二进制像素）时：

• JSON.stringify 会在 V8 引擎中尝试分配一段数亿字符的超长连续字符串，直接抛出 RangeError: Invalid string length 内存溢出（OOM）；
• 手机端浏览器瞬间卡死闪退，用户以为所有日记都被软件吞了，造成严重的恐慌与信任危机。

要实现真正工业级的大数据无感导出，必须采用流式管道思想（Streams Pipeline）：利用现代 Web 标准的 Web Streams API（ReadableStream + TextEncoderStream），配合游标（Cursor）做到边从数据库读取、边序列化切片、边流式冲刷进下载管道，让整场数百兆的导出过程，内存占用恒定压制在 5MB 以内！

今天这篇文章，我将带大家完整手写这套基于 Web Streams 的纯前端流式备份系统。

一、传统 Blob 导出与 Web Streams 流式管道的内存模型对比

为什么流式导出能彻底消灭内存溢出？我们来看两种模式在系统堆内存中的流向对比：

+————————————————————-+
| Web Streams 流式备份管道架构 |
+————————————————————-+
| [ IndexedDB 游标底层源 ] |
| – 逐条读出单篇手账 (避免批量膨胀) |
| | |
| v controller.enqueue(jsonChunk) |
| [ ReadableStream 字符流 ] |
| – 输出 JSON 数组开合: "[" -> 记录1 -> "," -> 记录2 -> "]"|
| | |
| v .pipeThrough() |
| [ TextEncoderStream 原生流式转码器 ] |
| – 毫秒级转换为 UTF-8 二进制 Uint8Array 块 |
| | |
| v .pipeTo() |
| [ 本地文件系统 / File System Access API / 流式下载管道 ] |
| – 直接写入本地磁盘 handbook-backup-2026.json! |
| * 全程内存开销恒定在 3MB ~ 5MB，导出 1GB 数据也如丝般顺滑! |
+————————————————————-+

二、代码实战：纯前端流式 JSON 备份导出器

我们来动手实现这个零依赖的原生流式备份引擎：

// stream-backup-exporter.js：基于 Web Streams 的大容量流式导出引擎
export class StreamHandbookExporter {
constructor(dbInstance) {
this.db = dbInstance;
}

// 构建只读手账流
createReadableStream() {
const db = this.db;

return new ReadableStream({
async start(controller) {
// 1. 发送 JSON 数组的开端符号 "["
controller.enqueue('[\\n');

const transaction = db.transaction(['notes'], 'readonly');
const store = transaction.objectStore('notes');
const request = store.openCursor();

let isFirst = true;

request.onsuccess = (event) => {
const cursor = event.target.result;
if (cursor) {
// 如果不是第一条，追加逗号分隔符
const prefix = isFirst ? ' ' : ',\\n ';
isFirst = false;

// 仅对当前单条手账记录进行序列化，内存开销微乎其微！
const jsonChunk = prefix + JSON.stringify(cursor.value);
controller.enqueue(jsonChunk);

// 前进到下一条记录
cursor.continue();
} else {
// 2. 遍历结束，封口 JSON 数组 "]"
controller.enqueue('\\n]');
controller.close();
}
};

request.onerror = (event) => {
controller.error(new Error(`数据库游标异常: ${event.target.error}`));
};
}
});
}

// 触发流式下载（结合现代 File System Access API 或兼容性回退）
async exportToFile(suggestedFileName = 'cozy-handbook-backup.json') {
const textStream = this.createReadableStream();

// 将字符串流通过原生管道转化为二进制流
const binaryStream = textStream.pipeThrough(new TextEncoderStream());

// 方案 A：现代桌面端 File System Access API（Chrome / Edge 等，真流式直写磁盘）
if ('showSaveFilePicker' in window) {
try {
const handle = await window.showSaveFilePicker({
suggestedName: suggestedFileName,
types: [
{
description: 'JSON 手账全量备份文件',
accept: { 'application/json': ['.json'] }
}
]
});

const writable = await handle.createWritable();
// 直接将可读流导入磁盘写入流！
await binaryStream.pipeTo(writable);
console.log('[流式备份] 已通过文件系统原生流式直写完成！');
return;
} catch (err) {
if (err.name === 'AbortError') {
console.log('[流式备份] 用户取消了保存');
return;
}
console.warn('[流式备份] FileSystemAPI 失败，回退至兼容下载:', err);
}
}

// 方案 B：通用浏览器回退（利用 Response 将流包装为下载）
const response = new Response(binaryStream);
const blob = await response.blob();
const downloadUrl = URL.createObjectURL(blob);

const a = document.createElement('a');
a.href = downloadUrl;
a.download = suggestedFileName;
document.body.appendChild(a);
a.click();
a.remove();
URL.revokeObjectURL(downloadUrl);
console.log('[流式备份] 兼容性导出完成！');
}
}

三、与 UI 进度的优雅装配

在手账设置面板中，给用户提供一个极具安全感的导出按钮与状态反馈：

<!– backup-panel.html –>
<div class="backup-card">
<h4>🍂 本地手账安全归档</h4>
<p>将保存在您设备中的所有日记、插画与标签完整流式导出为 JSON 备份文件。</p>
<button id="exportStreamBtn" class="cozy-btn">开始无损流式导出</button>
<div id="exportStatus" class="status-msg"></div>
</div>

// backup-main.js：装配导出器
import { localDB } from './local-handbook-db.js';
import { StreamHandbookExporter } from './stream-backup-exporter.js';

const exportBtn = document.querySelector('#exportStreamBtn');
const statusMsg = document.querySelector('#exportStatus');

exportBtn.addEventListener('click', async () => {
exportBtn.disabled = true;
statusMsg.textContent = '正在建立流式传输管道，导出期间可自由切换窗口…';

try {
const exporter = new StreamHandbookExporter(localDB.db);
const fileName = `听汐手账全量备份_${new Date().toISOString().slice(0, 10)}.json`;

await exporter.exportToFile(fileName);
statusMsg.textContent = '备份已成功保存在您的本地磁盘中 ✨';
} catch (err) {
statusMsg.textContent = `导出异常: ${err.message}`;
} finally {
exportBtn.disabled = false;
}
});

四、生产避坑与安全防线

五、写在最后

真正的自由，是拥有随时带走自己所有数字资产的权利。

通过 Web Streams API 的精密管道，我们让体积庞大的手账记忆能够像山泉一样平稳、清透、安全地流淌回使用者的本地硬盘里。

不将用户的数据作为人质扣留在封闭的云端，把掌控权完完整整地交还给每一个人，这就是独立软件开发中最可贵的工程伦理。