鸿蒙沙箱目录共享捐献机制与fileAccess深度搜索实战

鸿蒙专家

在企业级应用开发中，跨应用批量文件协同一直是个棘手问题。用户在用生产力工具编辑大量工程文件后，这些文件被安全地锁在应用自己的沙箱目录里。若想让另一个渲染引擎或同厂矩阵应用直接处理这些文件，传统做法要么依赖 FilePicker 让用户逐个手选，要么复制到公共目录，既浪费存储，又增加非授权访问风险。

HarmonyOS 7.0（API 26）的 Core File Kit 针对这个场景给出了两个关键解法：一是应用沙箱目录共享捐献机制（sandboxShare），二是文件搜索功能的大幅增强。前者允许应用在严格的 MAC/DAC 鉴权管控下，把沙箱内某个目录主动“捐献”给指定应用访问；后者则重构了文件搜索底层逻辑，通过开放 inode 遍历的递归深度控制算法，解决深层目录树下的搜索性能与稳定性问题。

一、沙箱目录共享捐献机制

过去的沙箱像一座密不透风的堡垒，除 FilePicker 能通过 URI 临时授权外，应用之间无法直接读取对方目录。sandboxShare 则是一种主动授权行为，不是简单修改 Linux 目录的 rwx 权限，而是结合了 MAC（强制访问控制）与 DAC（自主访问控制）的双重安全体系。

DAC 层面仍按文件系统原有的 UID/GID 归属判断；MAC 层面引入更细粒度的“上下文流转”机制。当应用 A 把目录捐献给应用 B 时，系统并不改变文件的真实物理路径和所有权，而是在 VFS（虚拟文件系统）层为应用 B 建立一条携带特定 Token 的映射通道。一旦 A 撤销捐献或 Token 过期，通道会在纳秒级被切断，避免“悬空权限”导致非授权访问。

核心 API 位于 @kit.CoreFileKit 的 sandboxShare 模块。以下代码展示了捐献目录与撤销授权的完整流程：

2. import { sandboxShare } from '@kit.CoreFileKit';
3. import { BusinessError } from '@kit.BasicServicesKit';
4. import { fileIo } from '@kit.CoreFileKit';
6. export class ShareDonationManager {
7.     public async donateDirectory(sourceDirPath: string, targetBundleName: string): Promise<string> {
8.         try {
9.             // 检查目标目录是否存在且必须是目录
10.             let stat = fileIo.statSync(sourceDirPath);
11.             if (!stat.isDirectory()) {
12.                 throw new Error('捐献失败：目标路径不是一个合法的目录');
13.             }
15.             // 构造捐献策略参数
16.             let policy: sandboxShare.SharePolicy = {
17.                 targetBundleName: targetBundleName,
18.                 mode: sandboxShare.ShareMode.READ_WRITE, // 建议在不需要修改时用 READ_ONLY
19.                 expiration: 24 * 60 * 60 // 可选有效期，单位为秒
20.             };
22.             // 执行捐献，底层触发 MAC/DAC 鉴权流并建立 VFS 映射
23.             let sharedUri: string = await sandboxShare.shareDirectory(sourceDirPath, policy);
24.             console.info(`[ShareDonation] 目录捐献成功！生成跨应用 URI: ${sharedUri}`);
25.             return sharedUri;
26.         } catch (error) {
27.             let err = error as BusinessError;
28.             console.error(`[ShareDonation] 捐献过程发生异常: 错误码 ${err.code}, 错误信息 ${err.message}`);
29.             throw error;
30.         }
31.     }
33.     public async revokeDonation(sharedUri: string): Promise<void> {
34.         try {
35.             await sandboxShare.cancelShare(sharedUri);
36.             console.info(`[ShareDonation] URI 授权已彻底撤销: ${sharedUri}`);
37.         } catch (error) {
38.             console.error(`[ShareDonation] 撤销异常，请检查 URI 状态`);
39.         }
40.     }
41. }

复制代码

这里有两个易踩的坑。第一，如果业务是跨应用的长效离线处理，必须显式设置 expiration，否则 Token 可能在应用进程死亡后默认回收。第二，即便目标应用拿到 READ_WRITE 权限，如果目录下包含系统保留只读文件，底层 IO 拦截器仍会抛出权限不足。捐献只是平移当前最高权限，不是提权。

二、fileAccess.search 深度搜索

过去要在一个包含数万个素材、深达十几层的目录中寻找指定后缀文件，只能手写递归调用 fs.listFile，导致堆栈内存暴涨，频繁的 JS 到 C++ 跨语言调用也会消耗大量 CPU，界面容易卡顿。HarmonyOS 7.0 的 fileAccess.search 把搜索过程下沉到系统内核的系统调用层。

