@mm-custom/md5

基于 WebAssembly 和 Web Worker 的高性能大文件 MD5 计算库，利用多线程和 Wasm 加速，支持进度反馈和取消操作。

特性

• 🚀 WebAssembly 加速：使用 Rust 编写的 MD5 算法，编译为 Wasm，计算速度接近原生。
• 🧵 Web Worker 多线程：在 Worker 线程中计算，避免阻塞主线程 UI。
• 📦 分块处理：支持大文件分块读取，内存占用低。
• 📊 进度反馈：实时回调计算进度。
• ⏹️ 取消操作：支持通过 AbortSignal 取消正在进行的计算。
• 🔧 灵活使用：既可使用内置 Worker，也可通过 workerFactory 自定义 Worker 创建（如 Vite 的 ?worker 导入）。

安装

npm install @mm-custom/md5
# 或
yarn add @mm-custom/md5
# 或
pnpm add @mm-custom/md5

使用示例

基本用法（内置 Worker）

import { calculateMD5 } from '@mm-custom/md5';

// 假设有一个文件输入框
const fileInput = document.querySelector('input[type=file]');
fileInput.addEventListener('change', async () => {
  const file = fileInput.files[0];
  if (!file) return;

  try {
    const md5 = await calculateMD5(file, {
      onProgress: (progress) => {
        console.log(`进度: ${Math.round(progress * 100)}%`);
      }
    });
    console.log('MD5:', md5);
  } catch (err) {
    console.error('计算失败:', err);
  }
});

自定义分块大小

const result = await calculateMD5(file, {
  chunkSize: 5 * 1024 * 1024, // 5MB
  onProgress: (p) => console.log(p),
});

取消计算

const controller = new AbortController();
setTimeout(() => controller.abort(), 5000);

try {
  const result = await calculateMD5(file, {
    signal: controller.signal,
    onProgress: (p) => console.log(p),
  });
} catch (err) {
  if (err.message === 'Aborted') {
    console.log('计算已取消');
  } else {
    console.error('计算失败:', err);
  }
}

指定自定义 Wasm 路径

默认情况下，库会使用内置的 Wasm 文件（位于 dist/md5.wasm）。如果需要自定义路径，可以通过 wasmUrl 参数指定：

const result = await calculateMD5(file, {
  wasmUrl: '/path/to/your/md5.wasm',
  onProgress: (p) => console.log(p),
});

API

calculateMD5(file, options?)

计算文件的 MD5 哈希。

参数

• file: MD5Input<string | ArrayBuffer | Blob>（必选）。

• options: ComputeOptions 对象（可选）

返回

• md5: Promise<string> - 文件的 MD5 哈希（十六进制小写）

ComputeOptions

| 属性 | 类型 | 默认值 | 描述 | |------|------|--------|------| | chunkSize | number | 10 * 1024 * 1024 | 分块大小（字节）。 | | onProgress | (progress: number) => void | - | 进度回调函数，progress 范围 0-1。 | | wasmUrl | string | 内置 Wasm 文件 URL | WebAssembly 文件的 URL。 | | workerFactory | () => Worker | 内置 Worker | 用于创建 Worker 的工厂函数。若提供，则使用该工厂创建 Worker；否则使用内置 Worker 文件。 | | signal | AbortSignal | - | 用于取消计算的 AbortSignal。 |

如何工作

1. Web Worker：计算过程在 Worker 线程中执行，避免阻塞主线程。

2. 分块读取：将大文件按 chunkSize 分块，每块读取后更新 MD5 哈希。

3. WebAssembly：MD5 核心算法由 Rust 实现并编译为 Wasm，在 Worker 中调用，性能接近原生。

4. 进度反馈：每处理完一个分块，Worker 向主线程发送进度消息。

5. 取消操作：通过 AbortSignal 可以随时终止计算。

注意事项

• 浏览器兼容性：需要支持 WebAssembly 和 Web Worker 的现代浏览器（Chrome 57+、Firefox 52+、Safari 11+、Edge 16+）。

• 分块大小：根据文件大小和内存限制调整 chunkSize，过大可能导致内存压力，过小会增加调用次数。默认 10MB 适合大多数场景。

• 自定义 Worker：如果在 Vite 项目中使用 ?worker 导入，确保 Worker 文件被正确处理（本项目已通过 exports 暴露 ./worker 子路径）。

• 跨域问题：如果 Wasm 文件托管在不同域名下，需配置 CORS 头。