当前位置：首页 > news >正文

《HarmonyOS技术精讲-Core File Kit》第4篇：目录操作与文件遍历

news 2026/7/1 15:52:14

在HarmonyOS NEXT的开发中，文件系统的操作是很多功能模块的基础。很多人第一次接触fileManager这个目录操作 API 时，会觉得很简单：不就是创建目录、删除文件、遍历一下吗？官方示例在模拟器上也能运行。

但实际项目里，问题往往出现在对目录结构动态变化的管理上。比如，你需要在应用启动时，根据用户 ID 创建多级目录来缓存图片和数据；比如，你需要持续监控某个数据目录，一旦有新的文件生成就去处理；又或者，你需要在用户退出登录时，干净地清理掉用户目录。

这个功能本身不复杂，但真正麻烦的是目录的生命周期管理和遍历时与 UI 的状态同步。这篇笔记重点拆解fileManager里的四个核心 API：mkdir、rmdir、listFile和watch。

它解决什么问题

在 HarmonyOS NEXT 中，访问应用沙箱内的文件目录，绕不开fileManager。它主要解决三个场景：

结构化存储：应用可以按照业务逻辑，在沙箱内创建多级目录来存放不同类型的文件，而不是把所有文件堆在一个目录下。
资源管理：在文件下载、日志存储、缓存清理等场景，需要程序化地遍历目录，获取指定的子文件或子目录。
事件驱动：watch接口允许监听目录的变化，比如当用户或其它进程向目录写入新文件时，应用可以自动响应，而无需轮询。

不适合的场景：

当需要批量操作海量文件（数万级别）时，直接遍历整个目录会导致明显的性能卡顿，此时应结合索引或数据库来管理文件路径。
watch监控不适合用于全局文件系统的变化，它局限于应用自己的沙箱目录。

环境说明

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

核心实现

1. 创建多层目录

官方的mkdir只能创建单层目录。如果需要创建a/b/c这种多级路径，需要逐级创建，或者自己封装一个工具函数。

// 文件: utils/DirUtils.etsimport{fileIoasfs,common}from'@kit.CoreFileKit';exportclassDirUtils{/** * 递归创建目录 * @param context 应用上下文，用于获取沙箱路径 * @param relativePath 相对于沙箱根目录的路径，例如: "datas/user/2024/images" */staticasynccreateDirectories(context:common.Context,relativePath:string):Promise<boolean>{letbasePath:string=context.filesDir;// 应用沙箱根目录lettargetDir:string=`${basePath}/${relativePath}`;// 1. 先判断目标目录是否已经存在letisExist:boolean=awaitthis.fileAccessExists(targetDir);if(isExist){console.info("目录已存在:",targetDir);returntrue;// 已存在，视为成功}// 2. 逐级创建。使用 'mkdir' 本身不支持递归，我们手动拆分路径letpathSegments:string[]=targetDir.replace(basePath,'').split('/').filter(segment=>segment.length>0);letcurrentPath:string=basePath;for(letsegmentofpathSegments){currentPath=`${currentPath}/${segment}`;try{// 注意：fileIo.mkdirSync 不常用，推荐使用异步的 fs.mkdir// 这里使用同步方式创建，避免回调地狱，但注意不要在UI主线程长时间运行大循环letstat=awaitfs.mkdir(currentPath,false);// false 表示非递归console.info("创建目录成功:",currentPath);}catch(err){// 如果目录已存在，会报错。我们在上层已经判断了 targetDir 是否存在，// 但如果中间目录已经存在，这里会捕获到错误，这是正常的。console.error("创建目录失败或目录已存在:",err.message);// 继续循环，不影响后续目录的创建continue;}}// 3. 再次确认最终目录是否存在returnawaitthis.fileAccessExists(targetDir);}privatestaticasyncfileAccessExists(filePath:string):Promise<boolean>{try{awaitfs.stat(filePath);// 如果文件或目录不存在，stat会抛出异常returntrue;}catch(err){returnfalse;}}}

注意事项：这个实现是同步风格的异步操作。如果pathSegments非常长，比如有 20 级，它会依次创建。对于大多数场景，10 级以内的目录结构是够用的。不建议在aboutToAppear或者build()里直接await这个函数，最好放在aboutToAppear里用TaskPool或者async异步执行，避免阻塞页面初始化。

2. 删除目录

rmdir只能删除空目录。如果目录里有文件，需要先遍历并删除文件，或者使用unlink逐个删除文件。

