掌握 errorManager 全局异常兜底、学会崩溃栈符号化与智能聚类、搭建"捕获→聚类→定位→修复→验证"的崩溃治理闭环

---

一、前置思考：崩溃率是稳定性的"体温计"

1.1 崩溃的商业伤害

指标	影响
崩溃率 > 0.5%	商店审核关注、用户流失
一次崩溃	用户 30% 概率卸载
崩溃后重进	丢失操作上下文，体验断裂
崩溃差评	权重最高的差评类型

核心目标：崩溃率压到 0.1% 以下，且"每次崩溃都能定位修复"。

1.2 崩溃治理的完整闭环

发现(捕获上报) → 聚类(智能分组) → 定位(符号还原) → 修复(发版) → 验证(回归) → 复盘

闭环的价值：没有闭环的崩溃监控 = 只看到了问题，没有解决问题。

1.3 崩溃的两大来源

来源	示例	捕获手段
JS 异常	空指针/类型错误/越界	errorManager + 全局兜底
Native 崩溃	C++ 段错误/内存问题	FaultLogger + 系统日志
系统强杀	OOM/ANR	状态恢复 + 内存治理

---

二、核心原理：异常捕获机制

2.1 异常传播链

业务代码抛出异常
  ├─ 有 try/catch → 本地处理
  ├─ 无 try/catch → 向上传播
  │       ├─ 页面级兜底 → 捕获
  │       └─ 全局兜底 (errorManager) → 捕获 + 上报
  └─ 未捕获 → 崩溃 → FaultLogger 记录

关键认知：崩溃前有两次"兜底机会"——页面级与全局级。规范工程应在
全局注册兜底，保证任何未捕获异常都有记录、有上报。

2.2 崩溃 vs 卡顿 vs 无响应

类型	定义	记录
JS Crash	未捕获 JS 异常	FaultLogger JS_CRASH
Native Crash	C++ 崩溃	FaultLogger CPP_CRASH
App Freeze	应用无响应	FaultLogger APP_FREEZE
OOM	内存耗尽被杀	系统日志 + 内存监控

2.3 崩溃栈的价值

崩溃栈是"犯罪现场"：记录了崩溃发生的精确位置与调用路径。

TypeError: Cannot read properties of undefined (reading 'items')
    at OrderList.build (pages/Order/OrderList.ets:38:12)
    at createComponent (arkui:1:2345)
    at render (arkui:1:5678)

• 定位：pages/Order/OrderList.ets:38 行
• 原因：this.orders 为 undefined 时读取 .items
• 修复：判空或初始化

---

三、源码/API 深度解析

3.1 errorManager：全局异常回调

import { errorManager } from '@kit.AbilityKit';

// 注册全局 JS 异常回调
export function registerGlobalErrorHandler(): void {
  errorManager.on('error', {
    onUnhandledException(errMsg: string): void {
      // 1. 本地记录(环形缓冲)
      RingBuffer.push(errMsg);
      // 2. 异步上报(不阻塞崩溃流程)
      ReportCrash(errMsg, 'JS_UNCAUGHT');
      // 3. 可选: 用户提示/状态保存
    }
  });
}

注意：全局回调中不要做耗时操作（崩溃流程正在收尾），
只做"记录 + 异步上报 + 必要状态保存"。

3.2 全局异常兜底（错误边界）

ArkTS 中可对业务入口做兜底，避免单点异常拖垮整个页面：

// 页面级兜底: 渲染失败显示占位, 不闪退
try {
  this.renderList();
} catch (e) {
  // 记录 + 展示降级 UI
  this.showFallback();
  reportError(e);
}

3.3 FaultLogger 查询崩溃

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

// 查询所有类型崩溃
async function queryAllCrashes(): Promise<void> {
  const types = [
    faultLogger.FaultType.JS_CRASH,
    faultLogger.FaultType.CPP_CRASH,
    faultLogger.FaultType.APP_FREEZE
  ];
  for (const t of types) {
    const logs = await faultLogger.query(t, 20);
    for (const log of logs) {
      // log.id / log.reason / log.stack / log.summary
      UploadCrash(log);
    }
  }
}

3.4 符号表还原（Symbolication）

发布版开启混淆后，崩溃栈是混淆符号：

混淆栈:  at a.b (pages/ab.ets:12:3)   ← 不可读
还原栈:  at OrderList.build (pages/Order/OrderList.ets:38:12)  ← 可定位

还原机制：

1. 构建时保存混淆映射表（mapping 文件）；
2. 崩溃上报附带混淆栈 + 版本号；
3. 服务器端用对应版本的映射表还原；
4. 还原后的栈才能用于定位与聚类。

符号还原流程:
崩溃上报 {混淆栈, 版本1.3.2}
    │
    ▼
匹配版本1.3.2的 mapping 文件
    │
    ▼
还原: a.b → OrderList.build, pages/Order/OrderList.ets:38:12
    │
    ▼
聚类: 按还原栈指纹分组

