hdc 速查手册 — HarmonyOS 设备调试连接器
# 🔌 hdc 速查手册（HarmonyOS Device Connector）
hdc 是鸿蒙版的 adb。本文按能力域组织：不求罗列全部参数，而是让你知道 hdc 能干哪些大事、每个域最常用的命令长什么样。 所有命令均在真机（API 24，hdc 3.2.0c）上验证过；实战配方来自真实 GPU 渲染内存排查实验的踩坑沉淀。
# 🗺️ 能力域总览
| # | 能力域 | 关键命令 | 对应 adb |
|---|---|---|---|
| 1 | 设备连接 | list targets / tconn / tmode | devices / connect |
| 2 | 应用管理 | install / bm / aa | pm / am |
| 3 | 文件传输 | file send / file recv | push / pull |
| 4 | Shell 与设备端脚本 | shell "循环..." | shell |
| 5 | 日志 | hilog | logcat |
| 6 | 系统服务转储 | hidumper -s <SA> -a '...' | dumpsys |
| 7 | 性能与内存观测 | hidumper --mem / --mem-jsheap / hiperf | dumpsys meminfo |
| 8 | 输入注入与 UI 自动化 | uinput / uitest | input tap/swipe |
| 9 | 端口转发 | fport / rport | forward / reverse |
| 10 | 截屏与布局 | snapshot_display / uitest screenCap | screencap |
| 11 | 调试支持 | jpid / shell -b / bugreport | jdwp / bugreport |
# 0. 环境与全局命令
hdc 随 DevEco Studio 的 SDK 发布，本机路径：
/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains/hdc
# 建议加入 PATH
export PATH=$PATH:/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains
1
2
3
2
3
hdc -v # 版本
hdc -h # 帮助
hdc help verbose # 更多隐藏命令
hdc -t <connectKey> <命令> # 多设备时指定目标
hdc kill [-r] # 杀 server（-r 重启），连接异常时先杀再起
hdc start [-r] # 启动/重启 server
hdc checkserver # 检查 client-server 版本一致性
1
2
3
4
5
6
7
2
3
4
5
6
7
设备级控制（daemon 侧）：
hdc target mount # /system /vendor 挂载为可写
hdc smode [-r] # daemon 以 root 权限运行（-r 取消）
hdc target boot [-bootloader|-recovery] # 重启/进 bootloader/recovery
hdc wait # 等待设备可用（脚本友好）
1
2
3
4
2
3
4
# 1. 设备连接管理
hdc list targets # 列出设备
hdc list targets -v # 详细状态
# 无线连接（TCP）
hdc tmode port 5555 # 设备端切换为 TCP 监听（会重启设备 daemon）
hdc tconn 192.168.1.100:5555 # host 连接
hdc tconn 192.168.1.100:5555 -remove # 断开
hdc tmode usb # 切回 USB 模式
hdc tmode port close # 关闭 TCP 端口
# 串口（UART）
hdc tconn COM5,921600 # 波特率默认 921600
1
2
3
4
5
6
7
8
9
10
11
12
2
3
4
5
6
7
8
9
10
11
12
排错套路：设备显示 [Empty] → hdc kill && hdc start → 换线/换口 → 检查开发者选项 USB 调试。
# 2. 应用管理（install / bm / aa）
# hdc 直装
hdc install -r app.hap # 安装（-r 替换已有；支持 .hap/.hsp/.app）
hdc install -s shared.hsp # 安装多应用共享包
hdc uninstall com.example.app # 卸载
hdc uninstall -k com.example.app # 卸载但保留数据与缓存
1
2
3
4
2
3
4
# bm（Bundle Manager，≈ pm）
hdc shell bm dump -n com.example.app # 查包详情：版本/签名/权限/ability
hdc shell bm dump -a # 列出全部已安装包
hdc shell bm clean -n com.example.app -c # 清缓存
hdc shell bm clean -n com.example.app -d # 清数据
hdc shell bm get --udid # 取设备 udid
hdc shell bm quickfix query # 热修复（quickfix）查询
1
2
3
4
5
6
2
3
4
5
6
# aa（Ability Assistant，≈ am）
hdc shell aa start -b com.example.app -a EntryAbility # 启动应用
hdc shell aa force-stop com.example.app # 强停进程
hdc shell aa dump # ability 栈信息
hdc shell aa attach com.example.app # 挂接调试模式（配合 IDE）
hdc shell aa detach com.example.app # 退出调试模式
1
2
3
4
5
2
3
4
5
# 3. 文件传输
hdc file send <本地> <设备> # ≈ adb push
hdc file recv <设备> <本地> # ≈ adb pull
# 选项：-a 保留时间戳 -sync 仅更新较新文件 -z 压缩传输
# -b 传输到 debug 应用目录 -cwd 指定工作目录
# 标准落点是 /data/local/tmp（可写），先建目录再传：
hdc shell mkdir -p /data/local/tmp
hdc file send rootCA.cer /data/local/tmp/rootCA.cer
hdc file recv /data/local/tmp/dump.log ./dump.log
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
# 4. Shell 与设备端脚本 ★ 高频踩坑域
hdc shell # 交互式 shell
hdc shell "ps -ef | grep myapp" # 单次执行
hdc shell -b com.example.app ls # 在 debug 应用沙箱目录内执行
1
2
3
2
3
# ★ 设备端循环：把循环放进一次 shell 调用
核心认知：host 每发起一次 hdc shell 都有秒级往返开销。host 端 for 循环 100 次 = 100 次 host↔device 往返（实测 ~9s/次），驱动/压测场景完全不可用。正确姿势是整段脚本一次下发，循环在设备端跑：
# 滑动注入 2 次，1.2s 间隔（$ 必须转义成 \$，防止被本机 shell 提前展开）
hdc shell "i=0; while [ \$i -lt 2 ]; do uinput -T -m 612 2100 612 600 200 >/dev/null 2>&1; i=\$((i+1)); sleep 1.2; done"
1
2
2
转义要点：
- host 双引号内的
$i、$((...))都要写成\$i、\$((...)) - 复杂脚本别硬塞一行：
hdc file send drive.sh /data/local/tmp/→hdc shell "sh /data/local/tmp/drive.sh" - 拿 pid 再拼命令：
hdc shell "pidof com.example.app"，或hdc shell "ps -ef | grep xxx"
# 5. 日志：hilog
hdc shell hilog # 阻塞式持续输出（≈ logcat）
hdc shell hilog -x # 一次性输出缓冲后退出（采样/落盘用）
hdc shell hilog -r # 清空日志缓冲
# 过滤（都支持 ^ 取反、逗号并列）
hdc shell hilog -T MyTag # 按 tag（最多 10 个）
hdc shell hilog -D 0xD003200 # 按 domain（最多 5 个）
hdc shell hilog -L D,I,W,E,F # 按级别
hdc shell hilog -P 12345 # 按 pid
hdc shell hilog -t app,core # 按类型 app/core/init/kmsg
# 头尾
hdc shell hilog -a 100 # 头 100 行
hdc shell hilog -z 100 # 尾 100 行
# 落盘
hdc shell hilog -x > dump.log
hdc shell "hilog -T MyTag" | grep --line-buffered keyword
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 6. 系统服务转储：hidumper ★★ 最强的"透视镜"
hidumper 是 dumpsys 的等价物，但能力更强：不仅能转储系统服务，还能直接做内存/CPU/网络/故障分析。
hdc shell hidumper -ls # 列出所有系统服务（SA）
hdc shell hidumper -s # 转储全部服务
hdc shell hidumper -s <SA> -a '<参数>' # 转储指定服务 + 参数（参数随服务而定）
hdc shell hidumper -s <SA> -a '-h' # 很多服务支持 -h 查自己的参数！
1
2
3
4
2
3
4
# RenderService 三板斧（GPU/渲染内存排查，来自实战）
# 按 pid 的渲染内存记账：node/pixelmap/GPU 分项 + totalSize（强杀判据方）
hdc shell "hidumper -s RenderService -a 'dumpExistPidMem <pid>'"
# 各进程 GPU 内存 + RS 全局汇总；输出后半段 kmd-ctx 表 = 驱动级真·显存
hdc shell "hidumper -s RenderService -a 'dumpGpuMem'"
# 全部 surface 缓冲队列：总量 + BufferQueue 个数（泄漏 surface 会在这里堆积）
hdc shell "hidumper -s RenderService -a 'allSurfacesMem'"
1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
# 其他高频转储
hdc shell hidumper -c # 全部系统信息簇
hdc shell hidumper -e # 历史 faultlog（崩溃记录）
hdc shell hidumper -e --list [进程名] # 异常退出列表
hdc shell hidumper -e --print <record_id> # 打印指定故障记录
hdc shell hidumper --net [pid] # 网络流量
hdc shell hidumper --storage [pid] # /proc/pid/io
1
2
3
4
5
6
2
3
4
5
6
# 7. 性能与内存观测
# 进程/系统内存（PSS 口径），支持 ashmem/dmabuf 明细
hdc shell hidumper --mem <pid>
hdc shell hidumper --mem <pid> --show-dmabuf
hdc shell hidumper --mem <pid> --show-ashmem
hdc shell hidumper --mem-smaps <pid> -v # smaps 统计
# ★ ArkTS 堆分析（JS/Native 堆快照，可触发 GC、查泄漏对象）
hdc shell hidumper --mem-jsheap <pid> --gc # 触发 GC
hdc shell hidumper --mem-jsheap <pid> --leakobj # dump 泄漏对象列表
hdc shell hidumper --mem-jsheap <pid> --raw # dump 原始堆
# CPU
hdc shell hidumper --cpuusage [pid] # CPU 占用（按进程/分类）
hdc shell hidumper --cpufreq # 各核实时频率
hdc shell hidumper -p <pid> # 线程/smap/执行时间
# IPC 负载
hdc shell hidumper --ipc <pid> --start-stat
hdc shell hidumper --ipc <pid> --stat
# 性能剖析（perf 等价物）
hdc shell hiperf stat -p <pid> --duration 10
hdc shell hiperf record -p <pid> -o /data/local/tmp/perf.data
hdc shell hiperf report -i /data/local/tmp/perf.data
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
⚠️ 口径警示：app 进程 PSS（
--mem）≠ RenderService 记账（dumpExistPidMem）≠ 驱动级显存（dumpGpuMem后半段）。GPU 渲染内存问题（如 RENDER_MEMORY_OVER_ERROR 强杀）以 RS 记账为准——它是强杀判据的记账方。
# 8. 输入注入与 UI 自动化：uinput / uitest ★
两套注入工具，性能差异巨大，选对工具是关键：
| 工具 | 通道 | 速度 | 适用 |
|---|---|---|---|
uitest uiInput | 无障碍树 | 慢（负载下实测 ~8.6s/次） | 语义操作、需要窗口感知 |
uinput -T | 内核级 | 快（~0.8s/次） | 高频驱动、压测复现 |
# uinput（内核级，快）
hdc shell uinput -T -c 328 2622 # 点击 (328,2622)
hdc shell uinput -T -m 612 2100 612 600 500 # 滑动 (612,2100)→(612,600)，速度 500
# -m x1 y1 x2 y2 [-k 保持时长ms] [平滑时长ms]
# 平滑时长默认 1000ms（最大 15000ms）；-k 保持最大 60000ms；最多支持三指同滑
hdc shell uinput -T -d 612 2100 # 按下
hdc shell uinput -T -u 612 600 # 抬起（自己组合长按）
hdc shell uinput -T -g 100 100 300 300 500 1000 # 拖拽（按下≥500ms）
# 其他通道：-K 键盘 -M 鼠标 -S 触控笔 -P 触控板 -k 指关节
hdc shell uinput -T -i 500 # 事件间隔 500ms
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
# uitest（无障碍树，慢但智能）
hdc shell uitest uiInput click 612 2100
hdc shell uitest uiInput swipe 612 2100 612 600 600 # 速度 200~40000，默认 600
hdc shell uitest uiInput dircFling 3 600 # 方向滑动 0/1/2/3=左右上下
hdc shell uitest uiInput keyEvent Back # keyEvent <id|Back|Home|Power>
# UI 树快照（慢！仅用于定位坐标/控件）
hdc shell uitest dumpLayout -p /data/local/tmp/layout.json
# 截屏
hdc shell uitest screenCap -p /data/local/tmp/s.jpeg
1
2
3
4
5
6
7
8
9
10
2
3
4
5
6
7
8
9
10
# ⚠️ 滑动节奏踩坑（实战验证）
- 滑动间隔 < 2s 会"橡皮筋"：页面只滑出 1/4 即回弹，切换不提交（150 次尝试仅 11 次生效）
- 2s/次 ≈ 人类提交极限；客诉"29 次/min ≈ 2.07s/次"与此吻合
- 高频驱动配方：
uinput -T -m ... 500+sleep 1.2（≈37/min，每次都提交）
# 9. 端口转发
hdc fport tcp:8100 tcp:8100 # host:8100 → device:8100（≈ adb forward）
hdc rport tcp:8100 tcp:8100 # 反向（≈ adb reverse）
hdc fport ls # 列出转发任务
hdc fport rm tcp:8100 tcp:8100 # 删除
# 节点格式：tcp:<port>、localfilesystem:<sock>、localabstract:<sock>、jdwp:<pid>、ark:pid@tid@Debugger
1
2
3
4
5
6
2
3
4
5
6
典型场景：转发 ArkTS Inspector / WebView devtools / 本地 server 联调。
# 10. 截屏与布局
hdc shell snapshot_display -f /data/local/tmp/s.jpeg # 系统级截屏
# -i displayId -w/-h 缩放 -t 类型
hdc file recv /data/local/tmp/s.jpeg .
1
2
3
2
3
# 11. 调试支持
hdc jpid # 列出 JDWP 可调试进程 pid
hdc track-jpid [-a|-p] # 持续跟踪调试进程（-a 含 release 进程）
hdc shell -b <bundle> <cmd> # 在 debug 应用目录内执行命令
hdc bugreport bug.zip # 全量诊断信息打包
hdc keygen debug.key # 生成调试公私钥对
hdc shell param get const.product.name # 系统参数（≈ getprop）
hdc shell param get const.ohos.apiversion # API 版本
hdc shell param set <key> <value> # 设置参数（≈ setprop）
1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
# 12. hdc ↔ adb 速查表
| 作用 | adb | hdc |
|---|---|---|
| 设备列表 | adb devices | hdc list targets |
| 指定设备 | adb -s <serial> | hdc -t <connectKey> |
| 无线连接 | adb tcpip 5555 + adb connect | hdc tmode port 5555 + hdc tconn |
| 安装 | adb install -r | hdc install -r（或 bm install -p） |
| 卸载 | adb uninstall | hdc uninstall（或 bm uninstall） |
| 推/拉文件 | adb push / adb pull | hdc file send / hdc file recv |
| 日志 | adb logcat | hdc shell hilog |
| 服务转储 | dumpsys <service> | hidumper -s <SA> -a '<args>' |
| 内存 | dumpsys meminfo <pid> | hidumper --mem <pid> |
| 系统属性 | getprop / setprop | param get / param set |
| 启动应用 | am start -n | aa start -b <bundle> -a <ability> |
| 强停 | am force-stop | aa force-stop <bundle> |
| 包查询 | pm list packages / pm dump | bm dump -a / bm dump -n |
| 点击/滑动 | input tap / input swipe | uinput -T -c / -m（或 uitest uiInput） |
| 截屏 | screencap | snapshot_display / uitest screenCap |
| 端口转发 | adb forward | hdc fport |
| 重启 | adb reboot | hdc target boot |
| root | adb root | hdc smode |
| 诊断报告 | adb bugreport | hdc bugreport |
# 13. 实战配方（真实排查案例沉淀）
# 突发滑切驱动（≈37/min，每次提交）
hdc shell "i=0; while [ \$i -lt 150 ]; do uinput -T -m 612 2100 612 600 200 >/dev/null 2>&1; i=\$((i+1)); sleep 1.2; done"
1
# 选集面板跳回续航（三连点击）
hdc shell "uinput -T -c 328 2622; sleep 1; uinput -T -c 98 1374; sleep 1; uinput -T -c 163 1537"
1
# RS 内存四通道采样（3s 间隔轮询，落 CSV 看趋势）
PID=$(hdc shell "pidof com.example.myapp" | tr -d '\r')
hdc shell "hidumper -s RenderService -a 'dumpExistPidMem $PID'" # RS 记账（主通道）
hdc shell "hidumper -s RenderService -a 'dumpGpuMem'" # GPU + 驱动级显存
hdc shell "hidumper -s RenderService -a 'allSurfacesMem'" # surface 队列数
hdc shell "hidumper --mem $PID" # PSS 对照
1
2
3
4
5
2
3
4
5
# 踩坑清单（每条都交过学费）
- host 循环 = 灾难：
for i in ...; do hdc shell ...; done每次 ~9s 往返开销，循环必须放设备端（§4） - uitest 慢：走无障碍树，负载下 ~8.6s/次；高频场景只配用来
dumpLayout定位坐标 - 滑动 <2s 橡皮筋：滑出 1/4 即回弹、切换不提交；2s/次是人类提交极限
- PSS 看不到 RS 记账：GPU 渲染内存问题必须用
hidumper -s RenderService，PSS 只是 app 进程侧口径 $转义：host 双引号内\$i、\$((i+1))，否则被本机 shell 提前展开成空串- pid 里有
\r：hdc shell输出带 CR，拼接命令前先tr -d '\r'
# 14. 自查命令的方法（授人以渔）
hdc help verbose # hdc 自身全量命令
hdc shell <工具名> -h # hilog -h / hidumper -h / bm help / aa help
hdc shell hidumper -ls # 先看有哪些系统服务可 dump
hdc shell "hidumper -s <SA> -a '-h'" # 很多服务支持 -h 查看自己的 dump 参数
hdc shell uinput # uinput 无 -h，无参运行即打印 usage
1
2
3
4
5
2
3
4
5
上次更新: 2026/10/09, 15:51:11