Streams API 實戰：瀏覽器端串流大檔案處理架構

為什麼需要串流處理？

傳統方式讀取大檔案：

// ❌ 200MB 檔案 → 200MB ArrayBuffer → 可能 OOM
const buffer = await file.arrayBuffer();
processEntireBuffer(buffer);

串流處理：

// ✅ 每次只處理 64KB chunk
const stream = file.stream();
for await (const chunk of stream) {
  processChunk(chunk); // 64KB
}

對比	全量載入	串流處理
記憶體佔用	檔案大小	~64KB（chunk 大小）
開始處理	全部讀完	第一個 chunk 到達
200MB 檔案	200MB 記憶體	~64KB 記憶體
1GB 檔案	可能 OOM	正常運行

---

三種核心 Stream

ReadableStream  →  資料來源（檔案、網路回應）
TransformStream →  中間處理（壓縮、加密、格式轉換）
WritableStream  →  資料目的地（檔案下載、網路上傳）

ReadableStream

const response = await fetch('/large-file.pdf');
const reader = response.body!.getReader();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(`Received ${value.byteLength} bytes`);
}

TransformStream

const compressor = new TransformStream({
  transform(chunk, controller) {
    const compressed = gzipSync(chunk);
    controller.enqueue(compressed);
  }
});

// 管道連接
fileStream.pipeThrough(compressor).pipeTo(downloadStream);

---

背壓 (Backpressure)

當生產者速度 > 消費者速度時，Stream 自動暫停生產者：

FileReader（快）→ [緩衝區滿] → 暫停讀取
                      ↓
              TransformStream（慢）→ 消費 chunk → 緩衝區有空間 → 恢復讀取

這是 Stream 相較手動 chunk 迴圈的核心優勢——自動流量控制，無需手動管理緩衝區大小。

---

工具庫中的串流應用

Gzip 壓縮／解壓

壓縮解壓工具 使用 CompressionStream API：

const compressed = file.stream().pipeThrough(new CompressionStream('gzip'));
// 串流壓縮，無需全量載入

大 PDF 分塊讀取

async function* readPdfChunks(file: File, chunkSize = 4 * 1024 * 1024) {
  let offset = 0;
  while (offset < file.size) {
    const chunk = file.slice(offset, offset + chunkSize);
    yield await chunk.arrayBuffer();
    offset += chunkSize;
  }
}

for await (const chunk of readPdfChunks(largePdf)) {
  await processPdfChunk(chunk);
}

串流下載

const stream = new ReadableStream({
  async start(controller) {
    for await (const chunk of generateChunks()) {
      controller.enqueue(chunk);
    }
    controller.close();
  }
});

const response = new Response(stream, {
  headers: { 'Content-Disposition': 'attachment; filename="output.zip"' }
});

---

Stream API 相容性

API	Chrome	Firefox	Safari	Edge
ReadableStream	52+	65+	10.1+	79+
TransformStream	80+	102+	14.1+	80+
CompressionStream	80+	113+	16.4+	80+
File.stream()	76+	69+	14.1+	79+

CompressionStream 較新，不支援的瀏覽器回退至 pako/fflate 函式庫的全量處理。

---

總結

Streams API 是處理大檔案的現代標準。ReadableStream 分塊讀取、TransformStream 中間處理、背壓自動流控——這套機制讓瀏覽器端處理 GB 級檔案成為可能，是工具庫大檔案工具（PDF、影片、壓縮）的底層基礎設施。