3.5 智能聚类（Crash Grouping）

崩溃聚类的核心是堆栈指纹：

聚类维度	说明
栈指纹	前 N 帧 + 异常类型哈希
异常类型	TypeError / ReferenceError
页面	崩溃所在页面
版本	影响面评估
设备	机型相关问题

指纹示例：

指纹: hash(异常类型 + 栈前10帧)
分组: 
  A组: OrderList.build undefined.items  (38条, 覆盖1.3.0~1.3.2)
  B组: Login.submit token 为空          (12条, 仅1.3.2)
  C组: WebView.native 崩溃              (5条, 仅Mate60)

聚类价值：同栈崩溃合并为一单，按"影响面 × 频次"排序修复优先级。

---

四、企业级实战：崩溃监控平台

4.1 平台架构

客户端                          服务器
┌──────────────┐              ┌────────────────────┐
│ errorManager │              │ 崩溃接收服务        │
│ FaultLogger  │──上报──►     │ 符号还原引擎        │
│ 环形缓冲日志  │              │ 聚类引擎(指纹)      │
│ 版本/设备信息 │              │ 影响面计算          │
└──────────────┘              │ 看板/告警/工单      │
                              └────────────────────┘

4.2 上报协议设计

interface CrashReport {
  id: string;             // 崩溃ID
  type: string;           // JS_CRASH / CPP_CRASH / FREEZE
  reason: string;         // 崩溃原因
  stackObfuscated: string; // 混淆栈(原样)
  appVersion: string;     // 版本号
  osVersion: string;
  deviceModel: string;
  logContext: string[];   // 最近业务日志
  time: number;
  sessionId: string;      // 会话(用户轨迹)
}

4.3 崩溃治理优先级排序

优先级	判定	处理
P0	影响面 > 5% 或 频次暴增	当日修复热修
P1	影响面 1%~5%	本周修复
P2	影响面 < 1%	排期修复
P3	单机型/单版本偶发	观察

4.4 闭环流程落地

阶段	动作	工具
发现	崩溃率/新指纹告警	看板 + 告警
聚类	指纹分组 + 影响面	聚类引擎
定位	符号还原 + 业务日志	还原服务
修复	代码修复 + 单测	开发流程
验证	回归测试 + 灰度监控	CI + 灰度
复盘	归因 + 规范沉淀	评审会

---

五、排查与优化：崩溃率治理

5.1 崩溃率指标体系

指标	定义	目标
崩溃率	崩溃用户/活跃用户	< 0.1%
崩溃次数/千次启动	稳定度	< 0.5
无崩溃会话率	用户满意	> 99.5%
崩溃定位率	可定位占比	> 90%
修复时长	发现到修复	< 3 天

5.2 高频坑点速查

• 是否注册了全局异常兜底（errorManager）？
• 崩溃上报是否附带版本与设备信息？
• 混淆版本是否保存了 mapping 文件？
• 崩溃栈是否完成了符号还原？
• 聚类是否按栈指纹合并去重？
• 是否计算了影响面并排优先级？
• 崩溃是否联动业务日志上下文？
• 修复后是否验证了同栈不复发？
• OOM 是否有专项治理（第 32 篇联动）？
• 新版本是否对比了崩溃率回归？

5.3 崩溃治理收益

指标	治理前	治理后
崩溃率	0.62%	0.08%
崩溃定位率	35%	93%
平均修复时长	6 天	1.5 天
无崩溃会话率	98.2%	99.7%

---

六、总结与进阶

6.1 收益模型（参考实测）

指标	治理前	治理后	提升
崩溃率	0.62%	0.08%	-87%
崩溃定位率	35%	93%	166%
修复时长	6 天	1.5 天	-75%
卸载率（崩溃相关）	基准	-42%	商业收益

6.2 工程规范

1. 全局兜底必注册：errorManager 是标配；
2. mapping 归档：每个发布版本保存混淆映射表；
3. 聚类去重：崩溃平台按指纹合并；
4. P0 热修通道：高影响面崩溃快速响应；
5. 回归监控：新版本灰度期崩溃率对比（第 44 篇联动）。

6.3 进阶方向

• 崩溃重放：利用业务日志还原崩溃前操作路径（第 39 篇联动）；
• Native 崩溃治理：C++ 层内存安全（第 32/33 篇联动）；
• 状态恢复：崩溃重启后恢复用户上下文；
• 稳定性看板：崩溃率/无崩溃会话率纳入大盘（第 41 篇联动）。

---

附：Demo 演示说明

Tab	演示内容
🎣 异常捕获	errorManager 全局兜底捕获链路演示（捕获→记录→上报）
🧬 崩溃聚类	堆栈指纹聚类：多条崩溃按指纹分组 + 影响面排序
🔧 符号还原	混淆栈 vs 还原栈对照（mapping 映射演示）
🔄 闭环流程	发现→聚类→定位→修复→验证 五步闭环演示
📊 监控看板	崩溃率/TOP崩溃表/修复状态（模拟数据）