底层不是简单封装 find 命令，而是一种带启发式剪枝的 inode 广度优先/深度优先混合遍历算法。当递归深度达到阈值时，系统会直接在节点上剪枝，连子节点的系统调用都不发起。因此，maxDepth 参数不仅是业务限制，更是防止符号链接成环引发死循环和内存爆炸的核心手段。

实际使用时，通过 fileAccess.createFileAccessHelper 创建实例，再调用 search 方法，传入目标目录数组和搜索选项。API 返回的不是一次性数组，而是迭代器，可以按需惰性拉取结果，避免海量命中导致 OOM。

2. import { fileAccess } from '@kit.CoreFileKit';
3. import { common } from '@kit.AbilityKit';
5. export class DeepSearchManager {
6.     private fileAccessHelper: fileAccess.FileAccessHelper;
8.     constructor(context: common.UIAbilityContext) {
9.         this.fileAccessHelper = fileAccess.createFileAccessHelper(context);
10.     }
12.     public async searchMediaFiles(targetDirs: string[], keyword: string, limitDepth: number): Promise<Array<string>> {
13.         let resultPaths: Array<string> = [];
14.         try {
15.             let searchOptions: fileAccess.FileSearchOptions = {
16.                 pattern: keyword, // 支持 glob 模式，如 *.mp4
17.                 maxDepth: limitDepth,
18.                 fileFilter: {
19.                     types: [fileAccess.FileType.FILE]
20.                 }
21.             };
23.             console.info(`[DeepSearch] 正在发起多目录深度搜索，目标深度: ${limitDepth}`);
24.             let startTime = new Date().getTime();
26.             // 底层并行执行，多个目录会自动进入协程池
27.             let searchResult = await this.fileAccessHelper.search(targetDirs, searchOptions);
29.             let nextResult = await searchResult.next();
30.             while (!nextResult.done) {
31.                 let fileInfo = nextResult.value;
32.                 resultPaths.push(fileInfo.uri);
33.                 nextResult = await searchResult.next();
34.             }
36.             let costTime = new Date().getTime() - startTime;
37.             console.info(`[DeepSearch] 搜索完成！共找到 ${resultPaths.length} 个文件，耗时 ${costTime}ms`);
38.         } catch (err) {
39.             console.error(`[DeepSearch] 搜索过程异常，请排查路径有效性或权限。错误: ${err}`);
40.         }
41.         return resultPaths;
42.     }
43. }

复制代码

值得注意，FileSearchOptions 的 pattern 是专为文件系统优化的 glob 匹配机制，写 *.mp4 比正则 .*\.mp4$ 效率高得多。另外，如果提前 break 迭代器，底层搜索上下文可能不会立即释放。在极端密集调用下，容易耗尽底层句柄，务必确保流程完整闭环。

三、方案对比与适用边界

跨应用文件流转方面，FilePicker 适合少量手动选择，但操作笨重；复制到公共目录会浪费空间且增加泄露风险；sandboxShare 则适合批量、受控、可撤销的目录级共享。文件搜索方面，手写递归虽然灵活，但性能和稳定性差；fileAccess.search 适合海量文件、深层目录树的快速检索，尤其配合多目录并行搜索能显著提升效率。

四、避坑指南

1. 包名大小写和特殊符号必须确认一致。包名写错不一定会立刻报错，但目标应用访问时会触发 MAC 策略阻断，抛出模糊的 Permission denied。
2. 捐献目录后，两个应用操作同一物理文件块，必须约定并发控制机制。例如目标应用在写 SQLite 事务时，源应用强行重置文件，可能导致文件损坏。
3. maxDepth 不宜设置过大，比如 999。根据实测，企业级业务限制在 3 到 5 层即可覆盖绝大多数场景，过深会拖慢存储系统全局响应。
4. 迭代器中断后，尽量让资源生命周期完整闭环，避免底层句柄耗尽。

五、总结

HarmonyOS 7.0 的 Core File Kit 把容易出错、效率低下的文件共享与搜索逻辑，下沉到了系统安全的底层实现。sandboxShare 用 MAC/DAC 双重鉴权和 VFS 映射，平衡了沙箱隔离与跨应用协作；fileAccess.search 则用内核级剪枝算法解决了深层目录性能瓶颈。在架构选型时理解这些底层机制，能让我们在企（业级）应用中做出更合理的技术决策，少踩一些没有文档的暗坑。