HarmonyOS 跨设备调试技巧: 从 hdc 命令行到分布式链路追踪的全栈实战

想你依然心痛

25人浏览 · 2026-08-28 21:28:38

想你依然心痛新星共创者 · 2026-08-28 21:28:38 发布

文章目录

在这里插入图片描述

每日一句正能量

“不要惧怕破碎，那往往是新生的开始。”
我们珍视的“完整”（如固有的认知、稳定的关系、熟悉的路径）有时会变成限制我们的“完整体”。不惧怕，是拥有了识别“结束中的开始”的远见。它不是被动的忍受，而是主动的信任——信任生命本身的更新能力。

摘要

在 HarmonyOS 分布式生态中, Bug 往往不再局限于单一设备, 而是隐藏在跨设备通信、状态同步、Ability 迁移的复杂交互之中。传统的单设备调试手段(断点、日志、Profiler)已无法满足分布式场景的排障需求。本文基于 HarmonyOS 5.0(API 12)与 DevEco Studio 4.1, 系统梳理了hdc 命令行工具链、HiTrace 分布式链路追踪、多设备日志关联分析、无线远程调试、DevEco Studio 可视化调试五大核心能力, 并结合真实案例提供可直接落地的调试方案与脚本工具。

一、跨设备调试的核心挑战

1.1 分布式场景下的调试困境

与传统单设备应用不同, HarmonyOS 分布式应用的核心逻辑运行在设备集群之上, 调试面临以下独特挑战:

挑战维度	单设备调试	跨设备调试
问题定位	堆栈跟踪即可定位	需追踪跨设备调用链
日志获取	单设备日志文件	多设备日志时间对齐
状态观测	本地变量查看	分布式状态一致性校验
网络分析	本地抓包即可	软总线协议需专用工具
复现难度	单一环境	多设备组网环境依赖

1.2 调试效率瓶颈

瓶颈一: 设备切换成本。 开发者需要在手机、平板、智慧屏之间频繁切换 USB 连接, 每次切换耗时 30 秒以上, 严重打断调试节奏。

瓶颈二: 日志碎片化。 五台设备的日志分散在不同文件中, 缺乏统一的时间基准, 难以还原事件发生的先后顺序。

瓶颈三: 异步调用黑盒。 Ability 迁移、分布式数据同步等操作涉及异步回调, 传统断点调试无法有效跟踪跨设备的状态流转。

瓶颈四: 偶现问题难复现。 软总线通信抖动、设备瞬时离线等问题具有随机性, 需要长时间监控与自动化捕获机制。

二、跨设备调试全景架构

HarmonyOS 提供了一套完整的跨设备调试基础设施, 从底层设备连接到上层可视化分析, 形成完整的调试闭环:

在这里插入图片描述

调试主机层: 以 DevEco Studio 为核心 IDE, 配合 hdc(HarmonyOS Device Connector)命令行工具, 实现对多设备的统一管理。

调试通道层: 提供 USB 调试通道、Wi-Fi 无线调试通道、HiLog 日志通道、HiTrace 跟踪通道、Profiler 性能通道五大通道, 分别对应不同的调试场景。

分布式软总线: 作为设备间通信的底层基础设施, 软总线本身也是调试对象–需要监控其设备发现、会话建立、数据传输的全过程。

被调试终端层: 涵盖 Phone、Pad、TV、Wearable、Car 等全场景设备, 每种设备的调试入口与权限配置略有差异。

三、hdc 命令行工具链深度实战

hdc 是 HarmonyOS 的通用设备连接工具, 功能对标 Android 的 adb, 但在分布式场景下提供了更丰富的多设备管理能力。

在这里插入图片描述

3.1 多设备管理基础

# 列出所有已连接设备(含 USB 与 Wi-Fi)
hdc list targets
# 输出示例:
# 127.0.0.1:8710    product=phone model=HUAWEI_P60
# 192.168.1.105:8710  product=pad model=HUAWEI_MatePad
# 192.168.1.110:8710  product=tv model=HUAWEI_Vision

