在这里插入图片描述

你是不是也在想——“鸿蒙这么火,我能不能学会?”
答案是:当然可以!
这个专栏专为零基础小白设计,不需要编程基础,也不需要懂原理、背术语。我们会用最通俗易懂的语言、最贴近生活的案例,手把手带你从安装开发工具开始,一步步学会开发自己的鸿蒙应用。
不管你是学生、上班族、打算转行,还是单纯对技术感兴趣,只要你愿意花一点时间,就能在这里搞懂鸿蒙开发,并做出属于自己的App!
📌 关注本专栏《零基础学鸿蒙开发》,一起变强!
每一节内容我都会持续更新,配图+代码+解释全都有,欢迎点个关注,不走丢,我是小白酷爱学习,我们一起上路 🚀

前言

应用崩溃有 Crash 日志,逻辑出错有异常堆栈,但还有一类问题最难定位——页面没崩,就是不动了。用户点什么都没反应,系统弹出"应用无响应"提示,或者直接把应用杀掉。这类问题在 HarmonyOS 里有一个专门的机制来记录:AppFreeze。

这篇文章做一件具体的事:先写一个会阻塞主线程的最小示例,让 AppFreeze 真实触发,然后通过 hiAppEvent 订阅卡死事件,把日志拿出来,逐字段看懂它。

适合第一次接触 AppFreeze 机制的开发者。

一、AppFreeze 解决什么问题

HarmonyOS 的 AppFreeze 是系统级的应用无响应监测机制。它和 Crash 不同:Crash 是应用异常终止,有完整的异常信息;AppFreeze 是应用进程还活着,但主线程长时间没有响应事件调度或输入事件,系统判定应用已经"冻结"。

官方文档将 AppFreeze 的常见触发原因归为两大类:

  • THREAD_BLOCK:主线程执行任务时被阻塞,超过规定时间没有恢复响应。
  • INPUT_BLOCK:用户输入事件(如触摸)长时间未被主线程处理。

这两类原因背后,往往是同一个根因:主线程上执行了耗时操作。同步网络请求、大文件读写、长耗时计算,只要放在主线程里跑,都可能触发 AppFreeze。

AppFreeze 触发后,系统会生成一份结构化日志,记录进程信息、触发原因、发生时间、前后台状态,以及主线程的调用栈。读懂这份日志,是定位卡死问题的起点。

二、先把机制弄清楚

2.1 AppFreeze 日志从哪里来

HarmonyOS 提供了两个入口来获取 AppFreeze 日志:

入口一:hiAppEvent 事件订阅

hiAppEvent 是 HarmonyOS 提供的应用事件打点和订阅框架(@ohos.hiviewdfx.hiAppEvent)。系统预定义了一系列系统事件,AppFreeze 对应的是卡死事件(freeze event)。通过 hiAppEvent.addWatcher 注册监听器,当本应用触发 AppFreeze 时,回调会被触发,可以在回调里读取事件参数。

入口二:faultLogger 查询

faultLogger(@ohos.faultLogger)提供了查询历史故障日志的能力,FaultType.APP_FREEZE 对应卡死类型。通过 faultLogger.querySync 或 faultLogger.query 可以拿到 FaultLogInfo 数组,每条记录包含 content 字段,里面是完整的日志文本。

这篇文章以 hiAppEvent 订阅 为主要演示方式,faultLogger 在第五节补充说明。

2.2 API Level 和版本要求

能力模块支持起始版本
hiAppEvent 事件订阅@ohos.hiviewdfx.hiAppEventAPI 9(Stage 模型)
faultLogger 查询@ohos.faultLoggerAPI 8
AppFreeze 系统监测机制系统内置HarmonyOS 3.1 及以上

以上均适用于 HarmonyOS 7 对应的 API Level 环境。工程必须使用 Stage 模型,UIAbility 生命周期下使用。

2.3 权限要求

hiAppEvent 订阅本应用自身的系统事件(包括 freeze),不需要额外声明权限。

faultLogger 查询本应用自身的故障日志,也不需要额外权限。

