前言

在鸿蒙应用开发中，本地文件管理是高频且核心的场景，无论是缓存用户数据、保存配置信息，还是处理多媒体资源，都离不开对应用沙箱目录的精准操控。很多开发者初接触 ohos.file.fs 模块时，容易混淆同步与异步接口的使用场景，或者在处理大文件读写时忽略内存溢出风险。

本文基于鸿蒙最新API文档，系统梳理鸿蒙基础文件操作的核心能力，通过新建读写、文件拷贝、流式传输三个典型场景的代码实战，帮你彻底掌握 @kit.CoreFileKit 的正确用法，避开常见的性能陷阱。

---

一、核心接口全景图：同步 vs 异步怎么选？

鸿蒙提供了覆盖文件全生命周期管理的基础操作接口，支持查看、创建、读写、删除、移动、复制及属性获取等能力。在实际开发中，选择同步还是异步接口直接决定了应用的流畅度。

接口名	功能描述	同步支持	异步支持	适用场景建议
access	检查文件是否存在	✅	✅	快速判断文件状态，同步调用即可
open / close	打开/关闭文件	✅	✅	小文件操作可用同步，大文件优先异步
read / write	读取/写入数据	✅	✅	耗时I/O操作务必使用异步接口
copyFile / moveFile	复制/移动文件	✅	✅	大文件移动建议异步避免卡顿
mkdir / rmdir	创建/删除目录	✅	✅	轻量操作同步执行，快速反馈
stat	获取文件属性	✅	✅	同步读取元数据，性能开销极低
listFile	列出目录下文件	✅	✅	目录文件数量较多时建议异步加载

⚠️ 重要提示：对于 read、write 这类涉及磁盘I/O的耗时操作，强烈推荐使用异步接口，避免阻塞主线程导致应用ANR（无响应）甚至直接崩溃。

---

二、前置准备：获取应用沙箱路径

在进行任何文件操作前，必须先获取应用的沙箱目录路径，这是鸿蒙系统为每个应用分配的私有存储空间，其他应用无法访问，保障数据安全。

以从 UIAbilityContext 获取 HAP 级别的文件路径为例：

import { common } from '@kit.AbilityKit';

// 在UI组件内获取上下文，确保返回有效UIAbilityContext
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
// 获取应用私有文件目录
let filesDir = context.filesDir;
console.info('应用沙箱路径：' + filesDir);

注意：不要硬编码绝对路径，所有文件操作都基于 context.filesDir 拼接路径，保证多设备、多版本系统的兼容性。除了基础的 filesDir，你还可以通过 context 获取 cacheDir（缓存目录）、tempDir（临时目录）等不同用途的沙箱路径，缓存目录下的文件会在系统存储空间不足时自动清理，适合存放不需要持久保留的临时资源。

---

三、实战场景1：新建文件并完成基础读写

这是最常用的基础场景，适合保存简单的文本配置、用户日志等轻量数据。核心要点是正确设置文件打开模式，并且确保操作完成后关闭文件句柄。

import { fileIo, ReadOptions } from '@kit.CoreFileKit';
import { common } from '@kit.AbilityKit';
import { buffer } from '@kit.ArkTS';

function createAndReadWrite(context: common.UIAbilityContext): void {
  let filesDir = context.filesDir;
  let file: fileIo.File | null = null;

  try {
    // 1. 打开/创建文件：读写模式 + 不存在自动创建
    file = fileIo.openSync(filesDir + '/user_config.txt',
      fileIo.OpenMode.READ_WRITE | fileIo.OpenMode.CREATE);

    // 2. 向文件写入字符串内容
    let writeLength = fileIo.writeSync(file.fd, 'Hello HarmonyOS 5.0');
    console.info(`写入成功，数据长度：${writeLength} 字节`);

    // 3. 准备1024字节的缓冲区，用于存储读取到的数据
    let arrayBuffer = new ArrayBuffer(1024);
    let readOptions: ReadOptions = {
      offset: 0, // 从文件起始位置开始读取
      length: arrayBuffer.byteLength
    };

    // 4. 执行读取操作，获取实际读取的字节数
    let readLength = fileIo.readSync(file.fd, arrayBuffer, readOptions);

    // 5. 将二进制数据转换为字符串输出
    let resultBuffer = buffer.from(arrayBuffer, 0, readLength);
    console.info(`读取到的文件内容：${resultBuffer.toString()}`);

  } catch (error) {
    console.error(`文件操作失败，错误码：${error.code}，错误信息：${error.message}`);
  } finally {
    // 6. 必须在finally块中关闭文件，防止资源泄漏
    if (file) {
      try {
        fileIo.closeSync(file);
      } catch (closeError) {
        console.error('关闭文件句柄失败');
      }
    }
  }
}