# 指定设备执行命令(-t 参数)
hdc -t 127.0.0.1:8710 shell
hdc -t 192.168.1.105:8710 shell bm dump -a

# 批量执行命令(结合 xargs 或 parallel)
for device in $(hdc list targets | awk '{print $1}'); do
    echo "=== Device: $device ==="
    hdc -t $device shell "param get const.product.name"
done

3.2 应用调试命令集

# 安装 HAP 包到指定设备
hdc -t <device_id> install entry/build/outputs/entry-default-signed.hap

# 启动 Ability 并附加调试模式
hdc -t <device_id> shell aa start -a EntryAbility -b com.example.demo -D
# -D 参数开启调试模式, 等待 DevEco Studio 连接

# 强制停止应用(模拟崩溃后恢复场景)
hdc -t <device_id> shell aa force-stop com.example.demo

# 查看 Ability 栈状态(排查迁移后 Ability 未销毁问题)
hdc -t <device_id> shell aa dump -a

# 查看应用内存占用
hdc -t <device_id> shell hidumper -s Memory -a com.example.demo

3.3 日志实时采集与分析

# 实时查看指定应用的日志(过滤分布式相关 Tag)
hdc -t <device_id> hilog | grep -E "(DSoftBus|Distributed|AbilityRuntime|MissionManager)"

# 设置日志级别(调试时开启 DEBUG 级别)
hdc -t <device_id> shell hilog -b D
hdc -t <device_id> shell hilog -b D -T DSoftBus

# 导出完整日志到本地
hdc -t <device_id> shell hilog -g > /data/log/hilog_all.log
hdc -t <device_id> file recv /data/log/hilog_all.log ./logs/phone_hilog.log

# 清空日志缓冲区(每次测试前执行, 避免旧日志干扰)
hdc -t <device_id> shell hilog -r

3.4 网络与软总线调试

# 查看设备网络配置(排查组网失败问题)
hdc -t <device_id> shell ifconfig
hdc -t <device_id> shell netcfg

# 测试设备间网络连通性
cat << 'EOF' > ping_test.sh
#!/bin/bash
TARGET_IP="192.168.1.105"
for device in $(hdc list targets | awk '{print $1}'); do
    echo "Testing from $device to $TARGET_IP"
    hdc -t $device shell "ping -c 3 $TARGET_IP"
done
EOF
bash ping_test.sh

# 查看软总线运行状态
hdc -t <device_id> shell cat /proc/dsoftbus/status
hdc -t <device_id> shell ls /data/misc/dsoftbus/

# 抓包分析软总线通信(需 root 权限)
hdc -t <device_id> shell tcpdump -i any -w /data/capture/dsoftbus.pcap 'port 5555 or port 5556'
hdc -t <device_id> file recv /data/capture/dsoftbus.pcap ./pcap/dsoftbus_phone.pcap

3.5 文件系统与数据调试

# 查看分布式数据存储目录
hdc -t <device_id> shell ls -la /data/app/el2/100/base/com.example.demo/haps/entry/files/

# 导出分布式 KV 数据库文件进行离线分析
hdc -t <device_id> file recv /data/app/el2/100/database/kvdb/test_store.db ./db/phone_kv.db

# 查看系统参数(排查版本兼容性)
hdc -t <device_id> shell param get const.ohos.apiversion
hdc -t <device_id> shell param get const.product.software.version
hdc -t <device_id> shell param get persist.distributed.enable

四、HiTrace 分布式链路追踪

4.1 为什么需要分布式链路追踪

当用户从手机迁移 Ability 到平板时, 涉及的调用链跨越了多个进程、多个设备、多个服务:

用户点击 -> UI 框架 -> AbilityRuntime -> MissionManager -> DSoftBus -> 网络传输 -> 
DSoftBus(远端) -> AbilityRuntime(远端) -> UI 框架(远端) -> 页面渲染

任何一个环节出现问题, 都会导致迁移失败。HiTrace 通过跨设备的 TraceId 传递机制, 将分散在各设备的日志串联成完整的调用链。

