《HarmonyOS技术精讲-Core File Kit》第12篇：文件哈希计算与完整性校验

一个容易被忽略的问题

HarmonyOS NEXT 开发中，很多人在做文件传输或存储时，默认认为文件写进去再读出来，内容一定是完整的。但实际项目里，文件可能因为传输中断、存储介质异常、多进程同时写等场景导致数据损坏。这时候如果直接用文件内容做业务判断，很容易引入隐蔽的 Bug。

文件哈希计算就是用来解决这个问题的——通过给文件算一个"数字指纹"，快速确认文件内容是否和预期一致。

官方文档里提到了 fileManager.hash 这个 API，但文档描述比较简略。很多开发者第一次用的时候，容易忽略算法选择、大文件性能、异常处理这几个关键点。这篇文章会把完整的实现逻辑和使用边界说清楚。

为什么需要文件哈希

文件哈希（也叫摘要、指纹）的核心用途是两个：

• 完整性校验：文件下载或复制后，对比哈希值是否与源文件一致，判断是否损坏。
• 内容去重：相同内容的文件，哈希值一定相同（冲突概率极低），可以直接用哈希值做唯一标识。

场景	推荐算法	原因
普通文件完整性校验	MD5	速度快，够用
安全敏感场景（如安装包校验）	SHA256	抗碰撞性强，更安全
大文件（>500MB）快速校验	MD5 或 SHA1	CPU 开销相对低
归档或版本管理	SHA256	标准统一，兼容性好

注意：MD5 在安全性上已经被证明有碰撞风险，如果文件内容涉及安全校验（如应用包、配置文件），建议用 SHA256。日常开发中做本地文件缓存校验，MD5 的效率和精度是够的。

不适合用文件哈希的场景：如果只是想判断文件是否存在，用 fileManager.access 或 fileManager.stat 就行，没必要算哈希。

环境说明

DevEco Studio 版本：DevEco Studio 6.1.0 及以上
HarmonyOS SDK 版本：HarmonyOS 6.1.0(23) 及以上
目标设备：手机或平板

核心实现：计算文件的 MD5 和 SHA256

1. 准备文件访问权限

在 module.json5 中声明文件读写权限：

{
  "requestPermissions": [
    {
      "name": "ohos.permission.READ_MEDIA"
    },
    {
      "name": "ohos.permission.WRITE_MEDIA"
    }
  ]
}

如果文件在应用沙箱内，不需要额外权限。如果访问公共目录，需要申请存储权限。

2. 使用 fileManager.hash 计算文件哈希

fileManager.hash 的签名如下：

hash(file: string | File, algorithm: string): Promise<string>

• file：文件路径（字符串）或已打开的 File 对象
• algorithm：算法名称，支持 'md5'、'sha1'、'sha256'、'sha384'、'sha512'

下面是一个完整工具类，封装了文件哈希计算逻辑：

// utils/FileHashUtil.ets
import { fileIo } from '@kit.CoreFileKit';
import { fileManager } from '@kit.CoreFileKit';

export enum HashAlgorithm {
  MD5 = 'md5',
  SHA1 = 'sha1',
  SHA256 = 'sha256',
  SHA384 = 'sha384',
  SHA512 = 'sha512'
}

export class FileHashUtil {
  /**
   * 计算文件的哈希值
   * @param filePath 文件绝对路径
   * @param algorithm 哈希算法，默认 SHA256
   * @returns 十六进制哈希字符串
   */
  static async computeHash(filePath: string, algorithm: HashAlgorithm = HashAlgorithm.SHA256): Promise<string> {
    try {
      // 检查文件是否存在
      let fileInfo = await fileIo.stat(filePath);
      if (fileInfo.size === 0) {
        throw new Error('文件为空，无法计算哈希');
      }

      // 打开文件拿到 File 对象
      let file = await fileIo.open(filePath, fileIo.OpenMode.READ_ONLY);
      try {
        // 计算哈希
        let hashValue: string = await fileManager.hash(file.fd, algorithm);
        return hashValue;
      } finally {
        // 确保关闭文件描述符
        fileIo.close(file);
      }
    } catch (error) {
      console.error(`文件哈希计算失败: ${JSON.stringify(error)}`);
      throw error;
    }
  }

  /**
   * 校验文件是否与预期哈希一致
   * @param filePath 文件路径
   * @param expectedHash 预期的哈希值
   * @param algorithm 哈希算法
   * @returns true 表示一致，false 表示不一致
   */
  static async verifyIntegrity(
    filePath: string,
    expectedHash: string,
    algorithm: HashAlgorithm = HashAlgorithm.SHA256
  ): Promise<boolean> {
    try {
      let actualHash = await this.computeHash(filePath, algorithm);
      return actualHash.toLowerCase() === expectedHash.toLowerCase();
    } catch (error) {
      console.error(`完整性校验失败: ${JSON.stringify(error)}`);
      return false;
    }
  }
}