// 追加在 DirUtils.ets 中/** * 递归删除目录及所有内容 */staticasyncdeleteDirectory(context:common.Context,relativePath:string):Promise<boolean>{lettargetPath=`${context.filesDir}/${relativePath}`;// 1. 先获取目录下的所有条目letentries:fs.DirEntry[]=awaitfs.listFile(targetPath,{recursive:true});// 2. 倒序遍历，先删除文件，再删除目录for(leti=entries.length-1;i>=0;i--){letentry=entries[i];letfullPath=`${targetPath}/${entry.name}`;if(entry.isDirectory()){// 如果是子目录，直接尝试删除，因为已经在递归列表里了，里面的文件应该已经被删掉了awaitfs.rmdir(fullPath).catch(e=>console.error("删除目录失败:",fullPath,e.message));}else{// 如果是文件，使用 unlink 删除awaitfs.unlink(fullPath).catch(e=>console.error("删除文件失败:",fullPath,e.message));}}// 3. 最后删除顶层目录awaitfs.rmdir(targetPath).catch(e=>console.error("删除顶层目录失败:",e.message));returntrue;}

为什么选择recursive: true：因为listFile如果不开启recursive，只会返回当前目录下的条目。我们需要递归删除，所以获取所有子条目是必要的。注意这里没有使用fsPromise.rm（如果有这个 API），而是用最原生的rmdir和unlink，兼容性更好。

3. 遍历目录并打印路径

这个操作在展示文件列表时非常常见。

// 文件: pages/FileListPage.etsimport{fileIoasfs,common}from'@kit.CoreFileKit';import{BusinessError}from'@kit.BasicServicesKit';@Entry@Componentstruct FileListPage{@StatefilePaths:string[]=[];build(){Column(){Button("遍历并打印所有文件路径").onClick(()=>this.traverseDirectory())List({space:4}){ForEach(this.filePaths,(path:string)=>{ListItem(){Text(path).fontSize(14)}})}.layoutWeight(1)}.padding(20).width('100%').height('100%')}asynctraverseDirectory(){letcontext=getContext(this)ascommon.Context;lettargetDir=`${context.filesDir}/datas/user/2024`;try{letentries:fs.DirEntry[]=awaitfs.listFile(targetDir,{recursive:true,filter:true});// filter: true 表示过滤掉隐藏文件（以 '.' 开头），通常不需要隐藏文件// 打印路径letpaths:string[]=[];for(letentryofentries){paths.push(`${targetDir}/${entry.name}`);}// 更新UI状态，必须在UI主线程this.filePaths=paths;console.info("成功遍历文件列表:",JSON.stringify(paths));}catch(err){leterror=errasBusinessError;console.error("遍历目录失败:",error.message);}}}

性能注意：当recursive: true并且目录层级很深、文件很多时（比如超过 2000 个文件），这个listFile操作可能会耗时超过 200ms。如果在 UI 主线程直接await，会导致页面掉帧。对于超大规模目录，推荐在子线程（如TaskPool）里执行listFile，然后将结果通过emitter发送回主线程更新 UI。

4. 设置目录变化监控

watch接口可以监听指定目录的 {add, remove, update, move} 事件。这个能力在下载管理、日志实时追踪场景下很有价值。

// 文件: utils/WatchManager.etsimport{fileIoasfs}from'@kit.CoreFileKit';import{BusinessError}from'@kit.BasicServicesKit';exportclassWatchManager{privatewatchId:number=-1;privateonFileChange:((event:string,fileName:string)=>void)|null=null;/** * 开始监控某个目录 * @param targetPath 要监控的目录绝对路径 * @param callback 事件回调 */startWatch(targetPath:string,callback:(event:string,fileName:string)=>void){this.onFileChange=callback;// watch 返回一个 watcher 实例letwatcher=fs.createWatcher(targetPath,{recursive:false,// 默认只监控当前目录，不递归监控子目录});// 注册事件监听watcher.on('change',(event:string,fileName:string)=>{// event: "add" | "remove" | "update" | "move"console.info("文件变化事件:",event,fileName);if(this.onFileChange){// 注意：这里回调是在监听线程，不能直接修改UI状态，需要抛回主线程// 推荐使用 AppStorage 或者 emitter 来同步this.onFileChange(event,fileName);}});// 开启监控watcher.start();// 返回的 watchId 可以用于后续停止监控this.watchId=watcher.id;}stopWatch(){if(this.watchId!==-1){// 停止监控fs.stopWatch(this.watchId);this.watchId=-1;console.info("停止文件监控");}}}