4.2 HiTrace 核心 API 使用

// utils/HiTraceHelper.ts
import hiTraceMeter from '@ohos.hiTraceMeter';
import hiTraceChain from '@ohos.hiTraceChain';

export class DistributedTraceHelper {
  static startTrace(name: string): hiTraceChain.HiTraceId {
    const traceId = hiTraceChain.begin(name, hiTraceChain.HiTraceFlag.INCLUDE_ASYNC);
    console.info(`[HiTrace] 开始追踪: ${name}, TraceId: ${traceId.getChainId()}`);
    return traceId;
  }

  static serializeTraceId(traceId: hiTraceChain.HiTraceId): string {
    return hiTraceChain.serialize(traceId);
  }

  static continueTrace(serializedId: string): hiTraceChain.HiTraceId {
    const traceId = hiTraceChain.deserialize(serializedId);
    hiTraceChain.tracepoint(hiTraceChain.HiTraceCommunicationMode.CLIENT,
                            hiTraceChain.HiTraceTracepointType.SS,
                            traceId, '跨设备调用发起');
    return traceId;
  }

  static endTrace(traceId: hiTraceChain.HiTraceId): void {
    hiTraceChain.tracepoint(hiTraceChain.HiTraceCommunicationMode.CLIENT,
                            hiTraceChain.HiTraceTracepointType.SR,
                            traceId, '跨设备调用完成');
    hiTraceChain.end(traceId);
    console.info(`[HiTrace] 结束追踪, TraceId: ${traceId.getChainId()}`);
  }
}

4.3 在 Ability 迁移中集成 HiTrace

// entry/src/main/ets/entryability/EntryAbility.ets
import { DistributedTraceHelper } from '../utils/HiTraceHelper';
import distributedMissionManager from '@ohos.distributedMissionManager';

export default class EntryAbility extends UIAbility {
  private migrateTraceId: hiTraceChain.HiTraceId | null = null;

  onContinue(wantParam: Record<string, Object>): AbilityConstant.OnContinueResult {
    this.migrateTraceId = DistributedTraceHelper.startTrace('AbilityContinue');
    const serializedTraceId = DistributedTraceHelper.serializeTraceId(this.migrateTraceId);
    wantParam['traceId'] = serializedTraceId;
    console.info(`[Migrate] onContinue 触发, 保存状态: ${JSON.stringify(wantParam)}`);
    return AbilityConstant.OnContinueResult.AGREE;
  }

  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    if (want.parameters && want.parameters['traceId']) {
      const remoteTraceId = DistributedTraceHelper.continueTrace(
        want.parameters['traceId'] as string
      );
      console.info(`[Migrate] 目标设备 onCreate, 恢复 TraceId`);
      DistributedTraceHelper.endTrace(remoteTraceId);
    }
  }
}

4.4 HiTrace 日志分析与可视化

# 采集包含 HiTrace 标记的日志
hdc hilog | grep -E "(HiTrace|TraceId|chainId)" > ./trace/hitrace_raw.log

# 使用 hitrace 工具生成可视化报告
hdc shell hitrace -t 10 -o /data/trace/trace.ftrace
hdc file recv /data/trace/trace.ftrace ./trace/

# 使用 systrace 或 Perfetto 打开分析
# 在浏览器中打开 https://ui.perfetto.dev/ 加载 trace.ftrace 文件

五、多设备日志关联分析

5.1 日志时间轴对齐原理

跨设备调试最大的痛点在于: 各设备的本地时间是独立运行的, 存在毫秒级甚至秒级的偏差。如果不进行时间对齐, 直接对比日志会导致事件顺序错乱。

在这里插入图片描述

对齐方案: 以调试主机的 NTP 时间为基准, 在日志采集时统一打上主机时间戳。

5.2 自动化日志采集脚本

#!/bin/bash
# collect_distributed_logs.sh - 分布式日志批量采集脚本

