StreamSaver.js 指南：告别浏览器崩溃，轻松保存G级别大文件

最新推荐文章于 2026-08-01 22:57:16 发布

原创最新推荐文章于 2026-08-01 22:57:16 发布 · 1.9k 阅读

31 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

该文章已生成可运行项目，

第一部分：基础篇 - StreamSaver.js 的存在理由与工作原理

在深入研究代码之前，我们首先需要建立一个坚实的理论基础。本部分将阐述 StreamSaver.js 旨在解决的核心问题，以及它为实现其目标所采用的巧妙机制。

1.1 挑战：在内存受限的浏览器中保存千兆字节数据

现代 Web 应用的功能日益强大，可以直接在浏览器中生成海量数据，例如视频录制、大型 CSV 文件导出或客户端加密文件 1。传统的文件保存方法，也是广受欢迎的

FileSaver.js 库所采用的方法，其流程是先在内存中完整地创建一个 Blob 对象，然后生成一个可供下载的链接 2。

这种方法存在一个致命的缺陷：整个文件必须能够完全载入到用户的内存（RAM）中。当文件体积达到数个G时，这种操作极易导致浏览器标签页内存溢出而崩溃，尤其是在内存有限的移动设备上 1。

StreamSaver.js 正是为解决这一难题而生。它另辟蹊径，不将整个文件缓冲在内存中，而是创建了一个从数据源到用户硬盘的直接、异步的数据流（stream）1。这意味着，理论上你可以保存任意大小的文件，其唯一的限制是用户的硬盘空间，而非宝贵的内存。

1.1.1 明确使用场景：客户端生成 vs. 服务端获取

StreamSaver.js 的文档反复强调，它主要用于处理客户端生成的内容 1。如果文件已经存在于服务器上，最佳实践是直接通过配置服务端的响应头

Content-Disposition: attachment，让浏览器以原生方式处理下载。此时不应使用 AJAX 或 fetch 将文件内容拉取到 JavaScript 的运行环境中 1。

一个常见的误区是，开发者使用 fetch 从服务器请求一个大文件，将其响应体转换为一个 Blob，然后再尝试用 StreamSaver.js 来保存这个 Blob。这种做法完全违背了该库的设计初衷，因为在创建 Blob 的那一刻，整个文件已经被加载到了内存中，此时使用 StreamSaver.js 毫无优势，甚至不如直接使用更简单的 FileSaver.js 9。

处理服务端文件的正确模式是：使用 fetch 获取响应，并从响应体 response.body 中得到一个 ReadableStream（可读流），然后将这个流直接“管道连接”（pipe）到 StreamSaver.js。通过这种方式，数据从服务器流经浏览器，最终写入磁盘，全程都未在内存中完整缓冲。

因此，StreamSaver.js 的核心价值主张并非简单地“保存大文件”，而是“在客户端流式生成或处理大文件并保存”。这个区别至关重要，必须在入门之初就清晰地认识到。

表1：文件保存库对比

为了帮助您在不同场景下做出正确的技术选型，下表对几种常见的文件保存方案进行了对比。

