前言

对于有 Android 开发经验的朋友来说，以前我们习惯了满磁盘找文件，申请个存储权限就能扫描整个 SD 卡。但在鸿蒙 HarmonyOS 6（API 20）里，这个路子走不通了。

鸿蒙采用了非常严格的沙箱机制。简单说，系统给每个 App 分了一块独立的自留地，你只能在这个圈子里活动，外面的世界你看不见，别人也看不见你。这虽然增加了安全性，但也改变了我们写代码的习惯。很多开发者刚上手时，经常遇到文件明明写入成功了，但就是找不到在哪里,或者读取文件报权限错误的问题。

我会带你深入理解这套机制。我们会从沙箱的底层原理讲起，搞清楚el1和el2到底是个什么鬼，然后手把手教你用最新的fs(fileIo) 模块进行高效的文件读写。

一、 搞懂应用沙箱，你的代码到底在读写哪里？

所谓沙箱，其实就是系统做的一层虚拟化隔离。在代码里，你以为你访问的是/data/storage，但实际上系统底层通过挂载技术，把它映射到了一个包含你应用包名和用户 ID 的物理路径上。

1. 物理路径 vs 逻辑路径

我们在开发调试的时候，经常会用hdc shell进入真机去查看文件。这时候你会发现一个现象：你在代码里打印的路径，和你在 shell 里看到的路径完全不一样。

• 逻辑路径：这是我们在代码里通过Context获取到的路径。比如/data/storage/el2/base/haps/entry/files。对于应用来说，这个路径是固定的，不随用户 ID 变化。
• 物理路径：这是文件真正存储在闪存上的位置。它通常长这样：/data/app/el2/100/base/com.example.myapp/haps/entry/files。

物理路径里多了一个100，这是当前用户的 ID。如果有应用分身，或者手机切换了多用户，这个 ID 会变。所以，千万不要在代码里硬编码物理路径，否则一旦环境变化，你的 App 就会直接崩溃。

2. 核心概念：EL1 与 EL2 的加密隔离

在鸿蒙的路径里，你肯定见过el1和el2这两个词。这可不是随便命名的文件夹，它们代表了数据的加密等级。搞不清楚这个，你的后台任务可能会读取失败。

• EL1 (Device Encrypted - 设备级加密)
  • 含义：只要手机开机了，不管用户有没有输入密码解锁，这块区域的数据都是可以解密的。
  • 场景：适合存放那些不需要用户交互就能运行的数据。比如你的 App 是个闹钟，或者有来电显示功能。如果这些资源放在 EL2，手机重启后还没解锁，闹钟就响不了，因为读不到铃声文件。
  • 安全性：相对较低，因为只要开机就能读。
• EL2 (User Encrypted - 用户级加密)
  • 含义：安全性更高。只有当用户解锁屏幕（输入密码、指纹或人脸）后，这块区域的数据才会被解密。如果手机处于“重启后未解锁”状态，或者部分高安全模式下，这里的数据是读不到的。
  • 场景：绝大多数用户数据都应该放在这里。比如相册照片、聊天记录、用户通过filesDir下载的文件。
  • 默认值：我们常用的context.filesDir，默认指向的就是 EL2 区域。

如果你的应用有特殊的后台运行需求（比如开机自启的服务），你需要专门去获取 EL1 的路径，而不是直接用默认的filesDir。

二、 Context 路径管理，给文件找个正确的家

在 Android 里我们习惯用getExternalFilesDir或者getCacheDir。在鸿蒙里，UIAbilityContext为我们提供了一整套标准的路径属性。选对路径，不仅是为了管理方便，更是为了避免被系统误删数据。

1.filesDir：核心数据仓库

• 路径示例：/data/storage/el2/base/haps/entry/files
• 作用：存放应用需要长期保存的文件。比如用户编辑的文档、下载的离线视频、解压后的游戏资源包。
• 清理策略：永久存储。除非用户主动卸载 App，或者去系统设置里点击“清除数据”，否则这里的文件会一直都在。系统不会自动清理这里。

2.cacheDir：临时缓存站

• 路径示例：/data/storage/el2/base/haps/entry/cache
• 作用：存放各种可以重新生成的缓存数据。比如网络图片的缓存、接口数据的 JSON 缓存。
• 清理策略：随时可能被删。当系统存储空间不足时，操作系统有权在不通知应用的情况下，直接删除这个目录下的文件来释放空间。所以，绝对不要把用户的草稿或者重要凭证放在这里。

3.tempDir：用完即弃

• 路径示例：/data/storage/el2/base/haps/entry/temp
• 作用：存放处理过程中的中间产物。比如你做图片压缩，压缩后的临时文件可以放这，上传完网络后就删掉。
• 清理策略：建议开发者用完手动删除。系统也会频繁清理。

4.distributedFilesDir：分布式跨端同步

