一、前置思考

1.1 为什么 90% 的 Bug 修复是失败的？

常见失败路径:
  → 没复现就猜原因 → 改了没验证 → 合入后问题复发
  → 复现了但没定位根因 → 打补丁掩盖症状 → 引出新 Bug

正确姿势: 复现 → 缩小 → 定位根因 → 修复 → 回归
  每个环节都要有"证据"，而不是"感觉"

1.2 Bug 定位的思维模型

分层缩小: 现象层 → 模块层 → 代码层 → 根因层

现象层: 用户报什么? (如: 相机偶发黑屏)
模块层: 哪个子系统? (Camera/图形/内存?)
代码层: 哪段逻辑?   (超时? 空指针? 状态机?)
根因层: 为什么?     (竞态? 生命周期? 协议不满足?)

每层都要用工具验证，而不是拍脑袋

二、核心原理

2.1 复现的艺术

复现三要素: 环境 + 步骤 + 频率

环境: 设备型号/系统版本/API Level/屏幕参数
步骤: 精确到每次点击、每个输入
频率: 必现 / 偶发(概率) / 条件触发(特定操作)

复现不了怎么办:
  → 采集现场日志 (bugreport / hilog)
  → 让用户录屏 (操作轨迹)
  → 扩大采样 (灰度用户埋点)
  → 环境矩阵 (不同版本交叉验证)

2.2 日志分析管线

崩溃类: faultlog → 栈回溯 → 符号化 → 定位崩溃点
卡顿类: trace 抓取 → 火焰图 → 主线程阻塞点
逻辑类: hilog 分级日志 → 关键路径埋点 → 时序还原

日志分析四问:
  1. 错误码是什么? (查错误码表)
  2. 调用链完整吗? (入口→出口)
  3. 数据状态对吗? (前置条件是否满足)
  4. 时间线合理吗? (时序是否有竞态)

2.3 gdb 调试内核/原生问题

gdb 关键命令:
  break / b      设置断点 (b func_name / b file.c:line)
  run / r        运行到断点
  bt             打印调用栈 (backtrace)
  print / p      打印变量 (p *ptr / p struct->field)
  next / n       单步跳过 (不进入函数)
  step / s       单步进入
  watch          监视变量变化
  info registers 查看寄存器

条件断点: b kernel/xxx.c:100 if task->pid == 1234

2.4 bisect 二分定位引入提交

场景: 功能在 v2.0 正常，v2.1 坏了，不知道哪次提交引入

git bisect 流程:
  git bisect start
  git bisect bad v2.1      # 坏版本
  git bisect good v2.0     # 好版本
  # Git 自动切到中间提交 → 编译测试 → 标记
  git bisect good / bad    # 重复直到定位
  git bisect reset

复杂度: 1000 次提交 → 只需 ~10 次二分

三、源码/API 深度解析

3.1 一个完整的 Bug 修复实战

# ===== 场景: ArkUI 列表滚动偶发白屏 =====
# 1. 复现: 环境 API 24 / 机型 P60 / 长列表快速滑动

# 2. 抓取崩溃现场
bugreport -v system > bug_20250401.txt
# 或
hdc shell hilog -x > crash.log

# 3. 查看 faultlog (崩溃栈)
hdc shell "ls /data/log/faultlog/faultlogger/"
hdc shell "cat /data/log/faultlog/faultlogger/20250401_xxx.log"
# 关键: 栈顶地址 → 符号化
# addr2line 还原行号
addr2line -f -e out/release/arm64/ohos.elf 0x0000000000x1234

# 4. 定位: 崩溃在列表复用池清理时访问已释放对象
#    LazyForEach cachedCount 边界条件下，item 被提前回收

# 5. 修复: 复用池加引用计数 + 清理前校验 inUse

# 6. 回归: 新增边界单测 + 100 次快速滑动压测

3.2 高效崩溃栈分析

Crash Type: NullPointerException
Reason:        Accessing a null object reference
Thread:        main (tid: 12345)
Stacktrace:
  at ohos.arkui.list.ListItemPool.release(ListOptimize.ets:98)   ← 崩溃点
  at ohos.arkui.list.ListScroller.onScrollStop(ListScroller.ets:210)
  at ohos.arkui.common.Scrollable.onScrollCallback(...)
  ...

分析:
  崩溃点 release() 访问了 null 的 item
  → 调用方 onScrollStop 在滚动停止时触发
  → 前置: 列表刚被清空/数据刷新，item 已置空
  → 根因: 滚动停止回调与数据刷新竞态

3.3 Bug 修复自检清单

□ 根因是否明确? (能用一句话说清"为什么")
□ 修复是否只针对根因? (不掩盖症状)
□ 是否覆盖了所有触发路径?
□ 是否新增了回归测试? (防止复发)
□ 是否验证了修复前的失败场景?
□ 是否评估了副作用? (性能/兼容/其他调用方)