OUTPUT_DIR="./logs/$(date +%Y%m%d_%H%M%S)"
mkdir -p $OUTPUT_DIR

# 定义设备列表
DEVICES=(
    "phone:127.0.0.1:8710"
    "pad:192.168.1.105:8710"
    "tv:192.168.1.110:8710"
)

# 统一时间基准
HOST_TIME=$(date +%s%3N)
echo "{\"sync_time\": $HOST_TIME, \"host\": \"$(hostname)\"}" > $OUTPUT_DIR/sync_meta.json

for device in "${DEVICES[@]}"; do
    IFS=':' read -r name ip port <<< "$device"
    device_id="${ip}:${port}"
    
    echo "正在采集 ${name}(${device_id}) 日志..."
    
    # 采集 hilog
    hdc -t $device_id shell hilog -g > $OUTPUT_DIR/${name}_hilog.log
    
    # 采集设备时间偏移量
    device_time=$(hdc -t $device_id shell echo $(date +%s%3N))
    offset=$((device_time - HOST_TIME))
    echo "{\"device\": \"$name\", \"offset_ms\": $offset}" >> $OUTPUT_DIR/time_offsets.json
    
    # 采集 dsoftbus 日志
    hdc -t $device_id shell dmesg | grep -i dsoftbus > $OUTPUT_DIR/${name}_dsoftbus.log
    
    # 采集应用崩溃日志
    hdc -t $device_id shell ls /data/log/faultlog/ | tail -5 > $OUTPUT_DIR/${name}_faults.log
done

echo "日志采集完成, 输出目录: $OUTPUT_DIR"

5.3 日志关联分析工具

# log_correlator.py - 跨设备日志关联分析器
import json
import re
from datetime import datetime, timedelta
from collections import defaultdict

class DistributedLogCorrelator:
    def __init__(self, log_dir: str):
        self.log_dir = log_dir
        self.events = []
        self.trace_chains = defaultdict(list)
    
    def parse_hilog(self, device_name: str, filepath: str, time_offset_ms: int):
        pattern = r"(\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}\.\d{3})\s+(\w+)\s+\w+\s+\w+\s+(.+)"
        with open(filepath, 'r', encoding='utf-8', errors='ignore') as f:
            for line in f:
                match = re.match(pattern, line)
                if match:
                    raw_time = match.group(1)
                    level = match.group(2)
                    message = match.group(3)
                    dt = datetime.strptime(f'2024-{raw_time}', '%Y-%m-%d %H:%M:%S.%f')
                    aligned_dt = dt + timedelta(milliseconds=time_offset_ms)
                    event = {
                        'timestamp': aligned_dt,
                        'device': device_name,
                        'level': level,
                        'message': message
                    }
                    self.events.append(event)
                    trace_match = re.search(r'TraceId:\s*(\d+)', message)
                    if trace_match:
                        trace_id = trace_match.group(1)
                        self.trace_chains[trace_id].append(event)
    
    def generate_timeline(self, output_path: str):
        self.events.sort(key=lambda x: x['timestamp'])
        with open(output_path, 'w', encoding='utf-8') as f:
            f.write('=== HarmonyOS Cross-Device Log Timeline ===\n\n')
            for event in self.events:
                marker = ''
                if 'DSoftBus' in event['message']:
                    marker = '[SoftBus]'
                elif 'AbilityRuntime' in event['message']:
                    marker = '[Ability]'
                f.write(f"[{event['timestamp'].strftime('%H:%M:%S.%f')[:-3]}] "
                        f"{event['device']:8} {marker:10} {event['level']:5} {event['message']}\n")
    
    def analyze_trace_chain(self, trace_id: str) -> dict:
        chain = sorted(self.trace_chains[trace_id], key=lambda x: x['timestamp'])
        if not chain:
            return {}
        duration = (chain[-1]['timestamp'] - chain[0]['timestamp']).total_seconds() * 1000
        devices_involved = set(e['device'] for e in chain)
        return {
            'trace_id': trace_id,
            'duration_ms': duration,
            'devices': list(devices_involved),
            'event_count': len(chain)
        }