• 作用：这是鸿蒙的杀手锏。如果你把文件存在这个目录下，系统底层的分布式数据服务（DDS）会自动把这个文件同步到组网内的其他设备上（比如旁边的平板）。
• 代码体验：你不需要写 Socket，不需要写传输协议，只需要把文件写进去，另一端就能读出来。这对于做“接续”功能的开发者来说简直是神器。

// 在 EntryAbility.ts 或页面中 import { common } from '@kit.AbilityKit'; // 获取上下文 let context = getContext(this) as common.UIAbilityContext; console.info(`[FilePath] filesDir: ${context.filesDir}`); console.info(`[FilePath] cacheDir: ${context.cacheDir}`); console.info(`[FilePath] tempDir: ${context.tempDir}`); console.info(`[FilePath] distributedDir: ${context.distributedFilesDir}`);

三、 实战 fileIo (fs) 模块：文件的增删改查

拿到了路径，接下来就是真刀真枪地操作文件了。在 HarmonyOS 6 中，文件操作的核心模块是@kit.CoreFileKit下的fileIo，通常我们会重命名为fs导入。

1. 基础写入与读取 同步 vs 异步

fs模块的大部分 API 都提供了 Sync（同步）和 Promise（异步）两个版本。

• 同步 (Sync)：阻塞主线程。只建议在读取极小的配置文件（比如几 KB）时使用。
• 异步 (Promise)：不阻塞主线程。强烈建议在绝大多数场景下使用异步，尤其是读写图片、视频时，否则界面会掉帧卡顿。

下面是一个标准的异步写入字符串并读取的流程。

import { fileIo as fs } from '@kit.CoreFileKit'; import { util } from '@kit.ArkTS'; // 引入 util 用于高效解码 import { BusinessError } from '@kit.BasicServicesKit'; async function writeAndReadFile(filePath: string) { let file: fs.File | undefined; try { // 1. 打开文件 (读写模式 | 不存在则创建 | 存在则截断清空) file = await fs.open(filePath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE | fs.OpenMode.TRUNC); // 2. 写入数据 const writeContent = "Hello, HarmonyOS 6! 鸿蒙, 你好!"; await fs.write(file.fd, writeContent); console.info(`[FileIO] Write success, length: ${writeContent.length}`); // 3. 读取数据 // 重置游标到文件头 fs.lseek(file.fd, 0, fs.SeekMode.SEEK_SET); // 建立缓冲区 (按需申请大小，避免 OOM) const bufferSize = 4096; let buffer = new ArrayBuffer(bufferSize); const readLen = await fs.read(file.fd, buffer); // 4. 解码 (API 20 推荐方式) // 使用 TextDecoder 处理 UTF-8，完美支持多字节字符 const decoder = util.TextDecoder.create('utf-8', { ignoreBOM: true }); // 仅解码实际读取的长度，避免乱码 const readContent = decoder.decodeWithStream(new Uint8Array(buffer.slice(0, readLen))); console.info(`[FileIO] Read result: ${readContent}`); } catch (err) { const error = err as BusinessError; console.error(`[FileIO] Operation failed. Code: ${error.code}, Message: ${error.message}`); } finally { // 5. 资源释放 (至关重要) if (file) { // 推荐使用同步关闭，确保句柄立即释放 fs.closeSync(file); } } }

• FD (File Descriptor)：文件描述符。在代码里你看到的file.fd是一个整数。它是系统内核给这个打开的文件分配的一个 ID。后续所有的读写操作都要拿着这个 ID 去找系统。
• OpenMode：CREATE是不存在就创建，TRUNC是如果有内容就清空。这两个组合起来就是“覆盖写入”。如果你想追加内容，应该用APPEND。
• ArrayBuffer：鸿蒙底层 IO 交换数据用的是二进制缓冲区。读取文本需要自己转换，读取图片则直接把 Buffer 丢给 Image 组件或解码器。
• closeSync：在finally块中关闭文件是标准操作。虽然 JS 有垃圾回收，但 FD 资源是有限的（通常一个进程最多打开 1024 个文件），不手动关可能会导致“Too many open files”错误。

四、 进阶：如何处理大文件与流式操作？

如果你要处理一个 500MB 的视频文件，用上面的fs.read一次性读进ArrayBuffer，你的应用立马就会崩，因为内存不够（OOM）。这时候，我们必须使用流（Stream）。

流的核心思想是：像水管一样，一点一点地把数据读出来，处理完一点，就丢掉一点，再读下一点。

1. 使用 createStream 建立管道

鸿蒙提供了fs.createStream，它比底层的 open/read 更高级，适合做文件拷贝、网络上传等场景。

假设我们要把一个文件从cacheDir复制到filesDir。

