Node.js 获取文件 MD5 的正确方式，大文件友好

在实际开发中，我们经常需要对文件计算 MD5 值，比如：

• 文件完整性校验
• 重复文件去重
• 上传前后比对
• 断点续传一致性校验

Node.js 内置的 crypto 模块已经提供了完整的哈希计算能力，不需要额外依赖。本文从 开发者实战角度 总结两种常用方案，并说明各自适用场景。

一、为什么不能直接 readFileSync 读大文件？

很多初学者会直接：

fs.readFileSync(filePath)

这会把整个文件一次性载入内存。 如果文件是几百 MB 或几个 GB，很容易：

• 占满内存
• 阻塞事件循环
• 影响整个服务稳定性

因此，在生产环境中， 流式计算才是正确姿势 。

二、推荐方案：使用 Stream 计算 MD5（大文件友好）

import fs from 'fs';
import crypto from 'crypto';

function md5File(filePath) {
  return new Promise((resolve, reject) => {
    const hash = crypto.createHash('md5');
    const stream = fs.createReadStream(filePath);

    stream.on('data', chunk => hash.update(chunk));
    stream.on('end', () => resolve(hash.digest('hex')));
    stream.on('error', reject);
  });
}

// 使用
md5File('./video.mp4').then(md5 => {
  console.log('MD5:', md5);
});

✔ 这个方案的优势

• 基于 createReadStream ，不会一次性占用内存
• 可处理任意大小文件
• 不阻塞主线程
• 适合服务器端文件校验、上传中转服务

🔧 原理简述

1. crypto.createHash('md5') 创建哈希计算器
2. 文件以流方式分片读取
3. 每个 chunk 送入 hash.update()
4. 文件读完后 hash.digest('hex') 输出最终 MD5

这是 Node.js 处理大文件的标准范式。

三、同步方案：适合小文件或脚本工具

如果你只是在本地 CLI 工具或构建脚本中处理小文件，可以使用同步版本：

function md5FileSync(filePath) {
  const data = fs.readFileSync(filePath);
  return crypto.createHash('md5').update(data).digest('hex');
}

✔ 适用场景

• 构建阶段校验
• 本地脚本工具
• 文件体积很小（几十 KB ～ 几 MB）

⚠ 注意

同步 IO 会阻塞线程，不适合 Web 服务请求链路中使用。

四、开发中常见应用场景

五、扩展建议

如果你的系统需要：

• 批量扫描文件夹 MD5
• 并发计算队列
• 结合数据库做文件指纹库

可以基于本文的流式方案很容易扩展成完整服务。

六、总结

一句话结论：

在 Node.js 中，计算 MD5 的核心是 crypto.createHash() ， 小文件用 readFileSync ， 大文件必须使用 createReadStream 流式处理。

这不仅是性能问题，更是生产稳定性的关键。