Fast File Hash

基于 hash-wasm 的高性能流式 SHA256 文件哈希计算库。

特性

• 🚀 真正的流式处理：边读边计算，不占用大量内存
• ⚡ 高性能：基于 WebAssembly 的 hash-wasm 实现
• 🎯 内存高效：适合处理大型文件（GB 级别）
• 🔒 类型安全：完整的 TypeScript 支持
• 🌐 Web 友好：适用于浏览器和 Node.js 环境

安装

pnpm install

快速开始

启动测试页面

pnpm run dev

这将启动 Vite 开发服务器并自动打开浏览器中的测试页面，你可以：

• 拖拽文件到上传区域
• 点击选择文件按钮
• 实时查看计算进度
• 查看性能统计信息

运行性能测试

# 基本性能测试（10MB）
pnpm test

# 1GB 性能测试
pnpm run test:1gb

使用方法

基本用法

import { streamSha256 } from "fast-file-hash";

const response = await fetch("large-file.zip");
const hash = await streamSha256(response.body);
console.log("SHA256:", hash); // 64字符十六进制哈希

高级用法 - 增量计算器

import { StreamSha256Calculator } from "fast-file-hash";

const calculator = new StreamSha256Calculator();
await calculator.init();

// 可以逐步添加数据
await calculator.update(chunk1);
await calculator.update(chunk2);
const hash = calculator.digest();

Web Worker 后台计算（推荐用于大文件）

Web Worker 可以避免阻塞主线程，特别适合处理大文件：

便捷使用

import { hashFileWithWorker, hashStreamWithWorker } from "fast-file-hash";

// 处理文件（带进度回调）
const hash = await hashFileWithWorker(file, {
    onProgress: (progress) => {
        console.log(
            `进度: ${((progress.loaded / progress.total) * 100).toFixed(1)}%`
        );
    },
});

// 处理流
const response = await fetch("large-file.zip");
const hash = await hashStreamWithWorker(response.body);

手动控制 Web Worker

import { WebWorkerSha256 } from "fast-file-hash";

const worker = new WebWorkerSha256();

// 初始化计算器
const calculatorId = await worker.initCalculator();

// 分批添加数据
await worker.updateCalculator(calculatorId, chunk1);
await worker.updateCalculator(calculatorId, chunk2);

// 计算最终哈希
const hash = await worker.digestCalculator(calculatorId);

// 清理资源
worker.destroy();

文件流处理

import { createReadStream } from "fs";
import { streamSha256 } from "fast-file-hash";

// Node.js 文件流
const fileStream = createReadStream("large-file.iso");
const hash = await streamSha256(fileStream);

API 参考

streamSha256(stream: ReadableStream<Uint8Array>): Promise<string>

计算 ReadableStream 的 SHA256 哈希值。

参数：

• stream: 包含 Uint8Array 数据块的可读流

返回值：

• Promise<string>: 64 字符十六进制 SHA256 哈希

StreamSha256Calculator 类

提供更灵活的增量哈希计算。

方法：

• init(): Promise<void> - 初始化计算器
• update(chunk: Uint8Array): Promise<void> - 添加数据块
• digest(): string - 计算并返回最终哈希
• reset(): void - 重置计算器以便重用

Web Worker API

WebWorkerSha256 类

在后台线程中执行哈希计算，避免阻塞主线程。

方法：

• hashStream(stream: ReadableStream<Uint8Array>): Promise<string> - 计算流哈希
• hashFile(file: File, options?: HashOptions): Promise<string> - 计算文件哈希
• initCalculator(): Promise<string> - 初始化增量计算器
• updateCalculator(id: string, chunk: Uint8Array): Promise<void> - 更新计算器
• digestCalculator(id: string): Promise<string> - 获取最终哈希
• resetCalculator(id: string): Promise<void> - 重置计算器
• destroy(): void - 销毁 Worker

便捷函数

• hashStreamWithWorker(stream: ReadableStream<Uint8Array>): Promise<string>
• hashFileWithWorker(file: File, options?: HashOptions): Promise<string>
• createIncrementalHashWorker(): Promise<WebWorkerSha256>

HashOptions：

interface HashOptions {
    onProgress?: (progress: { loaded: number; total: number }) => void;
}

性能测试

运行基本测试

pnpm test

运行 1GB 性能测试

pnpm run test:1gb

测试会生成指定大小的数据流并测量：

• 处理时间
• 吞吐量 (MB/s)
• 内存使用情况

性能特点

• 内存使用：常数级内存使用，不随文件大小线性增长
• CPU 效率：WebAssembly 优化，适合高性能场景
• 流式处理：支持任意大小的文件，无内存限制
• 多线程支持：Web Worker 避免阻塞主线程
• 进度监控：实时进度回调和状态报告

技术实现

• hash-wasm: 基于 WebAssembly 的哈希算法实现
• 流式处理: 增量更新哈希状态，无需完整数据
• TypeScript: 完整的类型定义和文档

Vite 集成

在 Vite 项目中使用时，确保正确配置 Web Worker：

// vite.config.ts
import { defineConfig } from "vite";

export default defineConfig({
    worker: {
        format: "es", // 使用 ES 模块格式
    },
});

浏览器兼容性

需要支持 WebAssembly 和 ReadableStream 的现代浏览器：

• Chrome 57+
• Firefox 52+
• Safari 11+
• Edge 16+

许可证

ISC