import { fileIo as fs } from '@kit.CoreFileKit'; import { BusinessError } from '@kit.BasicServicesKit'; /** * 使用 Stream 管道高效复制文件 * @param srcPath 源文件沙箱路径 * @param destPath 目标文件沙箱路径 */ async function copyByStream(srcPath: string, destPath: string) { // 定义在 try 外面，方便 finally 中关闭 let inputStream: fs.Stream | undefined = undefined; let outputStream: fs.Stream | undefined = undefined; try { // 1. 创建流 // mode 'r': 只读模式，打开源文件 // mode 'w+': 读写模式，文件不存在则创建，存在则清空内容 (TRUNC) inputStream = await fs.createStream(srcPath, "r"); outputStream = await fs.createStream(destPath, "w+"); // 2. 准备缓冲区 const bufferSize = 64 * 1024; let buffer = new ArrayBuffer(bufferSize); let bytesRead = 0; let totalBytes = 0; console.info('[Stream] 开始流式拷贝...'); // 3. 循环读写 // inputStream.read 返回读取到的实际字节数 while ((bytesRead = await inputStream.read(buffer)) > 0) { // slice 会创建新的内存对象，导致频繁 GC。 // 直接使用 write 的第二个参数 options 来指定写入长度。 await outputStream.write(buffer, { length: bytesRead }); totalBytes += bytesRead; } console.info(`[Stream] 拷贝完成，共传输: ${totalBytes} bytes`); } catch (error) { const err = error as BusinessError; console.error(`[Stream] Copy failed: code=${err.code}, msg=${err.message}`); } finally { // 4. 安全关闭流 (API 20 严格模式要求) try { if (inputStream) { inputStream.closeSync(); } if (outputStream) { outputStream.closeSync(); } } catch (closeErr) { // 忽略关闭时的次要错误，避免覆盖主业务错误 console.warn(`[Stream] Close stream warning: ${JSON.stringify(closeErr)}`); } } } // ------------------------------------------ // 调用示例 (放在 build 或方法中) // ------------------------------------------ /* const context = getContext(this) as common.UIAbilityContext; const src = context.cacheDir + '/big_video.mp4'; const dest = context.filesDir + '/saved_video.mp4'; this.copyByStream(src, dest); */

这里我们定义的 buffer 大小是 4096 (4KB)。对于特别大的文件，可以适当调大到 64KB 或 128KB 来减少 IO 调用的次数，提升速度。但不要设得太大，否则就失去了流式处理节省内存的意义。

2. 随机读写 (Random Access)

有时候我们不需要从头读到尾，比如我们想读取一个 MP4 文件的最后 100 个字节来获取元数据，或者修改 SQLite 数据库中间的某一行。

fs.read和fs.write方法都接受一个options参数，其中包含offset。

// 读取文件中间的内容 async readMiddle(filePath: string) { let file = await fs.open(filePath, fs.OpenMode.READ_ONLY); // 假设我们要从第 100 个字节开始，读 50 个字节 let buffer = new ArrayBuffer(50); let readLen = await fs.read(file.fd, buffer, { offset: 100 // 核心：设置偏移量 }); fs.closeSync(file); }

五、 文件监控：当配置变了，我怎么知道？

有些场景下，我们的配置文件可能是由另一个进程（比如下载服务）更新的。我们的 UI 需要实时感知到文件的变化并刷新。轮询查文件显然太 Low 了，耗电还低效。

鸿蒙提供了Watcher (观察者)机制。我们可以订阅一个文件或目录的变化事件。

import { fileIo as fs } from '@kit.CoreFileKit'; import { BusinessError } from '@kit.BasicServicesKit'; import { util } from '@kit.ArkTS'; async function readRandomAccess(filePath: string) { let file: fs.File | undefined; try { // 1. 打开文件 file = await fs.open(filePath, fs.OpenMode.READ_ONLY); // ------------------------------------------------- // 场景 A: 读取固定位置 (从第 100 字节开始) // ------------------------------------------------- const bufferA = new ArrayBuffer(50); const lenA = await fs.read(file.fd, bufferA, { offset: 100 // 绝对偏移量 }); console.info(`场景A读取长度: ${lenA}`); // ------------------------------------------------- // 场景 B: 读取文件末尾最后 100 个字节 (常见需求) // ------------------------------------------------- // 第一步：获取文件总大小 const stat = await fs.stat(file.fd); const fileSize = stat.size; const tailSize = 100; // 确保文件够读，防止偏移量为负数 if (fileSize >= tailSize) { const bufferB = new ArrayBuffer(tailSize); // 计算偏移量：总大小 - 要读的长度 const startOffset = fileSize - tailSize; const lenB = await fs.read(file.fd, bufferB, { offset: startOffset }); // 解码展示 const textDecoder = util.TextDecoder.create('utf-8', { ignoreBOM: true }); const content = textDecoder.decodeWithStream(new Uint8Array(bufferB)); console.info(`文件末尾内容: ${content}`); } } catch (err) { const error = err as BusinessError; console.error(`读取失败: code=${error.code}, msg=${error.message}`); } finally { // 2. 【至关重要】在 finally 中关闭文件 // 无论上面读取是否成功，必须释放 FD，否则应用运行久了会崩溃 if (file) { fs.closeSync(file); } } }

以下是去除了口语化比喻、采用专业技术文档风格优化的内容。代码部分已适配HarmonyOS Next (API 12+)的严格模式，增加了必要的错误处理和文件校验。

六、 跨应用文件共享：调用第三方应用打开文件

在沙箱隔离机制下，应用无法直接通过物理路径（如/data/storage/...）访问其他应用的沙箱数据。若需调用外部应用（如系统浏览器、PDF 阅读器）打开当前应用沙箱内的文件，必须使用URI（统一资源标识符）配合Want 授权机制。

1. 核心机制

实现跨应用文件访问主要依赖以下两个步骤：

• 路径转 URI：使用fileUri模块将沙箱内的物理路径转换为跨应用可识别的 URI（格式为file://bundleName/...）。
• 授权分发：在构建Want对象时，设置FLAG_AUTH_READ_URI_PERMISSION标志位，向目标应用临时授予该 URI 的读取权限。

2. 标准实现代码

以下代码封装了一个通用的文件打开方法，包含文件存在性校验与异常处理流程：

import { fileUri, fileIo as fs } from '@kit.CoreFileKit'; import { common, Want, wantConstant } from '@kit.AbilityKit'; import { BusinessError } from '@kit.BasicServicesKit'; import { promptAction } from '@kit.ArkUI'; /** * 调用系统能力打开沙箱文件 * @param context UIAbility 上下文 * @param filePath 沙箱内的物理路径 (如: context.filesDir + '/test.pdf') * @param fileType 文件的 MIME 类型 (如: 'application/pdf', 'image/jpeg') */ function openFileWithSystemApp(context: common.UIAbilityContext, filePath: string, fileType: string) { // 1. 校验文件是否存在 // 直接拉起不存在的文件会导致目标应用崩溃或报错 let isExist = false; try { isExist = fs.accessSync(filePath); } catch (e) { isExist = false; } if (!isExist) { promptAction.showToast({ message: '文件不存在，无法打开' }); return; } try { // 2. 将物理路径转换为 URI // 转换结果示例：file://com.example.app/data/storage/el2/base/haps/entry/files/test.pdf const uri = fileUri.getUriFromPath(filePath); console.info(`[Share] File URI: ${uri}`); // 3. 构建 Want 对象 const want: Want = { // 标准动作：查看数据 action: 'ohos.want.action.viewData', // 数据源：文件 URI uri: uri, // MIME 类型：用于系统筛选可打开该文件的应用 type: fileType, // 【关键配置】授予目标应用读取 URI 的权限 flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION }; // 4. 拉起目标应用 context.startAbility(want) .then(() => { console.info('[Share] 成功拉起外部应用'); }) .catch((err: BusinessError) => { // 错误处理：通常是因为未安装支持该文件类型的应用 console.error(`[Share] 拉起失败: code=${err.code}, msg=${err.message}`); promptAction.showToast({ message: '未找到可打开该文件的应用' }); }); } catch (err) { console.error(`[Share] URI 转换或授权异常: ${JSON.stringify(err)}`); } } // --- 调用示例 --- // 在 UIAbility 或页面中调用： // const filePath = this.context.filesDir + '/report.pdf'; // openFileWithSystemApp(this.context, filePath, 'application/pdf');

3. 技术要点解析

• fileUri.getUriFromPath：开发者不应尝试手动拼接file://格式的字符串，因为不同设备或系统版本的路径映射规则可能存在差异。
• wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION：这是跨应用文件访问的安全基石。若省略此标志，目标应用在尝试读取 URI 时会抛出Permission Denied错误。
• MIME Type(文件类型)：必须准确传入文件的 MIME 类型（例如application/vnd.ms-excel或video/mp4）。系统依赖此字段过滤并展示可用的应用列表。若类型未知或错误，可能导致无法匹配到合适的应用。

总结

今天我们把鸿蒙的文件系统拆解了一遍。

1. 沙箱机制：记住el1和el2的区别，物理路径和逻辑路径的映射关系。这是安全的基石。
2. 路径选择：filesDir存重要的，cacheDir存临时的，tempDir存即用即弃的。别乱放，小心被系统删了。
3. IO 操作：能用异步就别用同步，大文件一定要用流（Stream），避免 OOM。
4. 文件分享：跨应用交互要用 URI + Want 授权，不要直接传路径。

掌握了这些，你就不再是那个只会写writeString的初级开发者了。你已经具备了构建健壮数据存储架构的能力。