特性	`FileSaver.js`	`StreamSaver.js`	原生文件系统访问 API
输入	`Blob`、`File` (数据需完全载入内存)	`ReadableStream` (数据以流的形式存在)	`FileSystemWritableFileStream`
内存占用	高 (与文件大小成正比)	低 (恒定，仅有少量缓冲)	低 (恒定，仅有少量缓冲)
理想使用场景	中小文件 (<500MB)，内存不成问题的客户端文件生成。	G级别的大文件，客户端流生成（如视频录制、加密），流式处理服务端响应。	未来所有客户端文件读写操作的标准，提供读、写、修改等全面能力。
核心机制	`$URL.createObjectURL()$ +` ` 标签	`Service Worker` + `fetch` 请求拦截	浏览器原生 API
现状	成熟，广泛使用。	成熟，官方称为 "legacy-ish" (有点过时) 1，但仍是其特定场景下的最佳方案。	实验性阶段，尚未被所有浏览器普遍支持 1。

1.2 深入幕后：Service Worker 与“中间人”的魔法

一个核心的技术难题是：客户端脚本如何命令浏览器为一个尚不存在的、持续不断的数据流弹出“另存为”对话框？答案是，你无法从一个流创建一个 URL.createObjectURL() 4。

StreamSaver.js 的解决方案堪称一绝：它通过一个 Service Worker 模拟了服务器指示浏览器下载文件的行为 1。

以下是其工作机制的分解步骤 1：

启动：您的主页面代码调用 $streamSaver.createWriteStream('my-file.zip')$ 。
中间人（MITM）：StreamSaver.js 在后台加载一个特殊的HTML页面——mitm.html。这个页面就是所谓的“中间人”（Man-in-the-Middle）。
安装 Service Worker：mitm.html 页面的唯一任务就是注册 sw.js（Service Worker）文件。一旦注册成功，这个 Worker 便获得了拦截源自您页面的网络请求的能力。
建立通信：您的主页面与 mitm.html 之间建立一个 MessageChannel 进行通信，mitm.html 再将这个通信管道传递给 Service Worker。
“伪造”下载：Service Worker 被告知监听一个特定的、唯一的 URL。随后，主脚本触发对这个 URL 的下载（例如，通过设置一个隐藏 iframe 的 src 属性）。
拦截与响应：Service Worker 拦截到对这个“伪造”URL 的请求。它不会将请求发往网络，而是用一个新的 Response 对象来响应它。这个 Response 的响应体就是您在主页面中正在写入的数据流，同时，它还会附上一个至关重要的响应头： $Content-Disposition: attachment; filename="my-file.zip"$ 。
下载开始：浏览器接收到这个响应，识别出 Content-Disposition 头，便会像处理来自真实服务器的文件一样，触发文件下载流程。数据就这样从您的 JavaScript 代码，经由 Service Worker，直接流向了用户的硬盘。

1.2.1 HTTPS 的要求及其带来的架构影响

Service Worker 因其强大的能力，只能在安全上下文（Secure Context）中注册，即 HTTPS 协议的网站或 localhost 1。这一安全限制引发了一系列连锁反应，深刻影响了 StreamSaver.js 的设计。

首先，核心机制依赖于 Service Worker，而 Service Worker 需要 HTTPS。那么，如果开发者的网站是普通的 HTTP 协议呢？此时，库无法直接在当前页面注册 Service Worker。

为了解决这个问题，库采用了一种“popup hack”（弹窗技巧）11。它不再创建一个隐藏的

iframe，而是打开一个新的弹窗来加载 mitm.html。这是因为 StreamSaver.js 默认使用的 mitm.html 托管在作者的一个安全的 GitHub Pages URL 上（https://jimmywarting.github.io/StreamSaver.js/mitm.html）1。弹窗导航到这个安全的、跨域的地址，而这个地址是允许注册 Service Worker 的。

然而，这又带来了新的问题：现代浏览器为了防止恶意广告，会积极地阻止弹窗。为了确保弹窗能够成功打开，调用 $streamSaver.createWriteStream()$ 的操作必须由用户的直接交互（如点击按钮）触发 1。

这一整条因果链解释了为什么“推荐使用 HTTPS”以及“在 HTTP 网站上下载必须由用户发起”是最佳实践。这并非随意的规则，而是浏览器安全模型的直接产物。对于初学者来说，理解这一深层逻辑对于编写健壮的代码和排查问题至关重要。

第二部分：实现篇 - 安装、配置与核心 API

本部分是实践操作指南。我们将引导您完成库的安装配置，并对每个核心 API 进行详尽的参考说明。

2.1 快速上手：安装与配置

引入库

最简单的方式是通过 CDN 引入 StreamSaver.js 及其必要的 web-streams-polyfill。后者是为了兼容那些原生 WritableStream 实现不完整或缺失的旧版浏览器 7。

HTML

<script src="https://cdn.jsdelivr.net/npm/web-streams-polyfill@2.0.2/dist/ponyfill.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/streamsaver@2.0.3/StreamSaver.min.js"></script>

引入后，您可以根据项目的模块系统来使用它 7：

JavaScript

// ES 模块
import streamSaver from 'streamsaver';

// CommonJS (Node.js 环境，通常用于服务端渲染或构建过程)
const streamSaver = require('streamsaver');

// 全局变量 (直接在 <script> 标签中使用)
const streamSaver = window.streamSaver;

`mitm` 配置（生产环境自托管）

默认情况下， $streamSaver.mitm$ 指向作者的 GitHub Pages URL 12。这对于快速测试非常方便，但

不推荐在生产环境中使用。

为什么要自托管？

主要有三个原因：

可靠性：避免您的应用依赖于一个第三方服务，如果该服务中断，您的下载功能将失灵。
安全性：避免与外部站点进行不必要的跨域通信。
离线能力：如果您的应用需要支持离线工作，将所有资源本地化是必须的 14。

如何自托管？

步骤非常简单：

从 StreamSaver.js 的 GitHub 仓库中，找到 mitm.html 和 sw.js 这两个文件，将它们复制到您项目的前端静态资源目录中（例如 public 或 static 文件夹）14。
在您的应用代码中，执行任何下载操作之前，设置 mitm 属性，使其指向您托管的文件路径 7。

JavaScript

// 假设您已将 mitm.html 放在了网站根目录的 assets 文件夹下
streamSaver.mitm = '/assets/mitm.html';

请注意，为了获得最佳体验，此路径应与您的主应用同源，并通过 HTTPS 提供服务。在本地开发时，路径可能是 http://localhost:3000/mitm.html；在生产环境中，则应为 https://your-app.com/mitm.html 15。

2.2 核心 API：逐一详解

`streamSaver.createWriteStream(filename, [options])`

这是启动文件保存流程的入口函数。

语法: $const fileStream = streamSaver.createWriteStream(filename, options);$
参数:
- filename (string): 您希望保存的文件名，例如 'data.csv'。
- options (object, 可选): 一个配置对象。
  - size (number): 文件的总字节数。提供此值可以让浏览器显示下载进度条 7。
  - writableStrategy, readableStrategy: 用于控制流队列行为（即背压）的高级选项。这些主要面向高级用户，详情可参考 WHATWG Streams 规范 7。
返回值: 一个标准的 WritableStream（可写流）对象。需要特别注意的是，这个流只接受 Uint8Array 类型的数据块 7。

可运行 Demo:

HTML

<!DOCTYPE html>
<html>
<head>
  <title>CreateWriteStream Demo</title>
  <script src="https://cdn.jsdelivr.net/npm/web-streams-polyfill@2.0.2/dist/ponyfill.min.js"></script>
  <script src="https://cdn.jsdelivr.net/npm/streamsaver@2.0.3/StreamSaver.min.js"></script>
</head>
<body>
  <button id="createStreamBtn">创建流</button>
  <script>
    document.getElementById('createStreamBtn').onclick = () => {
      const fileStream = streamSaver.createWriteStream('hello.txt');
      console.log('可写流已创建:', fileStream);

      // 在这个演示中，我们只创建流而不写入数据。
      // 一个良好实践是，如果不打算使用这个流，应立即中止它。
      fileStream.getWriter().abort('Demo finished without writing.');
      alert('请查看控制台，可写流已创建但被立即中止。');
    };
  </script>
</body>
</html>

手动方式：使用写入器（Writer）

这是最基础、最手动的写入数据方式。您需要获取一个“写入器”对象，并为每个数据块显式调用 write() 方法。

const writer = fileStream.getWriter(): 获取一个与 fileStream 绑定的写入器对象。一旦获取，流就会被锁定。
writer.write(uint8Array): 写入一个数据块。此方法返回一个 Promise，当数据成功写入时，该 Promise 会被兑现。再次强调，数据块必须是 Uint8Array。您可以使用 $new TextEncoder().encode('some string')$ 将字符串转换为 Uint8Array 4。
writer.close(): 当您写完所有数据后，调用此方法。它会最终确定文件，并完成下载。
writer.abort(reason): 调用此方法可以取消下载。这对于错误处理和资源清理至关重要 4。

可运行 Demo:

HTML

<!DOCTYPE html>
<html>
<head>
  <title>Manual Writer Demo</title>
  <script src="https://cdn.jsdelivr.net/npm/web-streams-polyfill@2.0.2/dist/ponyfill.min.js"></script>
  <script src="https://cdn.jsdelivr.net/npm/streamsaver@2.0.3/StreamSaver.min.js"></script>
</head>
<body>
  <button id="manualWriteBtn">手动写入 "Hello World"</button>
  <script>
    document.getElementById('manualWriteBtn').onclick = async () => {
      const fileStream = streamSaver.createWriteStream('manual.txt');
      const writer = fileStream.getWriter();
      const encoder = new TextEncoder();

      let text1 = 'Hello, this is written chunk by chunk.\n';
      let uint8array1 = encoder.encode(text1);
      await writer.write(uint8array1);
      console.log('第一块数据已写入');

      let text2 = 'This is the second chunk.';
      let uint8array2 = encoder.encode(text2);
      await writer.write(uint8array2);
      console.log('第二块数据已写入');

      await writer.close();
      console.log('文件已手动保存!');
    };
  </script>
</body>
</html>

现代方式：`pipeTo()`

这是更优雅、更现代且官方推荐的方式。它将一个 ReadableStream（可读流）直接连接到您的 WritableStream（可写流）。浏览器会自动处理从源读取数据块并写入目标的全过程，包括自动管理背压（backpressure）。

语法: $readableStream.pipeTo(writableStream)$
适用场景: 当您已经拥有一个 ReadableStream 时，这是完美的选择。常见的来源包括 fetch 响应（ $response.body$ ）或从 Blob/File 对象创建的流（ $blob.stream()$ ）4。
特性检测: 最佳实践是先检查 pipeTo 方法是否存在，如果不存在，则回退到手动写入的方式，以保证兼容性 9。

可运行 Demo:

HTML

<!DOCTYPE html>
<html>
<head>
  <title>pipeTo Demo</title>
  <script src="https://cdn.jsdelivr.net/npm/web-streams-polyfill@2.0.2/dist/ponyfill.min.js"></script>
  <script src="https://cdn.jsdelivr.net/npm/streamsaver@2.0.3/StreamSaver.min.js"></script>
</head>
<body>
  <button id="pipeToBtn">使用 pipeTo 保存</button>
  <script>
    document.getElementById('pipeToBtn').onclick = () => {
      const fileStream = streamSaver.createWriteStream('piped.txt');

      // 创建一个简单的可读流作为数据源
      const readableStream = new ReadableStream({
        start(controller) {
          const encoder = new TextEncoder();
          controller.enqueue(encoder.encode('This was '));
          controller.enqueue(encoder.encode('piped directly!'));
          controller.close(); // 表示数据源已结束
        }
      });

      // 特性检测
      if (readableStream.pipeTo) {
        console.log('pipeTo is supported. Piping now...');
        readableStream.pipeTo(fileStream)
         .then(() => console.log('文件已通过 pipeTo 保存!'))
         .catch(error => console.error('Piping failed:', error));
      } else {
        console.log('pipeTo not supported, manual fallback would be needed here.');
        // 在此实现手动写入的回退逻辑
        fileStream.getWriter().abort();
      }
    };
  </script>
</body>
</html>

第三部分：实战场景 - 解析官方示例

现在，我们将运用所学知识，逐一分析 StreamSaver.js 官方仓库中最常见、最强大的几个用例。

3.1 示例一：将 `fetch` 响应流式传输到文件

目标：在不将文件完全缓冲到内存的情况下，从服务器下载一个大文件。
代码解析：以下是对 fetch.html 示例的完整分析 13。
1. 通过 onclick 事件处理器绑定一个按钮。
2. 调用 $streamSaver.createWriteStream() 准备接收文件流。
3. 发起 fetch(url) 请求。
4. 在 .then() 回调中，获取 $response.body$ ，这就是我们的 ReadableStream。
5. 进行 $readableStream.pipeTo$ 的特性检测。
6. 如果支持，则调用 $readableStream.pipeTo(fileStream)$ 。这是最高效、最简洁的“理想路径”。
7. 如果不支持，代码会回退到一个名为 pump 的手动循环函数中，该函数反复调用 $reader.read()$ 和 $writer.write()$ ，直到流结束。
反面模式重申：再次强调，这才是从服务器下载文件的正确流式方法。它与错误的 $fetch(url).then(res => res.blob()).then(blob =>...)$ 形成鲜明对比，后者完全破坏了流式处理的内存优势 9。

可运行 Demo:

HTML

<!DOCTYPE html>
<html>
<head>
  <title>Fetch Demo</title>
  <script src="https://cdn.jsdelivr.net/npm/web-streams-polyfill@2.0.2/dist/ponyfill.min.js"></script>
  <script src="https://cdn.jsdelivr.net/npm/streamsaver@2.0.3/StreamSaver.min.js"></script>
</head>
<body>
  <button id="fetchBtn">下载一个视频文件</button>
  <script>
    document.getElementById('fetchBtn').onclick = () => {
      // 一个公开的测试视频 URL
      const url = 'https://d8d913s460fub.cloudfront.net/videoserver/cat-test-video-320x240.mp4';
      const fileStream = streamSaver.createWriteStream('cat-video.mp4');

      fetch(url).then(res => {
        // 检查服务器是否返回成功状态
        if (!res.ok) {
          throw new Error('Network response was not ok');
        }

        const readableStream = res.body;

        // 优先使用 pipeTo
        if (window.WritableStream && readableStream.pipeTo) {
          return readableStream.pipeTo(fileStream)
           .then(() => console.log('视频下载完成!'));
        }

        // pipeTo 不可用时的回退方案
        const writer = fileStream.getWriter();
        const reader = res.body.getReader();
        const pump = () => reader.read()
         .then(result => result.done
           ? writer.close()
            : writer.write(result.value).then(pump)
          );

        return pump();
      })
     .catch(error => {
        console.error('下载失败:', error);
        fileStream.getWriter().abort(error);
      });
    };
  </script>
</body>
</html>

3.2 示例二：动态创建 ZIP 压缩包

目标：将多个来源（用户上传、fetch 获取、动态生成）的文件合并成一个 .zip 文件，而无需在内存中构建整个压缩包。
依赖：此功能需要一个额外的辅助脚本 zip-stream.js，该脚本也包含在官方示例中 17。
代码解析：分析 saving-multiple-files.html 示例 18。
1. 它使用了一个 new ZIPStream() 对象，该对象表现得像一个 ReadableStream。
2. 与普通流不同，您向其 enqueue 的不是 Uint8Array，而是类文件对象。
3. 每个类文件对象必须至少包含两个属性：name（字符串，包含在 ZIP 中的完整路径和文件名）和 stream()（一个返回其内容 ReadableStream 的方法）。
4. 示例展示了如何从 File 对象、Blob 或 fetch 响应中创建这些类文件对象。
5. 最后，将这个 ZIPStream 实例通过 pipeTo 连接到由 StreamSaver 创建的 fileStream。
4GB ZIP 限制：这是一个非常关键的细节。示例中提供的 zip-stream.js 并未实现 ZIP64 格式规范，这意味着最终生成的 .zip 文件大小不能超过 4GB。对于需要处理超大文件的开发者来说，这是一个重要的限制 19。

可运行 Demo:

HTML

<!DOCTYPE html>
<html>
<head>
  <title>ZIP Demo</title>
  <script src="https://cdn.jsdelivr.net/npm/web-streams-polyfill@2.0.2/dist/ponyfill.min.js"></script>
  <script src="https://cdn.jsdelivr.net/gh/eligrey/Blob.js/Blob.js"></script>
  <script src="https://cdn.jsdelivr.net/npm/streamsaver@2.0.3/StreamSaver.min.js"></script>
  <script src="https://jimmywarting.github.io/StreamSaver.js/examples/zip-stream.js"></script>
</head>
<body>
  <button id="zipBtn">创建并下载 ZIP 文件</button>
  <script>
    document.getElementById('zipBtn').onclick = () => {
      const fileStream = streamSaver.createWriteStream('archive.zip');

      // 创建一个可读的 ZIP 流
      const readableZipStream = new ZIPStream({
        start(ctrl) {
          // 1. 从字符串创建第一个文件
          const file1 = new File(['这是第一个文件的内容。'], 'folder/file1.txt');
          ctrl.enqueue(file1);

          // 2. 从 Blob 创建第二个文件
          const blob = new Blob();
          const file2 = { name: 'folder/file2.txt', stream: () => blob.stream() };
          ctrl.enqueue(file2);

          // 3. 动态创建一个可读流作为第三个文件的源
          const file3 = {
            name: 'generated-file.txt',
            stream() {
              return new ReadableStream({
                start(controller) {
                  controller.enqueue(new TextEncoder().encode('这个文件是动态生成的！'));
                  controller.close();
                }
              })
            }
          };
          ctrl.enqueue(file3);
        }
      });

      // 将 ZIP 流 pipe 到文件保存流
      if (window.WritableStream && readableZipStream.pipeTo) {
        return readableZipStream.pipeTo(fileStream)
         .then(() => console.log('ZIP 文件创建完成!'));
      }
      // 此处省略回退逻辑
    };
  </script>
</body>
</html>

3.3 示例三：录制并保存用户媒体

目标：从用户的摄像头或麦克风捕获视频/音频，并将其直接保存到文件，从而支持超长时间的录制。
核心 API： $navigator.mediaDevices.getUserMedia()$ 用于获取 MediaStream，MediaRecorder API 用于处理该流 20。
代码解析：
1. 获取用户媒体流： $const stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true });$
2. 使用 StreamSaver 创建可写流： $const fileStream = streamSaver.createWriteStream('my-recording.webm');$
3. 创建 MediaRecorder 实例： $const recorder = new MediaRecorder(stream);$
4. 桥接：这是最关键的一步。MediaRecorder 会触发 dataavailable 事件，该事件的数据块（event.data）是一个 Blob。我们需要将这些数据块写入 StreamSaver 的流中。
5. 正确的实现方式：由于 StreamSaver 的 WritableStream 只接受 Uint8Array，我们不能直接写入 Blob。正确的做法是在 dataavailable 事件处理器中，先将 Blob 转换为 ArrayBuffer，再封装成 Uint8Array 进行写入。

可运行 Demo:

HTML

<!DOCTYPE html>
<html>
<head>
  <title>Media Recorder Demo</title>
  <script src="https://cdn.jsdelivr.net/npm/web-streams-polyfill@2.0.2/dist/ponyfill.min.js"></script>
  <script src="https://cdn.jsdelivr.net/npm/streamsaver@2.0.3/StreamSaver.min.js"></script>
</head>
<body>
  <video id="liveVideo" autoplay muted style="width: 320px; border: 1px solid black;"></video><br>
  <button id="startRecBtn">开始录制</button>
  <button id="stopRecBtn" disabled>停止录制</button>
  <p>状态: <span id="status">空闲</span></p>

  <script>
    const startBtn = document.getElementById('startRecBtn');
    const stopBtn = document.getElementById('stopRecBtn');
    const liveVideo = document.getElementById('liveVideo');
    const statusEl = document.getElementById('status');
    let mediaRecorder;
    let writer;

    startBtn.onclick = async () => {
      try {
        const stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true });
        liveVideo.srcObject = stream;

        const fileStream = streamSaver.createWriteStream('my-recording.webm');
        writer = fileStream.getWriter();
        mediaRecorder = new MediaRecorder(stream, { mimeType: 'video/webm' });

        mediaRecorder.ondataavailable = async (event) => {
          if (event.data.size > 0) {
            statusEl.textContent = '正在写入数据块...';
            const buffer = await event.data.arrayBuffer();
            await writer.write(new Uint8Array(buffer));
          }
        };

        mediaRecorder.onstop = () => {
          writer.close();
          liveVideo.srcObject.getTracks().forEach(track => track.stop());
          liveVideo.srcObject = null;
          statusEl.textContent = '录制完成并已保存！';
          startBtn.disabled = false;
          stopBtn.disabled = true;
        };

        mediaRecorder.start(1000); // 每秒触发一次 dataavailable
        statusEl.textContent = '正在录制...';
        startBtn.disabled = true;
        stopBtn.disabled = false;

      } catch (err) {
        console.error("无法获取媒体设备:", err);
        statusEl.textContent = `错误: ${err.message}`;
      }
    };

    stopBtn.onclick = () => {
      if (mediaRecorder && mediaRecorder.state === 'recording') {
        mediaRecorder.stop();
      }
    };
  </script>
</body>
</html>

3.4 示例四：将 Canvas 动画录制为视频

目标：将一个动态的 <canvas> 动画保存为视频文件。
核心 API： $canvas.captureStream(frameRate)$ 用于将 canvas 实时内容转换为 MediaStream，然后同样使用 MediaRecorder API 进行处理 23。
代码解析：
1. 获取 canvas 元素及其 2D 绘图上下文。
2. 使用 requestAnimationFrame 创建一个动画循环。
3. 从 canvas 捕获流： $const canvasStream = canvas.captureStream(30);$ （表示期望帧率为 30fps）。
4. 从这一步开始，流程与上一个用户媒体录制的示例完全相同：用 canvasStream 创建一个 MediaRecorder 实例，用 StreamSaver 创建一个 fileStream，然后在 ondataavailable 事件中将数据块写入文件流。

第四部分：生产环境就绪 - 最佳实践与未来展望

最后一部分将为您提供在真实应用中负责任地、健壮地使用 StreamSaver.js 所需的知识。

4.1 构建稳健的下载器

处理页面导航：这是一个至关重要的问题。如果用户在下载过程中离开或刷新页面，JavaScript 上下文将被销毁，导致下载中断。最佳实践是实现 onbeforeunload 事件处理器，在下载进行中时向用户发出警告 1。
错误处理与取消：展示如何使用 $writer.abort()$ 或中止 WritableStream 来干净地取消下载。例如，当源数据流出错或用户点击了“取消”按钮时，这样做可以防止下载在浏览器中表现为“卡死”状态 4。
用户发起的下载：重申第一部分的结论：始终从用户的直接交互（如 onclick）开始下载流程。这不仅能避免在 HTTP 网站上被弹窗拦截器阻止，也能提供更好的用户体验 1。

可运行 Demo (包含 onbeforeunload 和取消功能):

HTML

<!DOCTYPE html>
<html>
<head>
  <title>Robust Downloader Demo</title>
  <script src="https://cdn.jsdelivr.net/npm/web-streams-polyfill@2.0.2/dist/ponyfill.min.js"></script>
  <script src="https://cdn.jsdelivr.net/npm/streamsaver@2.0.3/StreamSaver.min.js"></script>
</head>
<body>
  <button id="startSlowDownload">开始一个缓慢的下载</button>
  <button id="cancelBtn" disabled>取消下载</button>
  <p>状态: <span id="status">空闲</span></p>

  <script>
    const startBtn = document.getElementById('startSlowDownload');
    const cancelBtn = document.getElementById('cancelBtn');
    const statusEl = document.getElementById('status');
    let writer;
    let isDownloading = false;

    const beforeUnloadHandler = (event) => {
      if (isDownloading) {
        event.preventDefault();
        event.returnValue = '下载尚未完成，确定要离开吗？';
      }
    };
    window.addEventListener('beforeunload', beforeUnloadHandler);

    startBtn.onclick = async () => {
      isDownloading = true;
      startBtn.disabled = true;
      cancelBtn.disabled = false;
      statusEl.textContent = '下载中...';

      const fileStream = streamSaver.createWriteStream('slow-file.txt');
      writer = fileStream.getWriter();
      const encoder = new TextEncoder();

      try {
        for (let i = 0; i < 10; i++) {
          await new Promise(resolve => setTimeout(resolve, 500)); // 模拟耗时操作
          const chunk = encoder.encode(`这是第 ${i + 1} 块数据。\n`);
          await writer.write(chunk);
          statusEl.textContent = `已写入 ${i + 1}/10 块数据`;
        }
        await writer.close();
        statusEl.textContent = '下载完成！';
      } catch (error) {
        // 如果 writer 被中止，这里会捕获到错误
        statusEl.textContent = `下载被中止: ${error.message}`;
      } finally {
        isDownloading = false;
        startBtn.disabled = false;
        cancelBtn.disabled = true;
      }
    };

    cancelBtn.onclick = () => {
      if (writer) {
        writer.abort('用户手动取消');
      }
    };
  </script>
</body>
</html>

4.2 浏览器兼容性与未来

4.2.1 StreamSaver：通往未来的桥梁

StreamSaver.js 的作者明确指出，原生的文件系统访问 API (File System Access API) 将在未来使像 StreamSaver 这样的库“有点过时” 1。

技术是不断演进的。新的原生浏览器 API 会被引入，以解决以前由第三方库处理的问题。文件系统访问 API 就是 W3C 标准化的、用于解决客户端文件 I/O 问题的原生方案。然而，它目前仍处于实验阶段，并未得到所有主流浏览器的普遍支持 1。

因此，StreamSaver.js 目前扮演着一个至关重要的“桥梁”角色。它利用了更旧但支持更广泛的技术（Service Workers），为我们提供了在当今跨浏览器环境中迫切需要的功能。本教程的结论是，应将 StreamSaver.js 置于这样的背景下看待：它是目前完成特定任务的最佳工具，但开发者应密切关注原生文件系统访问 API，并将其视为长期的、最终的解决方案。

表2：底层 API 浏览器兼容性概览

下表为您提供了 StreamSaver.js 所依赖的关键技术的浏览器支持情况。这对于您评估目标用户群体和决定是否需要 Polyfill 至关重要。

API 特性	Chrome	Firefox	Safari	Edge (Chromium)
Service Workers	✔️ 支持	✔️ 支持	✔️ 支持	✔️ 支持
Streams API (Readable/Writable)	✔️ 支持	✔️ 支持 (高版本更完善)	✔️ 支持 (部分/逐步完善中)	✔️ 支持
`ReadableStream.pipeTo`	✔️ 支持	✔️ 支持	✔️ 支持 (14.1+)	✔️ 支持
`HTMLCanvasElement.captureStream`	✔️ 支持	✔️ 支持	✔️ 支持 (15.4+)	✔️ 支持
`MediaRecorder` API	✔️ 支持	✔️ 支持	✔️ 支持 (14+)	✔️ 支持