HarmonyOS 日志、崩溃分析与调试实战：从问题定位到线上治理

在 HarmonyOS 应用开发中，日志记录、崩溃分析和调试能力是保障应用质量的基础设施。本文从日志框架、崩溃捕获、调试工具到线上治理，构建完整的问题定位与修复闭环。

一、日志框架与分级策略

1.1 HiLog 基础

HarmonyOS 提供 hilog 模块作为统一日志框架：

import hilog from '@ohos.hilog';

const DOMAIN = 0x0001; // 自定义域
const TAG = 'MyApp';

// 日志级别：DEBUG < INFO < WARN < ERROR < FATAL
hilog.debug(DOMAIN, TAG, '调试信息：%{public}s', 'value');
hilog.info(DOMAIN, TAG, '普通信息');
hilog.warn(DOMAIN, TAG, '警告：%{public}d', count);
hilog.error(DOMAIN, TAG, '错误：%{public}s', error.message);

关键点：

• %{public}s 和 %{public}d 用于格式化输出，默认参数在 Release 包中不会打印（需显式标记 public）
• DOMAIN 用于区分模块，范围 0x0000 ~ 0xFFFF
• 日志级别可通过设备配置动态调整

1.2 日志封装与分环境控制

// logger.ets
import hilog from '@ohos.hilog';

const DOMAIN = 0x1001;

export class Logger {
   
  private tag: string;
  private isDebug: boolean = false; // 从构建配置读取

  constructor(tag: string) {
   
    this.tag = tag;
  }

  debug(format: string, ...args: any[]) {
   
    if (this.isDebug) {
   
      hilog.debug(DOMAIN, this.tag, format, ...args);
    }
  }

  info(format: string, ...args: any[]) {
   
    hilog.info(DOMAIN, this.tag, format, ...args);
  }

  warn(format: string, ...args: any[]) {
   
    hilog.warn(DOMAIN, this.tag, format, ...args);
  }

  error(format: string, ...args: any[]) {
   
    hilog.error(DOMAIN, this.tag, format, ...args);
  }

  // 带错误栈的日志
  logError(message: string, error: Error) {
   
    hilog.error(DOMAIN, this.tag, '%{public}s: %{public}s\nStack: %{public}s',
      message, error.message, error.stack);
  }
}

// 使用
const logger = new Logger('NetworkModule');
logger.info('请求开始：%{public}s', url);

二、崩溃捕获与上报

2.1 ErrorManager 注册全局错误监听

// EntryAbility.ets
import errorManager from '@ohos.app.ability.errorManager';
import hilog from '@ohos.hilog';

export default class EntryAbility extends UIAbility {
   
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
   
    // 注册全局错误监听
    errorManager.on('error', {
   
      onUnhandledException: (errMsg: string) => {
   
        hilog.error(0x0001, 'CrashHandler', 'Unhandled exception: %{public}s', errMsg);
        this.uploadCrashLog(errMsg);
      }
    });
  }

  private uploadCrashLog(errMsg: string) {
   
    // 上报到服务器或本地持久化
    try {
   
      // 示例：保存到沙箱文件
      const context = this.context;
      const filePath = `${
     context.filesDir}/crash_${
     Date.now()}.log`;
      fs.writeTextSync(filePath, errMsg);
    } catch (e) {
   
      hilog.error(0x0001, 'CrashHandler', 'Failed to save crash log');
    }
  }

  onDestroy() {
   
    errorManager.off('error');
  }
}

2.2 Promise 未捕获异常

// 监听 unhandledrejection
errorManager.on('error', {
   
  onUnhandledException: (errMsg: string) => {
   
    // 处理同步异常
  },
  onException: (errObject: Error) => {
   
    // 处理 Promise rejection
    hilog.error(0x0001, 'PromiseError', 'Unhandled rejection: %{public}s', errObject.message);
  }
});

三、DevEco Studio 调试工具

3.1 断点调试

操作步骤：

1. 在代码行号左侧点击设置断点
2. 点击 Debug 按钮启动调试
3. 程序暂停时查看变量、调用栈、表达式求值

条件断点：

• 右键断点 → Condition，设置如 userId === '123'

3.2 日志过滤