坑点提醒：

recursive: false是默认值，意思是只监控targetPath这个目录本身的变化。如果你需要监控其子目录下的文件变化，官方文档至今（API 13）仍不支持recursive: true。这是一个比较明显的限制。
回调运行在watcher的内部线程。如果你在回调里尝试runOnMainThread或者直接修改@State变量，会导致 ArkUI 的并发冲突。正确的做法是使用emitter或者共享的@LocalStorageProp来中转。

常见问题

1. 权限申请问题

现象：真机调试时，调用fs.mkdir或fs.listFile时，返回13900001权限错误。

原因：HarmonyOS NEXT 对沙箱目录访问有严格管控。虽然context.filesDir是应用私有目录，但如果尝试创建目录时，路径包含非法字符（如..、绝对路径越权），或者尝试在非沙箱路径下操作，就会报权限错误。

解决方案：确保所有路径都基于context.filesDir进行拼接。不要尝试操作external或download目录，除非你申请了ohos.permission.READ_MEDIA等权限。

2. watch 回调粘滞

现象：watch回调被频繁触发，或者一次文件写入触发了多次add事件。

原因：watch底层基于 inotify，对于大文件的写入（比如视频），系统会触发多次MODIFY事件。官方提供了去抖机制，但默认行为是实时上报。

解决方案：在回调内部添加防抖逻辑：

watcher.on('change',debounce((event:string,fileName:string)=>{// 你的业务逻辑},300));// 300ms 内只处理最后一次事件

3. 遍历时遇到空目录

现象：listFile返回的entries数组是空的，但目录确实存在。

原因：这是因为listFile在不设置recursive或filter时，只会返回可见的文件和目录。如果目录里只有隐藏文件（以.开头），且没有设置filter: false，则列表会为空。

解决方案：明确设置{ filter: false }来包含隐藏文件。如果是判断目录是否存在，应该使用fs.stat而非listFile。

最佳实践

不要在 build() 中频繁创建目录对象：fileIo的DirEntry对象创建成本不高，但如果在build()里用ForEach多次调用fs.stat或fs.listFile，ArkUI 会频繁触发组件重建。推荐把目录列表数据缓存到@StorageLink或AppStorage中。
使用 try-catch 保护文件操作：文件系统操作很容易抛异常，如权限拒绝、磁盘空间不足、路径不存在。不捕获异常会导致应用闪退。上述代码中几乎每一个await都包裹了catch，这是项目稳定性的关键。
合理设置recursive参数：监控目录变化时，如果业务场景不需要监控子目录，不要开启recursive: true（虽然目前watch本身也不支持）。遍历目录时，如果只需要当前层级，不要加recursive，否则会降低性能。

Demo 入口

文件:pages/Index.ets

@Entry@Componentstruct Index{build(){Column(){Text("目录操作与文件遍历 Demo").fontSize(20).margin({bottom:20})Button("创建测试目录结构").onClick(async()=>{letcontext=getContext(this)ascommon.Context;awaitDirUtils.createDirectories(context,"test/images/2024");awaitDirUtils.createDirectories(context,"test/docs");console.info("目录创建完成");})Button("遍历并打印所有文件").onClick(async()=>{letcontext=getContext(this)ascommon.Context;letentries=awaitfs.listFile(`${context.filesDir}/test`,{recursive:true});for(leteofentries){console.info("发现条目:",e.name);}})// 其他按钮...}.padding(20).width('100%').height('100%')}}

FAQ

Q：为什么真机正常，模拟器上 watch 回调不触发？
A：模拟器上对 inotify 的支持不完整。建议所有文件变化相关的功能都以真机为准进行测试。模拟器常被用于 UI 调试，不适合验证这类系统 API 行为。

Q：页面返回后，如何停止 watch 监控？
A：可以在页面的onPageHide或aboutToDisappear生命周期中调用stopWatch()方法。如果不在页面销毁时主动停止，监控可能会持续存在，导致内存泄漏或意外回调。

Q：为什么创建目录时，明明路径写对了，但还是报ERRNO_EEXIST错误？
A：这个错误表示目录已存在。在官方示例里，mkdir没有exists判断。写法上应该先stat，判断不存在后再创建。我们的createDirectories工具函数已经做了这件事，使用时直接调用即可。