HarmonyOS 崩溃账本实战：异常捕获、版本定位与复盘闭环

线上崩溃最怕只盯一条堆栈。单个堆栈能告诉你哪里抛错，却很难回答：哪个版本开始增多，哪些设备集中，是否和新功能有关，修复后趋势是否下降。要把崩溃真正管住，需要一份“崩溃账本”。

本文写一套适合 HarmonyOS 应用的崩溃账本方法：采集关键字段、归并同源问题、关联版本、推动修复和复盘。

1. 资料定位：崩溃排查不能只看堆栈顶部

HarmonyOS 应用排查崩溃时，常见证据来自设备日志、故障日志、业务 HiLog、版本发布记录和用户反馈。堆栈顶部只是一部分，账本要把运行环境也记录下来。

信息来源	记录内容	价值
故障日志	异常类型、线程、堆栈	判断直接崩溃点
业务日志	traceId、页面、动作	还原用户路径
发布记录	versionName、buildNo	判断版本引入
设备信息	deviceType、系统版本	判断设备集中度
修复记录	owner、commit、用例	形成闭环

版本边界建议写清楚：本文偏应用侧账本设计，不替代系统底层故障分析；Native 崩溃、三方 SDK 崩溃和 ArkTS 逻辑异常要分开归因。

2. 闭环流程：从异常到关闭标准

崩溃处理要有固定节奏：发现、归并、定责、修复、回归、观察、关闭。少了“观察”，就不知道修复是否真的有效；少了“归并”，同一个问题会被拆成十几个任务。

export type CrashStatus = 'new' | 'triaging' | 'fixed' | 'observing' | 'closed'

export interface CrashTicket {
  id: string
  stackHash: string
  versionName: string
  deviceType: string
  abilityName: string
  status: CrashStatus
  owner?: string
}

CrashTicket 的边界是问题单，不是原始日志。它信任采集层给出的 stackHash 和版本字段，预防同源问题重复流转。下一层会补充归因、修复和关闭条件。

3. 数据结构：账本字段要服务复盘

账本字段不要只为了好看。每个字段都要能回答一个排查问题：是否同源、谁负责、哪版引入、如何复现、修复是否回归。

export interface CrashLedgerItem {
  ticket: CrashTicket
  firstSeenAt: number
  lastSeenAt: number
  count: number
  rootCause?: string
  fixCommit?: string
  reproduceSteps?: string[]
  regressionCase?: string
}

这段结构拥有崩溃复盘的主体信息。count 和时间用于趋势判断，rootCause 和 fixCommit 用于追责闭环，regressionCase 用于防止同类问题再次出现。

4. 生成 stackHash：归并同源问题

如果直接用完整堆栈做 key，行号变化、混淆差异、异步包装都可能导致同一崩溃被拆散。可以先取关键帧，生成稳定的 hash。

export function buildStackHash(stack: string): string {
  const keyFrames = stack
    .split('\n')
    .map(line => line.trim())
    .filter(line => line.includes('.ets:') || line.includes('.ts:'))
    .slice(0, 5)
    .join('|')
  let hash = 0
  for (let i = 0; i < keyFrames.length; i++) {
    hash = (hash * 31 + keyFrames.charCodeAt(i)) >>> 0
  }
  return hash.toString(16)
}

这个函数负责同源归并。它不保证密码学安全，只保证同类堆栈更容易聚到一起。输入是原始堆栈，输出是账本 key；下一层可以结合异常类型和模块名再二次归并。

5. 捕获业务上下文：堆栈之外还要有页面动作

很多崩溃只看堆栈会误判。例如空对象出现在 ViewModel，但真正原因是上一页传参缺字段。账本里要保留页面、动作、traceId 和关键业务状态。

export interface CrashContext {
  traceId: string
  page: string
  action: string
  userState: 'guest' | 'login' | 'expired'
  network: 'wifi' | 'cellular' | 'offline' | 'unknown'
}

export class CrashContextHolder {
  private static current?: CrashContext

  static update(context: CrashContext): void {
    this.current = context
  }

  static snapshot(): CrashContext | undefined {
    return this.current
  }
}