六、无线调试与远程诊断

在这里插入图片描述

6.1 Wi-Fi 调试配置

USB 调试在跨设备场景下效率极低, Wi-Fi 无线调试是必备技能:

# 步骤1: 通过 USB 连接设备, 获取 IP 地址
hdc -t <usb_device> shell ifconfig wlan0 | grep "inet addr"
# 输出: inet addr:192.168.1.105  Mask:255.255.255.0

# 步骤2: 启动设备的 hdc 守护进程监听 TCP 端口
hdc -t <usb_device> shell hdcd -t 8710 -s

# 步骤3: 切换为 Wi-Fi 连接
hdc tconn 192.168.1.105:8710

# 步骤4: 断开 USB, 验证 Wi-Fi 连接
hdc list targets
# 应显示: 192.168.1.105:8710

# 步骤5: 批量配置所有设备的 Wi-Fi 调试
for ip in 192.168.1.{105..110}; do
    hdc tconn ${ip}:8710 2>/dev/null && echo "Connected: $ip" || echo "Failed: $ip"
done

6.2 远程诊断隧道

当设备不在本地网络时, 可通过反向 SSH 隧道建立远程调试通道:

# 在设备端建立反向隧道(需设备支持 ssh)
hdc -t <device_id> shell "ssh -fNR 9876:localhost:8710 user@jump-server.com"

# 在本地通过跳板机连接远程设备
ssh -L 9876:localhost:9876 user@jump-server.com
hdc tconn 127.0.0.1:9876

6.3 自动化设备发现与连接

// utils/DeviceConnector.ts
import { exec } from 'child_process';
import { promisify } from 'util';

const execAsync = promisify(exec);

interface DeviceInfo {
  id: string;
  ip: string;
  product: string;
  isConnected: boolean;
}

export class AutoDeviceConnector {
  private deviceSubnet: string = '192.168.1';
  private port: number = 8710;

  async scanDevices(): Promise<DeviceInfo[]> {
    const devices: DeviceInfo[] = [];
    const scanPromises = [];
    for (let i = 1; i <= 254; i++) {
      const ip = `${this.deviceSubnet}.${i}`;
      scanPromises.push(this.tryConnect(ip));
    }
    const results = await Promise.allSettled(scanPromises);
    results.forEach((result) => {
      if (result.status === 'fulfilled' && result.value) {
        devices.push(result.value);
      }
    });
    return devices;
  }

  private async tryConnect(ip: string): Promise<DeviceInfo | null> {
    try {
      const { stdout } = await execAsync(`hdc tconn ${ip}:${this.port}`, { timeout: 3000 });
      if (stdout.includes('Connect OK')) {
        const { stdout: info } = await execAsync(`hdc -t ${ip}:${this.port} shell param get const.product.name`);
        return { id: `${ip}:${this.port}`, ip, product: info.trim(), isConnected: true };
      }
    } catch (e) { }
    return null;
  }

  async broadcastCommand(command: string): Promise<Map<string, string>> {
    const devices = await this.getConnectedDevices();
    const results = new Map<string, string>();
    await Promise.all(devices.map(async (device) => {
      try {
        const { stdout } = await execAsync(`hdc -t ${device.id} shell ${command}`);
        results.set(device.id, stdout);
      } catch (e) {
        results.set(device.id, `ERROR: ${(e as Error).message}`);
      }
    }));
    return results;
  }

  private async getConnectedDevices(): Promise<DeviceInfo[]> {
    const { stdout } = await execAsync('hdc list targets');
    return stdout.split('\n')
      .filter(line => line.trim())
      .map(line => {
        const parts = line.trim().split(/\s+/);
        return { id: parts[0], ip: parts[0].split(':')[0], product: '', isConnected: true };
      });
  }
}

七、DevEco Studio 可视化调试

7.1 多设备并行调试配置

DevEco Studio 4.1 支持同时连接多台设备进行调试, 配置步骤如下:

