Web Crypto 计算文件 SHA-256：非流式 digest 的内存边界与大文件方案

一、问题概述：大文件哈希计算的峰值内存与交互风险

对多 GB 文件调用 file.arrayBuffer() 会额外分配与文件大小相当的连续缓冲区，可能触发分配失败、进程被系统终止或严重内存压力。即便 subtle.digest() 返回 Promise，也不代表大输入没有 CPU 与资源竞争；文件大小策略和目标设备实测仍不可省略。

二、最小复现：盲目全量读取大文件与 Web Crypto API 的限制

下面的代码说明了一次性读取大文件以及混淆 SubtleCrypto.digest 支持算法的常见失误：

/* 错误 1：试图用 SubtleCrypto 计算 MD5 -> 直接报错 DOMException (Algorithm Not Supported) */
// await window.crypto.subtle.digest("MD5", data); // SubtleCrypto 根本不支持 MD5！

/* 错误 2：一次性读取 2GB 文件传入 ArrayBuffer -> 页面内存爆满 OOM 崩溃！ */
// const buffer = await file.arrayBuffer(); // 不可取！

三、根因分析：SubtleCrypto 的算法与输入模型限制

1. 算法限制：subtle.digest() 支持 SHA-1, SHA-256, SHA-384, SHA-512，不支持 MD5。2. 没有增量接口：原生 API 单次接收完整的 BufferSource，不能逐块更新同一个摘要状态。3. 内存边界：完整文件缓冲区、浏览器内部处理和页面其他对象会共同抬高峰值内存；具体上限不是 Web Crypto 规范的一部分，不能写死为某个浏览器固定值。

四、推荐方案：先按文件大小选择正确的哈希实现

1. 中小文件：根据目标设备制定可配置的大小上限，在上限内使用 file.arrayBuffer() 与 crypto.subtle.digest('SHA-256', buffer)。2. 真正的大文件：在 Web Worker 中使用经过审计、支持增量 .update(chunk) 的 SHA-256 JS/Wasm 库，逐块读取并顺序更新同一个哈希状态；不能独立哈希每个切片后再拼接摘要。3. 进度与取消：主线程只接收进度和最终摘要，并支持终止 Worker。Worker 避免 UI 阻塞，但不会自动消除哈希状态和切片所需内存。

五、完整代码：带文件上限的原生 Web Crypto SHA-256

下面的代码忠实反映原生 API 的边界：它只接受上限内的文件，并一次性读取完整内容。64 MiB 是示例产品策略，不是浏览器保证；上线时应按支持的设备实测调整。超出上限后应切换到增量 Worker 实现，而不是假装 Blob.slice() 能流式调用 digest()。

const DEFAULT_NATIVE_DIGEST_LIMIT = 64 * 1024 * 1024;

async function computeFileSha256WithWebCrypto(
  file: File,
  maxBytes = DEFAULT_NATIVE_DIGEST_LIMIT,
): Promise<string> {
  if (file.size > maxBytes) {
    throw new RangeError(
      "文件超出原生 digest 的产品内存上限，请改用 Worker 中的增量 SHA-256 实现",
    );
  }

  const bytes = await file.arrayBuffer();
  const digest = await crypto.subtle.digest("SHA-256", bytes);
  return Array.from(new Uint8Array(digest), (byte) =>
    byte.toString(16).padStart(2, "0"),
  ).join("");
}

六、常见错误方案

使用 SubtleCrypto.digest('MD5', buffer) 期望计算 MD5 导致运行时捕获 DOMException 异常；在 UI 主线程循环中无休止地阻塞同步计算哈希导致页面失去响应；不检查文件物理大小盲目全量加载。

七、边界条件：设备差异、Worker 与内存所有权

不要依赖未经规范保证的固定浏览器内存阈值；移动设备、并发标签页和浏览器版本都会影响可用内存。向 Worker 发送切片时可转移 ArrayBuffer 所有权以减少复制，但必须确认增量库不会在内部长期保留所有切片。页面关闭、用户取消和 Worker 异常也要能清理资源。

八、如何验证文件哈希正确性与性能

使用系统 shasum -a 256 或服务端 SHA-256 与浏览器结果比对；固定测试空文件、非整块大小、含零字节文件和超过上限文件。对增量 Worker 方案监控峰值内存、主线程长任务、取消行为和不同大小下的进度单调性。

九、FAQ

问：Blob.slice() 后逐块调用 subtle.digest() 再拼起来可以吗？答：不可以，那得到的是多个独立摘要，不等于整个文件的 SHA-256。

问：如何处理 2GB 文件？答：选择支持增量更新的可信 SHA-256 JS/Wasm 实现，在 Worker 中顺序读取切片并更新同一个状态；同时核对库的供应链、许可和测试向量。

问：Worker 能防止 OOM 吗？答：不能保证。它主要隔离计算，仍需限制切片大小、避免保留全部切片，并实测峰值内存。

十、总结

原生 Web Crypto digest() 是非流式接口。中小文件应设置明确上限后一次性计算；超大文件应采用 Worker 加可信增量哈希库，并用标准测试向量与资源监控验证，不能用空循环切片伪装成流式 SHA-256。