引言

在App开发中，文件操作是躲不掉的基础能力——读写配置文件、缓存网络图片、导出用户数据、保存日志……HarmonyOS 提供了 @ohos.file.fs 模块，它是文件操作的核心API，属于 @kit.CoreFileKit。

本文涵盖文件/目录的增删改查、流式读写、文件信息获取等最常用操作，全部带代码示例，10分钟上手。

---

一、导入与基础概念

import fs from '@ohos.file.fs';

所有文件操作都基于应用沙箱路径，你不需要也不应该使用绝对路径。沙箱路径通过 Context 获取：

const ctx = getContext(this);
// 应用沙箱根路径
const sandboxPath = ctx.filesDir;    // 数据存储目录
const cacheDir = ctx.cacheDir;       // 缓存目录
const tempDir = ctx.tempDir;         // 临时目录

---

二、目录操作：创建、遍历、删除

2.1 创建目录

// 创建单级目录
fs.mkdirSync(`${ctx.filesDir}/myapp`);

// 创建多级目录（recursive = true）
fs.mkdirSync(`${ctx.filesDir}/myapp/images/avatars`, true);

2.2 遍历目录

// 列出目录下所有条目
const files = fs.listFileSync(`${ctx.filesDir}/myapp`);
console.log('文件列表:', files); // ['config.json', 'images', 'log.txt']

2.3 删除目录

// 删除空目录
fs.rmdirSync(`${ctx.filesDir}/myapp/empty_dir`);

// 递归删除（删除目录及其所有内容）
fs.rmSync(`${ctx.filesDir}/myapp`, { recursive: true });

---

三、文件操作：创建、读写、删除

3.1 检查文件是否存在

const exists = fs.accessSync(`${ctx.filesDir}/config.json`);

3.2 写入文件

// 写入文本（覆盖模式）
let file = fs.openSync(`${ctx.filesDir}/config.json`, fs.OpenMode.CREATE | fs.OpenMode.WRITE_ONLY);
fs.writeSync(file.fd, '{"theme": "dark", "fontSize": 16}');
fs.closeSync(file);

// 追加写入
file = fs.openSync(`${ctx.filesDir}/log.txt`, fs.OpenMode.CREATE | fs.OpenMode.APPEND);
fs.writeSync(file.fd, '\n新日志条目');
fs.closeSync(file);

3.3 读取文件

// 读取整个文件
const text = fs.readTextSync(`${ctx.filesDir}/config.json`);
console.log(text); // {"theme": "dark", "fontSize": 16}

// 指定编码和长度
const partial = fs.readTextSync(`${ctx.filesDir}/config.json`, 'utf-8', { length: 20 });

3.4 删除文件

fs.unlinkSync(`${ctx.filesDir}/temp.txt`);

---

四、文件信息与统计

const stat = fs.statSync(`${ctx.filesDir}/config.json`);
console.log({
  size: stat.size,          // 文件大小（字节）
  mtime: stat.mtime,        // 最后修改时间
  ctime: stat.ctime,        // 创建时间
  isDirectory: stat.isDirectory(), // 是否为目录
  isFile: stat.isFile()           // 是否为文件
});

---

五、流式读写：大文件场景

处理大文件时（比如图片、视频），用流式读写避免内存暴涨：

// 创建输出流
const outStream = fs.createStreamSync(
  `${ctx.filesDir}/output.jpg`,
  'w+'
);

// 创建输入流
const inStream = fs.createStreamSync(
  `${ctx.filesDir}/input.jpg`,
  'r'
);

// 分批读取
const buf = new ArrayBuffer(4096); // 4KB缓冲区
let readLen = 0;
do {
  readLen = inStream.readSync(buf);
  if (readLen > 0) {
    outStream.writeSync(buf.slice(0, readLen));
  }
} while (readLen > 0);

outStream.closeSync();
inStream.closeSync();

---

六、文件拷贝与移动

// 拷贝文件
fs.copyFileSync(
  `${ctx.filesDir}/source.txt`,
  `${ctx.filesDir}/backup/source.txt`
);

// 移动/重命名
fs.moveSync(
  `${ctx.filesDir}/old.txt`,
  `${ctx.filesDir}/new.txt`
);

---

七、最佳实践

✅ 文件操作完整模式

// 正确的写法：try/catch + finally 关闭
function safeWriteText(path: string, content: string): boolean {
  let file: fs.File | null = null;
  try {
    file = fs.openSync(path, fs.OpenMode.CREATE | fs.OpenMode.WRITE_ONLY);
    fs.writeSync(file.fd, content);
    return true;
  } catch (e) {
    console.error('文件写入失败:', e.message);
    return false;
  } finally {
    if (file) fs.closeSync(file);
  }
}

✅ 常用 OpenMode 组合

模式	说明
READ_ONLY	只读
WRITE_ONLY	只写（清空原内容）
CREATE + WRITE_ONLY	创建并写入（最常用）
CREATE + APPEND	创建并追加
READ_WRITE	读写

⚠️ 避坑指南

• 用完必须 close：文件描述符有限，不关闭会泄漏
• 路径不要硬编码：永远通过 Context.filesDir 获取沙箱路径
• 大文件用流式：readTextSync 读大文件会撑爆内存
• 异常必须捕获：文件操作失败（磁盘满、权限问题）会抛异常

---

总结

@ohos.file.fs 是鸿蒙文件操作的基石。记住核心三板斧：open → 读写/操作 → close，再加上 try/catch 保护，就能应对绝大多数文件处理需求。它和 @ohos.data.preferences（配置存储）、@ohos.data.relationalStore（数据库）组成鸿蒙数据存储三件套。