《HarmonyOS技术精讲-Core File Kit》第15篇：错误处理与异常排查指南

《HarmonyOS技术精讲-Core File Kit》第15篇错误处理与异常排查指南文件操作是应用开发中最基础也最容易出问题的环节。HarmonyOS NEXT 的 Core File Kit 提供了统一文件访问接口但很多开发者遇到文件操作异常时只做了简单的 try-catch错误信息直接弹 Toast 或者干脆不处理。结果是用户遇到“文件保存失败”时一脸懵开发者拿到日志也看不出具体问题。这篇文章不讲 API 怎么用直接总结 Core File Kit 文件操作中最常见的错误码给出一个完整的错误处理模板让你能快速定位问题而不是在日志里大海捞针。错误码背后的真实场景在 HarmonyOS 中文件操作失败时会抛出BusinessError对象里面包含code和message。这几个错误码出现频率最高错误码含义真实触发场景13900001操作失败通用文件写入内容格式不对、路径非法13900002文件不存在路径写错了、文件被删除13900003权限错误没申请文件读写权限、沙箱路径访问越界13900004存储空间不足设备磁盘满了、沙箱配额用完13900005文件已存在create() 时文件已存在但未指定覆盖13900006路径不是文件把目录当文件打开了13900007文件被占用另一个进程正在写文件这些错误码在官方文档有说明但实际开发中容易忽略的是同一个操作可能触发多个错误码比如磁盘满时写文件可能先报权限错误13900003再报磁盘满13900004。错误处理一定要按优先级走。完整的错误处理示例下面这个代码段覆盖了文件读写时的常见异常并且对用户和开发者分别输出不同级别的信息import{fileIo}fromkit.CoreFileKit;import{BusinessError}fromkit.BasicServicesKit;EntryComponentstruct FileOperationExample{Statestatus:string等待操作;build(){Column(){Text(文件读写状态)Text(this.status).fontSize(16)Button(写入文件).onClick(()this.writeTestFile())Button(读取文件).onClick(()this.readTestFile())}.padding(20).width(100%).height(100%)}// 写入文件的完整错误处理示例writeTestFile():void{this.status写入中...;try{// 沙箱路径应用自带目录确保有权限letcontextgetContext(this);letfilePath:stringcontext.cacheDir/test.txt;// 创建文件如果已存在则覆盖letfile:fileIo.FilefileIo.openSync(filePath,fileIo.OpenMode.CREATE|fileIo.OpenMode.WRITE_ONLY);// 写入数据fileIo.writeSync(file.fd,newArrayBuffer(10));fileIo.closeSync(file);this.status写入成功;}catch(error){letbizErrorerrorasBusinessError;// 针对不同错误码做分级处理switch(bizError.code){case13900004:// 存储空间不足this.status存储空间不足请清理后再试;console.warn([FileError] 存储空间不足:${bizError.message});break;case13900003:// 权限错误this.status权限不足请在设置中允许文件读写;console.error([FileError] 权限被拒绝:${bizError.message});break;case13900002:// 文件不存在一般不会在这出现因为用了CREATE模式case13900001:// 通用错误default:this.status写入失败请稍后重试;console.error([FileError] 写入异常 code${bizError.code}, message${bizError.message});}}}// 读取文件的错误处理readTestFile():void{this.status读取中...;try{letcontextgetContext(this);letfilePath:stringcontext.cacheDir/test.txt;letfile:fileIo.FilefileIo.openSync(filePath,fileIo.OpenMode.READ_ONLY);letstatfileIo.statSync(filePath);letbufnewArrayBuffer(stat.size);fileIo.readSync(file.fd,buf);fileIo.closeSync(file);this.status读取成功;}catch(error){letbizErrorerrorasBusinessError;switch(bizError.code){case13900002:// 文件不存在this.status文件不存在请先写入;break;default:this.status读取失败;console.error([FileError] 读取异常 code${bizError.code}, message${bizError.message});}}}}关键点说明用fileIo.openSync()时建议显式指定OpenMode.CREATE | OpenMode.WRITE_ONLY避免文件已存在时直接报错。BusinessError的message字段内容是可读的但生产环境中建议只对用户显示预定义中文提示把原始 message 写到日志。switch-case不要写死所有错误码留一个default兜底因为后续 SDK 更新可能新增错误码。常见问题 1权限被拒绝时为什么没有弹窗现象调用writeSync()时捕获到13900003但用户手机没有弹出文件权限授权弹窗。原因HarmonyOS 的文件权限分为系统级和沙箱级。沙箱路径下的文件操作不需要额外权限比如context.cacheDir但如果访问外部存储比如/data/storage/el2/base外的路径就需要在module.json5中申请ohos.permission.READ_MEDIA或ohos.permission.WRITE_MEDIA。没有申请权限时错误码都是 13900003但系统不会自动弹窗。解法先确认文件路径是否在沙箱范围内。如果需要访问外部存储必须在module.json5中添加requestPermissions并调用abilityAccessCtrl.requestPermissionsFromUser()主动请求授权。不要在 try-catch 里期待系统帮你弹窗。常见问题 2磁盘空间足够但写入仍然报 13900004现象设备存储还有十几个 G但写入小于 1KB 的文件时抛出 13900004。原因HarmonyOS 的沙箱不仅有设备层面的空间限制还有更细粒度的配额管理尤其是应用缓存目录下的文件有上限。文档没说具体数值但实测超过 100MB 时触发概率很高。解法写文件前先用fileIo.statSync()检查目录已用空间超过配额限制时通知用户清理或者改用context.filesDir替代context.cacheDir因为缓存目录的配额通常更严格。最佳实践分级处理错误码不要全部 toast 给用户。磁盘满或权限问题用户能理解但“通用错误 13900001”要么是路径非法要么是 SDK 缺陷用户看到了也解决不了反而增加困惑。所有文件操作都放在 try-catch 里。不要觉得“写入缓存目录不会失败”实际的失败场景多到你想不到系统清理缓存、目录被删除、并发写入导致 FD 耗尽每一种都要捕获并降级处理。日志里永远带 code 和 message。只记录“文件写入失败”对排查问题毫无帮助必须把BusinessError.code和BusinessError.message一起打出来。不同版本的 Core File Kit 对错误码的描述可能微调只看数字更可靠。FAQQ为什么捕获到的异常对象不是 BusinessError 类型A部分异步操作比如write()的回调模式抛出的异常可能是普通 Error需要用instanceof判断然后手动转换 code 和 message。建议统一用error as BusinessError强转然后判断code是否在已知范围内。Q有的错误明明发生了为什么没走到 catch 里A检查是否用了异步函数但没有await。fileIo.openSync()是同步的但fileIo.open()是异步的如果写成了try { fileIo.open(...) }但不await异常会在 Promise 里被吞掉。除非你显式.catch()。Q真机上同一个错误码不同版本系统显示不一样A遇到过。HarmonyOS 4.0 和 4.1 对“文件被占用”返回的都是 13900007但 4.2 之后被拆分成了 13900007被占用和 13900008正在被写入。所以兜底逻辑一定要保留。