打开 Device Manager: Tools -> Device Manager
添加物理设备: 点击 + 按钮, 选择 Physical Device, 输入 hdc 设备 ID
配置多设备启动: 在 Run/Debug Configurations 中选择 Multiple Devices
设置主控设备: 指定 Ability 迁移的源设备, 其余设备自动作为目标端

7.2 HiLog 窗口多设备过滤

HiLog Window Config:
[Device Filter] [phone_001] [pad_001] [tv_001]
[Log Level] [DEBUG]
[Keywords] DSoftBus | AbilityRuntime | MissionManager
[Time Range] 2024-08-23 14:30:00 ~ 14:35:00
[Regex] TraceId:\d+

7.3 分布式调试断点

在跨设备 Ability 迁移场景中, DevEco Studio 支持跨设备断点:

// 源设备断点
onContinue(wantParam: Record<string, Object>): AbilityConstant.OnContinueResult {
    debugger;  // DevEco Studio pauses here
    const savedState = this.saveState();
    wantParam['state'] = JSON.stringify(savedState);
    return AbilityConstant.OnContinueResult.AGREE;
}

// 目标设备断点
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    debugger;
    if (want.parameters?.['state']) {
      const state = JSON.parse(want.parameters['state'] as string);
      this.restoreState(state);
    }
}

调试技巧: 在 DevEco Studio 中同时打开两个设备的调试会话, 当源设备执行到 onContinue 断点时, 手动切换到目标设备的调试会话, 等待 onCreate 断点触发。

八、典型问题排查案例

8.1 案例一: Ability 迁移后黑屏

现象: 用户点击迁移到平板后, 平板端 Ability 启动但页面黑屏。

排查步骤:

# Step 1: 检查目标设备 Ability 生命周期回调
hdc -t <pad_id> hilog | grep -E "(onCreate|onWindowStageCreate|onRestoreData)"
# 发现: onRestoreData 未触发, 说明迁移数据未正确传递

# Step 2: 检查软总线数据传输
hdc -t <phone_id> hilog | grep -E "(DSoftBus|continueMission)"
# 发现: DSoftBus 发送成功, 但平板端未收到

# Step 3: 检查设备组网状态
hdc -t <pad_id> shell "cat /proc/dsoftbus/peers"
# 发现: phone 不在 peers 列表中, 组网已断开

# Step 4: 检查网络连通性
hdc -t <phone_id> shell "ping -c 3 <pad_ip>"
# 发现: 网络不通, 路由器 AP 隔离导致

# 根因: 路由器开启了 AP 隔离, 设备间无法直接通信
# 解决: 关闭 AP 隔离, 或配置设备间通过 P2P 直连

8.2 案例二: 分布式数据同步延迟

现象: 手机端修改设置后, 平板端 10 秒后才同步。

排查步骤:

# Step 1: 采集两端 KV Store 日志
hdc -t <phone_id> hilog | grep -i "distributedkvstore" > phone_kv.log
hdc -t <pad_id> hilog | grep -i "distributedkvstore" > pad_kv.log

# Step 2: 分析同步时序
# 手机端日志:
# 14:30:00.123 D DistributedKVStore: Put key=settings_theme, value=dark
# 14:30:00.456 D DistributedKVStore: Sync request sent
# 平板端日志:
# 14:30:10.789 D DistributedKVStore: DataChange received, key=settings_theme

# Step 3: 检查软总线传输时延
hdc -t <phone_id> shell "cat /proc/dsoftbus/stats"
# 发现: 重传率 15%, 丢包严重

# Step 4: 网络质量检测
hdc -t <phone_id> shell "ping -c 100 -i 0.01 <pad_ip>"
# 发现: 丢包率 12%, 时延抖动大

# 根因: Wi-Fi 信号弱, 2.4GHz 频段干扰严重
# 解决: 切换至 5GHz 频段, 或优化软总线重传策略

8.3 案例三: 设备发现间歇性失败

现象: 应用有时能发现周边设备, 有时发现不了。