避坑指南

• 读取后转换字符串时，必须用实际读取的字节数截取缓冲区，否则会出现多余的空字符乱码。如果文件内容包含中文，还需要额外指定 UTF-8 编码进行解码，避免出现乱码问题。
• 不要在循环中频繁打开关闭同一个文件，会产生不必要的性能开销。对于需要多次写入的日志类文件，可以保持文件句柄打开，操作完成后再统一关闭，大幅提升写入效率。
• 注意 OpenMode 的组合使用：如果需要覆盖原有文件内容，可以额外加上 TRUNCATE 模式；如果要以追加模式写入内容，则使用 APPEND 模式，避免覆盖原有数据。

---

四、实战场景2：低内存实现大文件拷贝

如果直接一次性读取整个大文件到内存，很容易造成 OOM 内存溢出。推荐使用分块读写的方式，用固定大小的缓冲区循环读取写入，把内存占用控制在极低水平。

import { fileIo, ReadOptions } from '@kit.CoreFileKit';
import { common } from '@kit.AbilityKit';

function copyLargeFile(context: common.UIAbilityContext): void {
  let sourceFile: fileIo.File | null = null;
  let targetFile: fileIo.File | null = null;

  try {
    let filesDir = context.filesDir;
    // 同时打开源文件和目标文件
    sourceFile = fileIo.openSync(filesDir + '/source_video.mp4',
      fileIo.OpenMode.READ_ONLY);
    targetFile = fileIo.openSync(filesDir + '/backup_video.mp4',
      fileIo.OpenMode.READ_WRITE | fileIo.OpenMode.CREATE);

    // 定义4KB缓冲区，平衡内存占用和I/O操作次数
    const BUFFER_SIZE = 4096;
    let buffer = new ArrayBuffer(BUFFER_SIZE);
    let currentOffset = 0;

    // 循环分块读取，直到文件末尾
    let readBytes = fileIo.readSync(sourceFile.fd, buffer, {
      offset: currentOffset,
      length: BUFFER_SIZE
    });

    while (readBytes > 0) {
      // 将当前块数据写入目标文件
      fileIo.writeSync(targetFile.fd, buffer, { length: readBytes });
      // 更新读取偏移量，继续读取下一块
      currentOffset += readBytes;
      readBytes = fileIo.readSync(sourceFile.fd, buffer, {
        offset: currentOffset,
        length: BUFFER_SIZE
      });
    }

    console.info('大文件拷贝完成，无内存溢出风险');

  } catch (error) {
    console.error(`文件拷贝失败：${error.message}`);
  } finally {
    // 依次关闭两个文件句柄
    [sourceFile, targetFile].forEach(fileItem => {
      if (fileItem) {
        try {
          fileIo.closeSync(fileItem);
        } catch (e) {
          console.error('关闭文件失败');
        }
      }
    });
  }
}

进阶优化

你可以基于这个分块拷贝逻辑，加入 进度回调 功能，每完成一块数据的写入就更新一次进度，在 UI 上展示拷贝进度条，提升用户体验。同时还可以加入 断点续传 逻辑，记录当前拷贝的偏移量，应用被意外杀死后再次启动时可以从断点位置继续拷贝，不需要从头开始重新操作。

---

五、实战场景3：Stream流式处理超大文件

对于 GB 级别的音视频文件，使用 createStream 开启文件流是最优方案。流式操作天然支持背压机制，不需要一次性加载全量数据，结合异步语法完全不会阻塞 UI 线程。

import { fileIo } from '@kit.CoreFileKit';
import { common } from '@kit.AbilityKit';

