Web Crypto subtle.digest 处理大文件时如何分块计算

处理几十 MB 甚至更大的文件时，直接把 file.arrayBuffer() 交给 crypto.subtle.digest() 很容易让内存峰值跟着文件大小上涨。关键点是：Web Crypto 的 subtle.digest() 目前不接收流，也没有 update() 方法；把文件切成多段后分别计算摘要，再把摘要字符串拼接，得到的并不是原文件的 SHA-256。

先分清：切片读取不等于分块摘要

原生方案适合小文件，写法很直接：先把完整文件读成一个 ArrayBuffer，再交给 Web Crypto。

async function digestWholeFile(file) {
  // 这里一次性读取完整文件，适合体积可控的输入。
  const bytes = await file.arrayBuffer();
  // digest 不保存可继续 update 的上下文，所以不能把它当流式哈希器。
  const buffer = await crypto.subtle.digest("SHA-256", bytes);
  return Array.from(new Uint8Array(buffer), (byte) =>
    byte.toString(16).padStart(2, "0")
  ).join("");
}

MDN 明确说明，digest() 不支持 streaming input；它接收的是 ArrayBuffer、TypedArray 或 DataView，并返回一个新的摘要 ArrayBuffer。因此下面这种思路只是算出了多个独立文件块的摘要：

// 错误示意：块摘要的拼接不等于整文件摘要。
const partA = await crypto.subtle.digest("SHA-256", await file.slice(0, 4 * 1024 * 1024).arrayBuffer());
const partB = await crypto.subtle.digest("SHA-256", await file.slice(4 * 1024 * 1024).arrayBuffer());
// 这里得到的是 SHA256(partA) 与 SHA256(partB) 的两个结果，不是 SHA256(file)。

用 Blob.slice 控制每次读入的块大小

Blob.slice(start, end) 会返回原 Blob 的一个子集，arrayBuffer() 再把这个子集读成二进制缓冲区。切片边界要使用字节偏移，不要按字符串字符数计算；文件可能是图片、压缩包或任意二进制数据。

真正的分块方案：同一个哈希器持续 update

浏览器端可以选择提供增量接口的库，例如 hash-wasm。它的 createSHA256() 返回带状态的实例，连续调用 update() 后再 digest("hex")。官方项目地址可复制为：https://github.com/Daninet/hash-wasm。

# 安装带有 createSHA256、update 和 digest 接口的前端依赖。
npm install hash-wasm

import { createSHA256 } from "hash-wasm";

export async function digestFileInChunks(file, chunkSize = 4 * 1024 * 1024) {
  // 只接受 Blob/File，并拒绝无意义的块大小，避免循环无法前进。
  if (!(file instanceof Blob)) throw new TypeError("file 必须是 Blob 或 File");
  if (!Number.isSafeInteger(chunkSize) || chunkSize 

这段代码把“文件读取”和“摘要状态”分开：slice() 限制单块大小，update() 保留跨块的 SHA-256 上下文。它不会把整个文件装进一个 ArrayBuffer，代价是引入 WASM/依赖、需要额外测试包体和 Worker 调度。

块大小和 Worker 怎么取舍

4 MiB 是一个便于起步的工程值，不是标准答案。块太小会增加 slice()、Promise 和 WASM 边界调用次数；块太大又会抬高单次 ArrayBuffer 的峰值。可以根据设备内存、文件类型和交互响应逐档测试 1、4、8 MiB。

如果哈希计算会让主线程出现明显卡顿，把同一套读取循环搬到 Web Worker；不要在主线程和 Worker 同时保留整份文件副本。需要断点续算时，只有库明确支持保存/恢复内部状态才可以持久化状态，而且状态可能包含输入相关信息，不能当作普通公开元数据。

最后别混淆用途：SHA-256 适合做完整性比对、去重键或上传前校验；如果需求是证明“这份文件来自某个可信方”，还需要签名、密钥管理和服务端验证，单独计算摘要不能完成身份认证。

常见问题

把文件分成多块后分别调用 subtle.digest，能省内存吗？

每次调用的峰值可能变小，但结果是多个块摘要，不是整文件摘要；若要得到整文件 SHA-256，应使用增量哈希器或让服务端以流方式计算。

空文件会返回什么？

循环不会执行，增量哈希器直接 digest() 即可得到 SHA-256 的空输入结果；仍应在业务层决定空文件是否允许上传。

能把 digest 的结果继续 update 吗？

不要这样做。digest() 表示输入结束；要计算另一份文件，应重新初始化或创建新的哈希实例。