// 在应用中添加详细的状态监听日志
import distributedDeviceManager from '@ohos.distributedDeviceManager';

class DeviceDiscoveryDebugger {
  private deviceManager: distributedDeviceManager.DeviceManager;

  init() {
    this.deviceManager = distributedDeviceManager.createDeviceManager('com.example.debug');
    this.deviceManager.on('deviceStateChange', (data) => {
      console.info(`[DeviceState] Action: ${data.action}, Device: ${data.device.deviceName}`);
      console.info(`[DeviceState] NetworkId: ${data.device.networkId}`);
    });
    this.deviceManager.on('discoverFail', (data) => {
      console.error(`[DiscoverFail] SubscribeId: ${data.subscribeId}, Reason: ${data.reason}`);
    });
  }

  startDiscoveryWithLog() {
    const subscribeInfo = {
      subscribeId: 12345,
      mode: distributedDeviceManager.DiscoverMode.DISCOVER_MODE_ACTIVE,
      medium: distributedDeviceManager.ExchangeMedium.AUTO,
      freq: distributedDeviceManager.ExchangeFreq.HIGH,
      isSameAccount: false,
      isWakeRemote: true,
      capability: 0
    };
    console.info(`[Discovery] Start discovery, SubscribeId: ${subscribeInfo.subscribeId}`);
    const startTime = Date.now();
    this.deviceManager.startDeviceDiscovery(subscribeInfo);
    setTimeout(() => {
      const devices = this.deviceManager.getAvailableDeviceListSync();
      console.info(`[Discovery] Found ${devices.length} devices in ${Date.now()-startTime}ms`);
    }, 10000);
  }
}

# 结合系统日志分析
hdc -t <device_id> hilog | grep -E "(DeviceState|DiscoverFail|Discovery)" > discovery_debug.log

# 检查蓝牙/Wi-Fi 状态
hdc -t <device_id> shell "dumpsys bluetooth_manager"
hdc -t <device_id> shell "dumpsys wifi"

# 根因定位:
# 1. BLE 广播被系统限制(后台应用限制)
# 2. Wi-Fi P2P 组建立失败(频段冲突)
# 3. 设备休眠导致发现服务停止

九、调试效率提升技巧

9.1 一键调试环境初始化脚本

#!/bin/bash
# init_debug_env.sh - 一键初始化跨设备调试环境

echo "=== HarmonyOS Cross-Device Debug Environment Init ==="

# 1. 检查 hdc 版本
HDC_VERSION=$(hdc version | head -1)
echo "hdc version: $HDC_VERSION"

# 2. 启动所有设备的 hdcd 服务
for device in $(hdc list targets | awk '{print $1}'); do
    echo "Starting hdcd on $device..."
    hdc -t $device shell hdcd -s
done

# 3. 统一设置日志级别
for device in $(hdc list targets | awk '{print $1}'); do
    hdc -t $device shell hilog -b D
    hdc -t $device shell hilog -b D -T DSoftBus
    hdc -t $device shell hilog -b D -T AbilityRuntime
    hdc -t $device shell hilog -b D -T MissionManager
    hdc -t $device shell hilog -r
done

# 4. 创建日志输出目录
mkdir -p ./logs/$(date +%Y%m%d)

# 5. 检查设备组网状态
echo "=== Device Mesh Status ==="
for device in $(hdc list targets | awk '{print $1}'); do
    echo "Device $device peers:"
    hdc -t $device shell "cat /proc/dsoftbus/peers" 2>/dev/null || echo "  No peers"
done

echo "=== Init Complete ==="

9.2 实时日志监控面板

#!/bin/bash
# start_log_monitor.sh

SESSION="harmonyos_debug"
tmux new-session -d -s $SESSION

# Window 1: Phone logs
tmux rename-window -t $SESSION:0 'Phone'
tmux send-keys -t $SESSION:0 'hdc -t phone_id hilog | grep -E "(DSoftBus|AbilityRuntime|MissionManager)"' C-m