四、企业级实战落地

4.1 Bug 处理流程与工具对照

阶段	动作	工具
复现	环境采集 + 步骤记录	真机/模拟器 + 录屏
采集	现场日志/崩溃栈	bugreport / hilog / faultlog
定位	栈回溯/火焰图/二分	addr2line / SmartPerf / git bisect
修复	根因修复 + 单测	代码 + 测试框架
验证	回归 + 压测	自动化测试 / 压力脚本
提交	补丁 + 关联 Issue	git commit -s + PR
归档	复盘 + 知识沉淀	故障文档 / 防回归用例

4.2 完整示例：Bug 排查流程演示

@Entry
@ComponentV2
struct IssueDebugDemo {
  @Local stage: string = '待开始';
  @Local suspicion: string[] = [];
  @Local logs: string[] = [];

  private runDebugFlow(): void {
    this.logs = [];
    this.stage = '复现';
    this.log('🐞 用户报障: 相机偶发黑屏 (API 24)');
    this.log('① 复现: 冷启动后立即打开相机, 3/10 次黑屏');
    this.log('② 采集: bugreport + hilog 抓取现场');

    this.stage = '定位';
    this.suspicion = [];
    this.log('③ 分析 faultlog: 崩溃在 CameraManager.onOpen');
    this.log('④ 看调用链: 打开相机与预览初始化竞态');
    this.log('   → 预览 Surface 尚未就绪就下发 StartPreview');
    this.log('⑤ 根因: 缺少 Surface 就绪回调等待');

    this.stage = '修复';
    this.log('⑥ 修复: onSurfaceReady 后再启动预览');
    this.log('⑦ 单测: 模拟 Surface 延迟就绪, 通过');
    this.log('⑧ 回归: 100 次冷启动相机, 0 次黑屏');

    this.stage = '归档';
    this.log('⑨ 提交 PR + 关联 Issue #4512');
    this.log('⑩ 复盘归档: 增加"异步就绪等待"检查项');
  }

  build() {
    Column({ space: 12 }) {
      Text('🔍 Bug 定位与修复演示').fontSize(20).fontWeight(FontWeight.Bold)
      Text('阶段: ' + this.stage).fontSize(13).fontColor('#D1242F')

      Row({ space: 8 }) {
        Button('▶ 模拟排查流程').layoutWeight(1).height(40).fontSize(12)
          .onClick(() => this.runDebugFlow())
        Button('清空').height(40).fontSize(12)
          .onClick(() => this.logs = [])
      }
      .width('100%')

      Scroll() {
        Column() {
          ForEach(this.logs, (l: string) => {
            Text(l).fontSize(11).lineHeight(18).fontColor('#24292F').width('100%')
          }, (l: string, i: number) => l + i)
        }.width('100%')
      }
      .layoutWeight(1).width('100%').scrollBar(BarState.Off)
    }
    .width('100%').height('100%').padding(16)
    .backgroundColor('#F6F8FA')
  }
}

4.3 疑难 Bug 排查清单

1. 先用工具取证，不要先猜原因
2. 一次只验证一个假设 (控制变量)
3. 偶发问题优先查竞态/生命周期/时序
4. 崩溃栈要符号化后看真实行号
5. 修复必须带回归测试，否则等于没修

五、问题排查与性能优化

问题	原因	解决
无法复现	环境/步骤不一致	采集现场日志 + 用户录屏
栈符号缺失	未做符号化	addr2line 还原行号
偶发崩溃	竞态条件	线程日志 + 时间线对齐分析
修复后复发	未覆盖触发路径	补全回归用例
二分耗时	编译时间长	增量编译 + 先缩小可疑提交范围
误修根因	症状当根因	向下追问"为什么"到不可再分

5.1 定位效率优化

1. 日志埋点前置: 关键路径加 HILOG_INFO，问题出现就有迹可循
2. 崩溃信息沉淀: 符号表随版本归档，随时可还原线上栈
3. 复用排查脚本: 现场采集一键化 (bugreport+hilog+trace)
4. 建立知识库: 常见错误码/模式沉淀为 wiki，新人直接查

六、高阶总结与最佳实践

1. 先复现后修复：不能复现的 Bug 无从谈起，环境+步骤+频率三要素先行。
2. 根因导向：每修一个 Bug 都要能回答"为什么"，而不是"症状消失了"。
3. 工具链是杠杆：faultlog 符号化、火焰图、git bisect 让定位从"猜"变"证"。
4. 回归即承诺：没有回归测试的修复，是给未来埋雷。
5. 复盘沉淀：每个 Bug 都是资产，归档成防回归用例和知识库。

一句话记住：Bug 修复的黄金链路是"复现 → 取证 → 定位根因 → 修复 → 回归"——每一步用工具和证据说话，杜绝拍脑袋，让每次修复都经得起复盘的检验。