这段代码的核心逻辑：

1. 通过 fileIo.stat 先判断文件是否存在且非空，避免对空文件计算哈希导致异常。
2. 使用 fileIo.open 以只读方式打开文件，拿到文件描述符 fd。
3. 调用 fileManager.hash 传入 fd 和算法名，返回十六进制字符串。
4. 用 try-finally 确保文件描述符被关闭，防止 fd 泄漏。

需要注意的点：

• fileManager.hash 的第一个参数可以直接传文件路径字符串，也可以传文件描述符。推荐传 fd，因为传字符串时内部会再次打开文件，多了一次 I/O 开销。
• 算法名必须小写，'MD5' 会报错。
• 返回值是全小写的十六进制字符串，校验对比时统一用 toLowerCase()。

3. 完整页面示例：生成哈希并校验

// pages/FileHashDemo.ets
import { fileIo } from '@kit.CoreFileKit';
import { common } from '@kit.AbilityKit';
import { FileHashUtil, HashAlgorithm } from '../utils/FileHashUtil';

@Entry
@Component
struct FileHashDemo {
  @State filePath: string = '';
  @State md5Value: string = '';
  @State sha256Value: string = '';
  @State verifyResult: string = '';
  @State isLoading: boolean = false;

  build() {
    Column({ space: 12 }) {
      Text('文件哈希计算与完整性校验')
        .fontSize(18)
        .fontWeight(FontWeight.Bold)
        .margin({ bottom: 8 })

      Button('选择文件并计算哈希')
        .width('80%')
        .enabled(!this.isLoading)
        .onClick(() => this.selectFileAndCompute())

      if (this.isLoading) {
        LoadingProgress().width(32).height(32)
      }

      if (this.filePath) {
        Text(`文件路径: ${this.filePath}`)
          .fontSize(14)
          .maxLines(2)
          .textOverflow({ overflow: TextOverflow.Ellipsis })
      }

      if (this.md5Value) {
        Text(`MD5: ${this.md5Value}`)
          .fontSize(14)
          .fontFamily('monospace')
          .breakStrategy(BreakStrategy.WORD)
      }

      if (this.sha256Value) {
        Text(`SHA256: ${this.sha256Value}`)
          .fontSize(14)
          .fontFamily('monospace')
          .breakStrategy(BreakStrategy.WORD)
      }

      if (this.verifyResult) {
        Text(this.verifyResult)
          .fontSize(16)
          .fontColor(this.verifyResult.includes('一致') ? Color.Green : Color.Red)
          .fontWeight(FontWeight.Medium)
      }

      if (this.md5Value && this.sha256Value) {
        Button('验证文件未被篡改')
          .width('80%')
          .type(ButtonType.Outlined)
          .onClick(() => this.verifyFile())
      }
    }
    .width('100%')
    .padding(16)
    .alignItems(HorizontalAlign.Center)
  }

  async selectFileAndCompute() {
    this.isLoading = true;
    this.md5Value = '';
    this.sha256Value = '';
    this.verifyResult = '';

    try {
      // 这里使用应用沙箱内的一个文件做演示
      // 实际项目中可以通过文件选择器获取文件路径
      let context = getContext(this) as common.UIAbilityContext;
      let sandboxDir: string = context.filesDir;
      // 假设沙箱下有一个 test.pdf
      let testPath = `${sandboxDir}/test.pdf`;

      // 如果文件不存在，先创建一个示例文件
      let fileInfo = await fileIo.stat(testPath).catch(() => null);
      if (!fileInfo) {
        await this.createSampleFile(testPath);
      }

      this.filePath = testPath;
      console.info(`开始计算哈希, 文件路径: ${testPath}`);

      // 同时计算 MD5 和 SHA256
      let [md5, sha256] = await Promise.all([
        FileHashUtil.computeHash(testPath, HashAlgorithm.MD5),
        FileHashUtil.computeHash(testPath, HashAlgorithm.SHA256)
      ]);

      this.md5Value = md5;
      this.sha256Value = sha256;
      console.info(`MD5: ${md5}, SHA256: ${sha256}`);
    } catch (error) {
      console.error(`计算失败: ${JSON.stringify(error)}`);
      this.verifyResult = `计算失败: ${error.message}`;
    } finally {
      this.isLoading = false;
    }
  }

  async verifyFile() {
    // 用 SHA256 做完整性校验
    let expected = this.sha256Value;
    let isMatch = await FileHashUtil.verifyIntegrity(this.filePath, expected, HashAlgorithm.SHA256);
    this.verifyResult = isMatch ? '✅ 文件完整，未被篡改' : '❌ 文件已被修改或损坏';
  }