# Window 2: Pad logs
tmux new-window -t $SESSION:1 -n 'Pad'
tmux send-keys -t $SESSION:1 'hdc -t pad_id hilog | grep -E "(DSoftBus|AbilityRuntime|MissionManager)"' C-m

# Window 3: TV logs
tmux new-window -t $SESSION:2 -n 'TV'
tmux send-keys -t $SESSION:2 'hdc -t tv_id hilog | grep -E "(DSoftBus|AbilityRuntime|MissionManager)"' C-m

# Window 4: Console
tmux new-window -t $SESSION:3 -n 'Console'

tmux attach -t $SESSION

9.3 自动化问题捕获与告警

// utils/DebugMonitor.ts
import { exec } from 'child_process';
import { promisify } from 'util';

const execAsync = promisify(exec);

interface AlertRule {
  name: string;
  pattern: RegExp;
  severity: 'warning' | 'error' | 'critical';
  action: (match: RegExpMatchArray, deviceId: string) => Promise<void>;
}

export class DistributedDebugMonitor {
  private rules: AlertRule[] = [];
  private isRunning: boolean = false;

  constructor() { this.initRules(); }

  private initRules() {
    this.rules.push({
      name: 'AbilityMigrationFailed',
      pattern: /onContinue.*FAILED|continueMission.*error/,
      severity: 'error',
      action: async (match, deviceId) => {
        console.error(`[ALERT] ${deviceId} Ability migration failed: ${match[0]}`);
        await this.collectContextLogs(deviceId, 'migration_failure');
      }
    });
    this.rules.push({
      name: 'SoftBusDisconnected',
      pattern: /DSoftBus.*disconnect|peer.*offline/,
      severity: 'warning',
      action: async (match, deviceId) => {
        console.warn(`[ALERT] ${deviceId} SoftBus disconnected: ${match[0]}`);
        await this.checkNetworkHealth(deviceId);
      }
    });
    this.rules.push({
      name: 'DataSyncTimeout',
      pattern: /KVSync.*timeout|distributedData.*sync.*fail/,
      severity: 'error',
      action: async (match, deviceId) => {
        console.error(`[ALERT] ${deviceId} Data sync timeout: ${match[0]}`);
      }
    });
  }

  async startMonitoring(deviceIds: string[]): Promise<void> {
    this.isRunning = true;
    const monitorPromises = deviceIds.map(id => this.monitorDevice(id));
    await Promise.all(monitorPromises);
  }

  private async monitorDevice(deviceId: string): Promise<void> {
    while (this.isRunning) {
      try {
        const { stdout } = await execAsync(`hdc -t ${deviceId} hilog -t 100`, { timeout: 5000 });
        for (const rule of this.rules) {
          const match = stdout.match(rule.pattern);
          if (match) { await rule.action(match, deviceId); }
        }
      } catch (e) { }
      await new Promise(resolve => setTimeout(resolve, 1000));
    }
  }

  private async collectContextLogs(deviceId: string, context: string): Promise<void> {
    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
    const outputDir = `./logs/alerts/${context}_${timestamp}`;
    await execAsync(`mkdir -p ${outputDir}`);
    await execAsync(`hdc -t ${deviceId} shell hilog -g > ${outputDir}/hilog.log`);
    await execAsync(`hdc -t ${deviceId} shell dmesg > ${outputDir}/dmesg.log`);
    await execAsync(`hdc -t ${deviceId} shell cat /proc/dsoftbus/status > ${outputDir}/dsoftbus_status.log`);
    console.info(`[Monitor] Context logs saved to: ${outputDir}`);
  }

  private async checkNetworkHealth(deviceId: string): Promise<void> {
    try {
      const { stdout } = await execAsync(`hdc -t ${deviceId} shell ifconfig`);
      console.info(`[Monitor] ${deviceId} network status:\n${stdout}`);
    } catch (e) {
      console.error(`[Monitor] Cannot get ${deviceId} network status`);
    }
  }

  stop(): void { this.isRunning = false; }
}