在 DevEco Studio 的 HiLog 窗口：

• 按 Tag 过滤：输入 MyApp
• 按级别过滤：选择 Error 只显示错误日志
• 按进程过滤：选择当前应用进程

3.3 实时预览与热重载

• Previewer：实时预览 UI 组件，修改代码后自动刷新
• Hot Reload：保持应用状态的情况下更新代码

四、hilog 命令行工具

连接设备或模拟器后，通过 hdc 使用 hilog：

# 实时查看日志
hdc shell hilog

# 按 Tag 过滤
hdc shell hilog -t MyApp

# 按级别过滤（只看 Error 和 Fatal）
hdc shell hilog -L E

# 清空日志
hdc shell hilog -r

# 导出日志到文件
hdc shell hilog > app.log

五、性能分析与内存泄漏排查

5.1 Profiler 工具

DevEco Studio 提供 Profiler 用于性能分析：

• CPU Profiler：查看方法耗时、调用栈
• Memory Profiler：监控内存占用、对象分配
• Network Profiler：查看网络请求时序

5.2 内存泄漏定位

常见场景：

• 闭包持有 this
• 定时器未清理
• 事件监听器未移除

排查方法：

1. 使用 Memory Profiler 观察内存曲线
2. 触发页面进入、退出操作
3. 手动触发 GC 后查看对象是否被回收

代码示例：

@Entry
@Component
struct LeakDemo {
   
  private timer: number = -1;

  aboutToAppear() {
   
    // ❌ 错误：未清理定时器
    this.timer = setInterval(() => {
   
      console.log('tick');
    }, 1000);
  }

  aboutToDisappear() {
   
    // ✅ 正确：清理定时器
    if (this.timer !== -1) {
   
      clearInterval(this.timer);
      this.timer = -1;
    }
  }
}

六、线上日志治理

6.1 日志脱敏

export class SecureLogger {
   
  static maskPhone(phone: string): string {
   
    return phone.replace(/(\d{3})\d{4}(\d{4})/, '$1****$2');
  }

  static maskIdCard(idCard: string): string {
   
    return idCard.replace(/(\d{6})\d{8}(\w{4})/, '$1********$2');
  }

  static logUserAction(action: string, userId: string) {
   
    hilog.info(0x0001, 'UserAction', '%{public}s, userId: %{public}s',
      action, this.maskUserId(userId));
  }
}

6.2 日志分级上报

export class LogUploader {
   
  static uploadIfNeeded(level: string, message: string) {
   
    if (level === 'ERROR' || level === 'FATAL') {
   
      // 立即上报
      this.uploadToServer({
   
        level,
        message,
        timestamp: Date.now(),
        deviceInfo: this.getDeviceInfo()
      });
    } else if (level === 'WARN') {
   
      // 批量上报
      this.addToBuffer(message);
    }
  }

  private static uploadToServer(log: object) {
   
    // 调用网络接口上报
  }
}

6.3 日志采样策略

export class SamplingLogger {
   
  private static sampleRate = 0.1; // 10% 采样率

  static shouldLog(): boolean {
   
    return Math.random() < this.sampleRate;
  }

  static debug(tag: string, message: string) {
   
    if (this.shouldLog()) {
   
      hilog.debug(0x0001, tag, message);
    }
  }
}

七、崩溃治理最佳实践

7.1 崩溃率指标

崩溃率 = 崩溃用户数 / 活跃用户数

目标：主版本崩溃率 < 0.1%

7.2 崩溃分类与优先级

7.3 崩溃修复闭环

1. 监控告警：崩溃率突增自动触发告警
2. 快速定位：通过堆栈、日志还原现场
3. 紧急修复：热修复或快速发版
4. 回归验证：修复版本上线后验证崩溃率下降
5. 复盘总结：分析根因，建立防护机制

八、总结

HarmonyOS 的日志与调试体系包括：

工程化要点：

• 日志分级输出、脱敏处理
• 崩溃自动上报、分类治理
• 开发期 Debug 日志、线上仅保留 Error/Fatal
• 定期回顾崩溃 Top 问题，建立修复优先级

通过完善的日志与调试基础设施，可以快速定位问题、缩短修复周期，最终提升应用稳定性与用户体验。