CrashContextHolder 只保存轻量上下文，不能保存页面对象或大数据。它预防“只有堆栈没有场景”的问题；如果和内存治理冲突，应优先保证不持有 UI 引用。

6. 账本入库：先去重，再更新趋势

同一个崩溃如果每次都新建记录，会让处理列表失真。入库逻辑应该按 stackHash、版本、模块归并，更新次数和最后出现时间。

export class CrashLedger {
  private readonly items: CrashLedgerItem[] = []

  upsert(ticket: CrashTicket): CrashLedgerItem {
    const existed = this.items.find(item =>
      item.ticket.stackHash === ticket.stackHash &&
      item.ticket.versionName === ticket.versionName &&
      item.ticket.abilityName === ticket.abilityName)

    if (existed) {
      existed.count += 1
      existed.lastSeenAt = Date.now()
      return existed
    }

    const item: CrashLedgerItem = {
      ticket,
      firstSeenAt: Date.now(),
      lastSeenAt: Date.now(),
      count: 1
    }
    this.items.push(item)
    return item
  }
}

这段代码拥有账本更新边界。它信任 ticket 的归因字段，但不信任每次崩溃都是新问题。它防止任务膨胀，也为后续 Top Crash 排序提供数据。

7. 版本定位：看哪一版开始抬升

修复崩溃时，版本维度比单次堆栈更重要。某个问题如果只在新版本出现，优先看新功能、配置开关、接口协议和数据迁移。

现象	判断方向	处理策略
新版本突然增多	新代码引入	对比发布 diff
只在旧版本出现	已修复未覆盖	引导升级
某设备集中	适配问题	补设备专项回归
某入口集中	参数或状态问题	加入口校验

export interface VersionCrashStat {
  versionName: string
  crashCount: number
  activeUsers: number
}

export function crashRate(stat: VersionCrashStat): number {
  if (stat.activeUsers === 0) return 0
  return stat.crashCount / stat.activeUsers
}

这里用比例而不是绝对次数判断趋势。小流量灰度包只看次数可能不明显，按活跃用户归一化后更容易发现风险。

8. 修复策略：不要只补空判断

空指针、数组越界、状态异常经常可以用保护代码压住，但真正的根因可能是数据契约不稳定。修复时要同时处理入口校验、状态兜底和回归用例。

export interface RoutePayload {
  orderId?: string
  source?: string
}

export function normalizeOrderPayload(payload: RoutePayload): { orderId: string; source: string } {
  if (!payload.orderId || payload.orderId.length < 6) {
    throw new Error('订单入口缺少合法 orderId')
  }
  return {
    orderId: payload.orderId,
    source: payload.source ?? 'unknown'
  }
}

这段代码的边界是入口参数契约。它不让非法数据继续进入页面和 ViewModel，预防后续在深层逻辑里崩溃。下一层应该把错误转成用户可理解提示，而不是让异常冒泡到页面渲染。

9. 回归用例：每个关闭的问题都要留下用例

崩溃修复如果没有回归用例，后续很容易在重构或迁移时复发。账本里至少记录一个可执行的验证点。

export interface CrashRegressionCase {
  name: string
  steps: string[]
  expected: string
}

export const orderPayloadRegression: CrashRegressionCase = {
  name: '订单详情入口缺少 orderId 时不崩溃',
  steps: ['打开消息页', '点击缺少 orderId 的订单消息', '观察页面反馈'],
  expected: '页面展示参数异常提示，并返回消息列表'
}

用例描述要面向复现，不要只写“验证通过”。它的输入是历史崩溃场景，输出是可回放步骤，防止同类入口再次漏校验。

10. 常见问题排查表

现象	可能原因	优先动作	关闭条件
堆栈相同但版本不同	同源问题跨版本	按 stackHash 合并	新旧版本策略清楚
只在某设备崩溃	设备适配差异	补设备矩阵	目标设备复测通过
修复后仍有新增	根因没断	看入口和数据契约	趋势连续下降
没法复现	上下文缺失	补 traceId 和页面动作	下次出现能还原
任务长期不关	没有关闭标准	写观察窗口	达到窗口后关闭