async function streamProcessHugeFile(context: common.UIAbilityContext): Promise<void> {
  let filesDir = context.filesDir;
  let inputStream: fileIo.Stream | null = null;
  let outputStream: fileIo.Stream | null = null;

  try {
    // 以只读模式打开输入流，只写模式打开输出流
    inputStream = fileIo.createStreamSync(`${filesDir}/huge_log.log`, 'r');
    outputStream = fileIo.createStreamSync(`${filesDir}/huge_log_backup.log`, 'w');

    // 定义8KB分块大小，进一步降低单次内存占用
    const CHUNK_SIZE = 8192;
    let chunkBuffer = new ArrayBuffer(CHUNK_SIZE);

    // 异步循环读取流数据
    let readChunk = await inputStream.read(chunkBuffer);
    while (readChunk > 0) {
      // 将当前分块写入输出流
      await outputStream.write(chunkBuffer.slice(0, readChunk));
      // 继续读取下一分块
      readChunk = await inputStream.read(chunkBuffer);
    }

    console.info('超大文件流式处理完成，全程内存占用稳定');

  } catch (error) {
    console.error(`流操作失败：${error.message}`);
  } finally {
    // 异步关闭流资源
    if (inputStream) await inputStream.close();
    if (outputStream) await outputStream.close();
  }
}

流式操作扩展场景

除了文件拷贝，Stream 流还非常适合用来实现大文件的 压缩、加密、转码 等操作。你可以在流的读写过程中，对每一块数据实时进行加密处理，不需要等待全量文件读取完成，就能边读取边加密写入新文件，大幅提升大文件处理效率。

---

六、补充实战：目录管理与文件属性操作

除了基础的文件读写，日常开发中还经常需要进行目录创建、文件属性查询、目录遍历等操作，这里补充两个高频场景的实现代码：

1. 递归创建多级目录

鸿蒙的 mkdir 接口默认只能创建单级目录，如果需要创建多级嵌套目录，可以封装一个递归工具函数：

async function mkdirRecursive(dirPath: string): Promise<void> {
  try {
    // 先检查目录是否已经存在
    await fileIo.access(dirPath);
  } catch {
    // 目录不存在，先创建父目录
    const parentPath = dirPath.substring(0, dirPath.lastIndexOf('/'));
    await mkdirRecursive(parentPath);
    // 创建当前目录
    await fileIo.mkdir(dirPath);
  }
}

2. 遍历目录下所有文件

使用 listFile 接口可以快速获取目录下的所有文件名，结合 stat 接口可以批量获取所有文件的大小、修改时间等属性：

async function listAllFiles(dirPath: string): Promise<void> {
  const fileNames = await fileIo.listFile(dirPath);
  for (const name of fileNames) {
    const fullPath = `${dirPath}/${name}`;
    const statInfo = await fileIo.stat(fullPath);
    console.info(`文件名：${name}，文件大小：${statInfo.size}字节，修改时间：${statInfo.mtime}`);
  }
}

---

七、开发最佳实践总结

• 路径规范：所有文件操作都基于系统返回的沙箱路径拼接，禁止硬编码绝对路径，保证跨设备兼容性。不同用途的文件要分类存放在 filesDir、cacheDir、tempDir 等不同目录下，避免文件混乱。
• 资源安全：所有打开的文件句柄、流对象，必须在 finally 块中执行关闭操作，避免句柄泄漏导致后续文件操作异常。应用退出前要统一清理临时目录下的无用文件，避免占用过多存储空间。
• 异步优先：除了几 KB 的极小配置文件，所有磁盘读写操作优先使用异步接口，避免主线程阻塞造成应用卡顿。耗时的文件操作要放到子线程中执行，完全不干扰 UI 渲染。
• 异常闭环：文件操作受存储空间、权限等因素影响极易出错，必须包裹完整的 try-catch 逻辑，记录错误日志方便排查问题。操作前要提前判断剩余存储空间，避免写入过程中因为空间不足导致文件损坏。

掌握这些 ArkTS 文件操作技巧，你就能轻松在鸿蒙应用中实现数据持久化、缓存管理、资源处理等核心能力，为构建高性能应用打下坚实基础。