如果尝试查询其他应用的日志,则需要系统权限,三方应用无法使用。

三、搭一个能触发 AppFreeze 的最小实验

目标很简单:写一个按钮,点击后在主线程执行一段足够长的同步阻塞,让系统检测到主线程无响应,从而生成 AppFreeze 日志。

同时,在应用启动时注册 hiAppEvent 监听器,当 freeze 事件触发后,把关键字段打印到 HiLog。

工程结构只需要两个文件:

  • EntryAbility.ets:在 onCreate 里注册 hiAppEvent watcher
  • Index.ets:提供触发阻塞的按钮

3.1 注册 hiAppEvent Watcher

// EntryAbility.ets
import { UIAbility, Want, AbilityConstant } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import hiAppEvent from '@ohos.hiviewdfx.hiAppEvent';

const TAG = 'AppFreezeDemo';
const DOMAIN = 0xFF00;

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // 注册系统事件监听器,订阅本应用的 freeze 事件
    hiAppEvent.addWatcher({
      name: 'freeze_watcher',
      appEventFilters: [
        {
          domain: hiAppEvent.domain.OS,
          eventTypes: [hiAppEvent.EventType.FAULT]
        }
      ],
      onReceive: (domain: string, appEventGroups: Array<hiAppEvent.AppEventGroup>) => {
        hilog.info(DOMAIN, TAG, '=== AppFreeze Event Received ===');
        for (const group of appEventGroups) {
          for (const event of group.appEventInfos) {
            hilog.info(DOMAIN, TAG, `Event Name: ${event.name}`);
            hilog.info(DOMAIN, TAG, `Params: ${JSON.stringify(event.params)}`);
          }
        }
      }
    });
  }

  onDestroy(): void {
    // 应用退出时移除监听器,避免泄漏
    hiAppEvent.removeWatcher({ name: 'freeze_watcher' });
  }
}

这段代码解决的问题:在应用生命周期里注册一个持久监听器,当系统检测到本应用发生 freeze 事件时,onReceive 会被回调,event.params 里包含日志的关键字段。

真正需要关注的地方:appEventFilters 的 domain 使用 hiAppEvent.domain.OS,订阅的是操作系统预定义事件域;eventTypes 指定 FAULT 类型,这会覆盖 freeze 和 crash 两类故障事件。如果只想订阅 freeze,可以在 onReceive 里通过 event.name 过滤。

3.2 触发主线程阻塞的按钮

// Index.ets
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG = 'AppFreezeDemo';
const DOMAIN = 0xFF00;

@Entry
@Component
struct Index {
  @State statusText: string = '点击按钮触发主线程阻塞';

  // 在主线程执行同步忙等,模拟耗时操作
  blockMainThread(durationMs: number): void {
    const start = Date.now();
    // 纯 CPU 忙等,不释放主线程
    while (Date.now() - start < durationMs) {
      // intentionally empty
    }
    hilog.info(DOMAIN, TAG, `主线程阻塞 ${durationMs}ms 结束`);
  }