排查崩溃要避免“谁看到谁修”。账本把 owner、模块、根因、修复提交和观察窗口写清楚，团队才能知道问题走到哪一步。

11. 发布观察与验收清单

验收项	标准
归并准确	Top Crash 没有明显重复
版本定位清楚	知道哪版开始出现
修复有证据	commit、用例、复测结果齐全
趋势可观察	修复后同源问题下降
关闭有窗口	至少经过一个观察周期

如果修复当天就关闭问题，风险很高。建议按灰度节奏观察：灰度用户稳定后再扩大范围，扩大后仍无抬升，再关闭账本项。

观察窗口可以写成一个明确规则，避免“感觉差不多了”就结束。下面这个例子把同源崩溃的新增次数和观察天数放在一起判断。

export interface CrashObserveWindow {
  days: number
  sameStackNewCount: number
  grayUsers: number
}

export function canCloseCrash(item: CrashObserveWindow): boolean {
  if (item.days < 3) return false
  if (item.grayUsers < 1000) return false
  return item.sameStackNewCount === 0
}

这段规则拥有问题关闭边界。它信任账本统计出的同源新增数量，但不让团队在观察天数和灰度用户不足时提前关闭。这样崩溃治理才从“修完代码”延伸到“线上趋势稳定”。

崩溃关闭复现场景：给读者一组可执行核验

崩溃账本要验证修复后观察窗口。堆栈修掉不代表问题关闭，同源新增为零并经过灰度观察才算稳定。

核验维度	读者需要准备的证据
输入	页面入口、用户动作、关键参数
过程	日志、状态变化、异常分支
输出	UI 表现、回调结果、持久化结果
回归	同场景重复执行后的结果

interface CrashReplayCase {
  stackHash: any
  fixedVersion: any
  observeDays: any
  sameStackNewCount: any
}

const replay93: CrashReplayCase = {
  stackHash: 'sample',
  fixedVersion: 'sample',
  observeDays: 'sample',
  sameStackNewCount: 'sample',
}

function assertReplay93(item: CrashReplayCase): void {
  if (item.observeDays < 3 && item.sameStackNewCount === 0) throw new Error('观察窗口不足，不能关闭崩溃项')
}

这组核验把崩溃修复和观察窗口绑定，防止堆栈刚消失就过早关闭问题。

崩溃观察回放表：把文章方法变成可复现动作

崩溃账本要补观察期。建议修复后至少记录灰度用户数、同源新增数、版本分布和关闭时间，避免堆栈刚消失就结束。

回放动作	核验方式
灰度用户数	准备输入、执行操作、记录结果、给出结论
同源新增数	准备输入、执行操作、记录结果、给出结论
版本分布	准备输入、执行操作、记录结果、给出结论
关闭时间	准备输入、执行操作、记录结果、给出结论

崩溃账本要强调关闭条件。读者可以把修复版本、灰度用户数、同源新增数和观察天数写进账本，只有观察窗口足够且同源新增归零，才关闭问题。这样每次崩溃修复都会留下可复用的经验，而不是只处理当前堆栈。

崩溃复盘的落地边界：不要把边界留给读者猜

崩溃账本的目标不是记录事故数量，而是沉淀下一次不再发生的方法。每个关闭项都应该有根因、修复提交、回归用例和观察窗口。读者按这个边界执行，崩溃处理就会从救火变成工程资产。

落地项	处理要求
根因必须可解释	需要有明确输入、处理边界和失败兜底
修复提交可追溯	需要有明确输入、处理边界和失败兜底
回归用例可执行	需要有明确输入、处理边界和失败兜底
观察窗口可量化	需要有明确输入、处理边界和失败兜底

这类边界写清楚后，读者不需要猜哪些逻辑属于页面、哪些属于服务、哪些属于发布前验收。文章的价值也会从“讲了一个功能”变成“给了一套可迁移的工程判断”。

12. 小结：崩溃治理要从任务变成账本

崩溃不是修掉一条堆栈就结束。真正可持续的方式，是把异常类型、堆栈摘要、版本、设备、页面动作、根因、修复和观察结果写进同一份账本。这样每次线上事故都会沉淀成下一次的防线，而不是反复从零开始排查。