  async createSampleFile(filePath: string) {
    let file = await fileIo.open(filePath, fileIo.OpenMode.CREATE | fileIo.OpenMode.READ_WRITE);
    try {
      let data = new ArrayBuffer(1024);
      // 写入一些测试数据
      await fileIo.write(file.fd, data);
    } finally {
      fileIo.close(file);
    }
  }
}

这段代码完成了三个核心操作：

1. 选择（或创建）一个文件，计算 MD5 和 SHA256 两个哈希值。
2. 展示哈希结果，支持复制对比。
3. 提供"验证文件完整性"按钮，用 SHA256 校验文件是否被修改。

为什么同时算 MD5 和 SHA256？实际项目中，MD5 用于快速对比（比如缓存去重），SHA256 用于安全校验。两者一起算并不冲突，用 Promise.all 并发执行，性能开销不会翻倍。

常见问题与踩坑记录

问题 1：fileManager.hash 传入路径字符串时，文件被占用导致失败

现象：
调用 fileManager.hash(path, 'sha256') 时，如果文件正在被其他流写入，会抛出 13900001 操作失败异常。

原因：
传字符串路径时，API 内部会以共享读模式打开文件。但如果文件上有排它写锁（比如正在被 fileIo.write 写入），打开就会失败。

解决方案：
优先传文件描述符 fd，且确保 fd 是以只读方式打开的。如果需要并发读写，业务层自己做状态同步，不要在写入同时计算哈希。

问题 2：大文件（>200MB）计算哈希导致 UI 线程卡顿

现象：
在点击按钮后直接调用 fileManager.hash，页面会卡住几秒甚至十几秒，然后才刷新结果。

原因：
fileManager.hash 虽然是异步 API，但默认是在 I/O 线程池 执行。如果在 @State 响应链中直接 await，ArkUI 的状态刷新会被阻塞，表现为页面卡顿。

解决方案：
用 @Concurrent 或 TaskPool 将哈希计算放到独立 Task 中，避免阻塞主线程。如果文件不大（< 50MB），直接 await 问题不大，但 UI 上要加 LoadingProgress 反馈。

问题 3：模拟器上 fileManager.hash 返回空字符串

现象：
代码在真机上运行正常，但在模拟器中调用 fileManager.hash 返回 ''。

原因：
模拟器的文件系统在某些版本上有兼容问题，fileManager.hash 对文件描述符的处理和真机不一致。这个 Bug 在 DevEco Studio 6.0 的模拟器中存在。

解决方案：

• 升级 DevEco Studio 到 6.1.0 及以上。
• 如果必须兼容模拟器，可以降级方案：用 cryptoFramework 逐块读取文件自己算哈希（不推荐，性能差很多）。
• 最佳实践：真机调试为主，模拟器只做 UI 验证。

最佳实践

1. 文件操作前后统一用 try-finally 关闭 fd。fileIo.open 和 fileIo.close 必须成对出现，一旦忘记关闭，fd 池会被耗尽，后续所有文件操作都会失败。这个错误在长时间运行的应用里特别隐蔽。

2. 不要频繁对小文件计算哈希。如果文件是固定的（比如内置的资源文件），建议第一次计算后把哈希值缓存到 Preferences 或数据库里，下次直接对比缓存值，省去 I/O 开销。

3. 校验时统一用小写比较。fileManager.hash 返回的字符串是全小写，但其他工具（比如 Linux 的 sha256sum）可能输出大写。统一用 toLowerCase() 做比对，避免大小写问题导致的误判。

4. 算法选择和文件大小有关。超过 500MB 的文件，SHA512 的计算耗时是 MD5 的 3-5 倍。如果只是做快速去重，MD5 更合适；如果是安全校验，优先 SHA256，SHA512 的性价比不高。

Demo 入口文件

// pages/Index.ets
import { FileHashDemo } from './FileHashDemo';

@Entry
@Component
struct Index {
  build() {
    FileHashDemo()
  }
}

FAQ

Q：fileManager.hash 支持的文件大小上限是多少？

A：官方没有明确上限，实测 2GB 以内的文件可以正常计算。超过 2GB 建议分片处理，用 cryptoFramework 逐块更新摘要。

Q：为什么 MD5 算出来的值和 Windows 上不一致？

A：检查文件是否包含 BOM 头或换行符差异。文本文件在不同系统上的换行符（CRLF vs LF）会导致哈希不同。建议用二进制模式打开文件再计算。

Q：可以在 worker 线程里调用 fileManager.hash 吗？

A：可以。fileManager 的 API 在 worker 线程中可用，但需要把文件描述符传递过去。注意 ArkTS 的 worker 通信限制，fd 是数字类型，可以直接传，文件路径字符串也可以。

Q：计算哈希时文件被其他进程写入了怎么办？

A：哈希计算的是计算时刻的文件内容快照。如果文件正在被写入，得到的是"不完整"的哈希。业务上建议先锁定文件（通过信号量或状态标记），确保计算期间文件不被修改。

示例代码地址：项目地址