鸿蒙三方库 | harmony-utils之CrashUtil全局异常捕获详解

前言

全局异常捕获是应用稳定性保障的重要手段，可以防止应用因未处理的异常而崩溃，同时收集异常信息用于问题排查。@pura/harmony-utils 的 CrashUtil 封装了全局异常捕获方法。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、CrashUtil核心API

CrashUtil 提供了以下全局异常捕获方法：

方法	说明	参数	使用场景
`setCrashHandler(callback)`	设置全局异常处理器	callback	异常捕获
`getCrashLog()`	获取崩溃日志	无	问题排查

1.1 核心特性

简洁易用：封装复杂API为一行调用，降低使用门槛
类型安全：完整的TypeScript类型定义，编译期即可发现错误
异常处理：内置异常捕获机制，避免运行时崩溃
日志收集：支持崩溃日志的收集和查询

1.2 异常处理策略

策略	说明	适用场景
全局捕获	捕获所有未处理异常	应用稳定性保障
日志记录	记录异常堆栈信息	问题排查
用户提示	友好提示用户	用户体验

二、完整使用步骤

2.1 安装依赖

bash 复制代码

ohpm install @pura/harmony-utils

2.2 设置全局异常捕获

typescript 复制代码

import { CrashUtil } from '@pura/harmony-utils';

aboutToAppear() {
  CrashUtil.setCrashHandler((error) => {
    console.error('全局异常捕获:', error.message);
    this.result = `捕获异常: ${error.message}`;
  });
}

2.3 获取崩溃日志

typescript 复制代码

Button('获取崩溃日志')
  .width('100%')
  .onClick(() => {
    try {
      let log = CrashUtil.getCrashLog();
      this.result = `崩溃日志:\n${log || '无崩溃记录 ✅'}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

typescript 复制代码

import { CrashUtil } from '@pura/harmony-utils';

@Entry
@Component
struct CrashDemo {
  @State result: string = '';

  aboutToAppear() {
    CrashUtil.setCrashHandler((error) => {
      this.result = `捕获异常: ${error.message}`;
    });
  }

  build() {
    Column({ space: 12 }) {
      Button('设置异常捕获').width('100%').onClick(() => {
        this.result = '全局异常捕获已设置 ✅';
      });
      Button('获取崩溃日志').width('100%').onClick(() => {
        let log = CrashUtil.getCrashLog();
        this.result = log || '无崩溃记录';
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 异常上报

typescript 复制代码

import { CrashUtil, LogUtil } from '@pura/harmony-utils';

CrashUtil.setCrashHandler((error) => {
  LogUtil.error('CrashReport', `异常: ${error.message}`);
  uploadCrashReport({
    message: error.message,
    stack: error.stack,
    timestamp: Date.now(),
    deviceInfo: DeviceUtil.getDeviceModel()
  });
});

4.2 异常恢复

typescript 复制代码

CrashUtil.setCrashHandler((error) => {
  LogUtil.error('CrashHandler', error.message);
  let crashLog = CrashUtil.getCrashLog();
  PreferencesUtil.putString('last_crash', crashLog);
  ToastUtil.showToast('应用遇到异常，已自动恢复');
});

五、注意事项

设置时机：建议在应用启动时设置异常处理器
异常类型：只能捕获JS层异常，原生层崩溃需其他方案
日志大小：崩溃日志可能较大，建议定期清理
初始化依赖 ：使用前需确保 AppUtil.init() 已调用
隐私保护：异常日志中不要包含用户敏感信息

六、常见问题

Q1: setCrashHandler()后仍崩溃？

CrashUtil捕获的是JS层异常，原生层崩溃无法捕获。

Q2: getCrashLog()返回空？

可能是应用从未崩溃过，或崩溃日志已被清理。

Q3: 如何将崩溃日志发送给开发者？

可以在异常回调中将日志上传到服务器，或引导用户通过邮件发送。

Q4: 异常处理器可以设置多个吗？

只能设置一个异常处理器，后设置的会覆盖前面的。

总结

CrashUtil 的全局异常捕获方法为应用稳定性提供了重要保障。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。合理使用异常捕获，可以提升应用的用户体验和问题排查效率。

本文基于 @pura/harmony-utils 工具库，更多功能请参考官方文档与后续系列文章。