  build() {
    Column({ space: 24 }) {
      Text(this.statusText)
        .fontSize(16)
        .textAlign(TextAlign.Center)
        .padding(16)

      Button('阻塞主线程 10 秒')
        .width('80%')
        .onClick(() => {
          this.statusText = '主线程阻塞中,界面无响应...';
          // 直接在主线程同步阻塞 10000ms
          // 注意:这是故意触发 AppFreeze 的实验写法,不是正常代码
          this.blockMainThread(10000);
          this.statusText = '阻塞结束';
        })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

这段代码做的事很直接:点击按钮后,blockMainThread 在主线程上用忙等循环占用 CPU 10 秒。这段时间内,主线程无法处理任何 UI 更新或输入事件,系统会检测到 THREAD_BLOCK 类型的 freeze。

真正需要关注的地方:this.statusText = '主线程阻塞中...' 这行赋值在阻塞开始前执行,但由于主线程立刻进入 blockMainThread,UI 刷新不会发生——页面上看到的文字实际上要等阻塞结束才会更新,或者根本不会更新(如果系统在此期间杀掉了应用)。这个现象本身就是 AppFreeze 的典型表现。

四、读懂 AppFreeze 日志里的关键字段

触发后,日志会通过 onReceive 回调送达,或者通过 faultLogger 查询拿到。日志内容以文本形式存储在 event.params 或 FaultLogInfo.content 中。

官方文档中描述的 AppFreeze 日志包含以下核心字段,定位问题时主要看这几个:

4.1 Pid

进程 ID。用来确认这份日志确实属于你的应用进程,不是其他进程产生的。在多进程架构下,不同 Ability 可能跑在不同进程,Pid 帮你区分是哪个进程卡住了。

4.2 Reason

触发 AppFreeze 的原因类型。常见值:

Reason 值含义
THREAD_BLOCK_6S主线程被阻塞超过 6 秒
THREAD_BLOCK_3S主线程被阻塞超过 3 秒(部分场景,轻度告警)
INPUT_BLOCK用户输入事件超时未被处理
APP_LIFECYCLE_TIMEOUT应用生命周期回调(如 onForeground)超时

这个字段是最先应该看的。THREAD_BLOCK_6S 说明主线程执行任务阻塞;INPUT_BLOCK 说明主线程处理输入事件阻塞——两者都指向主线程,但触发路径不同。

4.3 Fault time

AppFreeze 发生的时间戳,精确到毫秒。结合你的业务日志,可以反推当时正在执行哪个操作,缩小排查范围。比如对比 HiLog 里的业务打点时间,找到"是在进入某个页面之后 N 秒触发的"这类关联。

4.4 Foreground

标记应用触发 AppFreeze 时是否处于前台。值为 true 时表示应用在前台运行时卡死,这类问题用户感知最强烈;值为 false 时表示应用在后台发生了 freeze,系统同样会检测记录,但用户不一定直接看到。

这个字段对优先级判断很有用:前台 freeze 是高优问题,后台 freeze 可以结合业务场景评估。

4.5 Stack

主线程在 freeze 发生时的调用栈。这是整份日志里含金量最高的部分。

调用栈从栈顶往下读,栈顶是当时正在执行的代码位置。定位主线程阻塞时,重点看:

  • 是否有 while 或 for 死循环的迹象(帧深度浅但一直重复)
  • 是否卡在某个同步 I/O 调用
  • 是否卡在某个加锁等待
  • 是否卡在第三方库的某个同步操作

通过 DevEco Studio 的符号表,可以把原始地址反解析为可读的函数名和行号。

五、用 faultLogger 也能拿到这份日志

除了订阅事件,也可以在下次启动时通过 faultLogger 主动查询上一次的 AppFreeze 记录:

import faultLogger from '@ohos.faultLogger';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG = 'AppFreezeDemo';
const DOMAIN = 0xFF00;

function queryLastFreezeLogs(): void {
  try {
    // querySync 返回 FaultLogInfo 数组,FaultType.APP_FREEZE 对应卡死类型
    const logs = faultLogger.querySync(faultLogger.FaultType.APP_FREEZE);
    if (logs.length === 0) {
      hilog.info(DOMAIN, TAG, '没有查到 APP_FREEZE 日志');
      return;
    }
    for (const log of logs) {
      hilog.info(DOMAIN, TAG, `--- APP_FREEZE Log ---`);
      hilog.info(DOMAIN, TAG, `pid: ${log.pid}`);
      hilog.info(DOMAIN, TAG, `timestamp: ${log.timestamp}`);
      // content 字段包含完整日志文本,包括 Reason、Fault time、Stack 等
      hilog.info(DOMAIN, TAG, `content: ${log.content}`);
    }
  } catch (err) {
    hilog.error(DOMAIN, TAG, `querySync failed: ${JSON.stringify(err)}`);
  }
}

FaultLogInfo 的 content 字段是一整块文本,包含 Reason、Fault time、Stack 等所有字段,格式与系统日志一致。log.pid 和 log.timestamp 在结构体层面单独提供,方便过滤。

这里有一个常见的理解偏差:querySync 返回的是当前用户的本应用日志,不会返回其他应用的日志,也不能跨用户查询。每次查询返回的是系统保留的最近若干条记录,不保证包含所有历史日志。

六、几个容易踩错的地方

1. 阻塞主线程不等于崩溃,不能靠 try-catch 捕获

AppFreeze 不会抛出任何异常。主线程阻塞时,整个 ArkTS 运行时就是卡在那里执行,没有异常可以捕获。这是开发者最容易忽略的地方:加了 try-catch 不代表卡死问题被"处理了"。

2. 生命周期回调也是主线程,超时同样触发 AppFreeze

onForeground、onBackground、onWindowStageCreate 这些回调都在主线程上执行。如果在这里做了同步网络请求或者大量 I/O,APP_LIFECYCLE_TIMEOUT 类型的 AppFreeze 同样会触发。这类问题特别容易在冷启动阶段发生。

3. hiAppEvent 的 watcher 需要在 onDestroy 里移除

addWatcher 注册的监听器如果不在 onDestroy 里调用 removeWatcher 移除,可能导致重复注册(下次启动时再 addWatcher 同一个 name 会报错)。建议用固定的 name 字符串,并在 onDestroy 配套移除。

4. Stack 里的地址需要符号化才可读

原始 AppFreeze 日志里的调用栈是内存地址形式,直接看是一串十六进制数字,没有意义。需要在 DevEco Studio 里使用符号表(.sym 文件)对地址进行反解析,才能看到具体的函数名和代码行号。如果 release 包没有保留符号表,Stack 就无法还原。

5. 阻塞时间阈值以系统检测为准

THREAD_BLOCK_6S 中的"6S"是系统检测阈值的参考值,实际触发时间可能因设备负载、系统版本有所差异。不要在业务代码里写"只要我的操作在 5 秒内结束就安全"这类假设——耗时操作应该一律放到异步线程,不论耗时长短。

七、排查 AppFreeze 的顺序

拿到日志之后,按这个顺序往下查效率最高:

  1. 看 Reason:先确认是 THREAD_BLOCK 还是 INPUT_BLOCK,前者找主线程执行路径,后者找事件分发链路。
  2. 看 Foreground:前台发生的问题优先处理,后台 freeze 结合业务逻辑判断必要性。
  3. 看 Fault time:对照业务日志(HiLog 打点),定位"是哪个操作触发的"。
  4. 看 Pid:多进程应用确认是哪个进程,单进程应用可以跳过。
  5. 看 Stack:符号化之后,从栈顶往下找第一个属于你自己业务代码的帧,那就是阻塞的入口。
  6. 找到根因后:将耗时操作移出主线程,用 taskpool 或 worker 执行,或改为异步接口。

如果 Stack 里看不到自己的业务代码,全是系统框架帧,可能是系统锁等待或者第三方库的同步操作,这种情况可以结合 DevEco Studio 的 Profiler 进一步分析。

开发经验总结

AppFreeze 和 Crash 的本质差别在于进程状态——Crash 是死了,AppFreeze 是卡住了。正因为进程还活着,日志里有完整的调用栈,定位反而比 Crash 更直接。

读日志的顺序不复杂:先看 Reason 确认类型,看 Foreground 确认优先级,看 Fault time 缩小时间范围,最后把 Stack 符号化找到阻塞入口。这个流程走一遍,大部分主线程卡死的根因都能定位出来。

真正难在事后的修复判断:发现是某个数据库操作在主线程上跑,改成异步很直接;但如果是某个三方库内部做了同步等待,就需要评估是否可以换接口,或者通过 Worker 把整块逻辑隔离出去。

如果你的应用也有偶发卡死但没法稳定复现,可以先把 hiAppEvent 的 freeze 订阅加进去,让它在后台默默收集,积累几次触发记录之后再看 Stack——往往比单靠猜测要快很多。

❤️ 如果本文帮到了你…

  • 请点个赞,让我知道你还在坚持阅读技术长文!
  • 请收藏本文,因为你以后一定还会用上!
  • 如果你在学习过程中遇到bug,请留言,我帮你踩坑!
Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