简介鸿蒙HDC工具包面向鸿蒙应用开发者与测试人员提供与鸿蒙终端设备交互所需的命令行工具集功能定位类似Android平台的adb可用于连接、管理设备并执行安装、卸载、查看系统信息等操作。资源包共30个文件约14.08MB以8个exe可执行文件为主涵盖设备交互、反汇编分析、接口定义生成与性能监控等用途同时包含14个json配置与校验文件、3个jar打包签名工具、2个pem证书、1个p12密钥库、1个dll动态库及1个说明文档覆盖开发调试、应用签名与资源管理的常见环节。目前已有3865人学习下载。借助这套工具开发者可快速搭建鸿蒙设备调试环境完成应用打包、签名、安装与性能分析并通过反汇编与接口定义工具排查问题、优化应用适合需要系统掌握鸿蒙设备调试流程的中高级开发者参考使用。1. 鸿蒙 hdc 工具包从设备连接到自动化调试的完整落地如果你正在做鸿蒙应用开发大概率遇到过这样的场景设备插上电脑IDE 识别不到或者想批量安装十几个测试包只能一个个手动点。这时候你需要的是 hdc——HarmonyOS Device Connector鸿蒙生态里的设备调试桥接工具。它类似于 Android 生态里的 adb负责主机与鸿蒙设备之间的命令下发、文件传输、应用安装和日志抓取。这份工具包把 hdc 的常用命令、环境配置脚本和几个批量操作模板整理在一起适合刚接触鸿蒙设备调试的新手快速跑通链路也适合已经上手但想把手动操作脚本化的熟手。下面从工具结构、环境搭建、核心命令到避坑一步步拆开讲。2. hdc 工具包结构拆解与环境搭建2.1 工具包里到底有什么拿到这份工具包后先别急着双击运行。我一般会先看目录结构确认版本和依赖。典型的 hdc 工具包包含以下内容文件/目录作用备注hdc.exe/hdc主程序设备连接与命令执行Windows 下为 exeLinux/macOS 为可执行文件hdc_std标准版 hdc部分设备需要与 hdc 功能类似协议版本不同libusb-1.0.dllUSB 通信依赖库Windows 下缺失会导致设备无法识别config目录存放设备授权与端口配置首次连接后生成scripts目录批量安装、日志抓取等脚本模板工具包附带的实用脚本README.md版本说明与基础命令示例建议先扫一眼版本号工具包本身不区分“安装版”和“绿色版”解压后配置环境变量即可使用。需要注意的是hdc 的版本要和设备系统版本匹配版本差异过大时会出现“设备已连接但无法执行命令”的情况。2.2 环境变量配置与设备连接Windows 下配置 hdc 环境变量我习惯用命令行方式比图形界面点来点去更可控。以下步骤在 PowerShell 中执行# 假设工具包解压到 D:\tools\hdc # 将 hdc 所在目录加入当前用户 PATH $hdcPath D:\tools\hdc $currentPath [Environment]::GetEnvironmentVariable(Path, User) if ($currentPath -notlike *$hdcPath*) { [Environment]::SetEnvironmentVariable(Path, $currentPath;$hdcPath, User) Write-Host 已添加 hdc 到 PATH请重启终端生效 } else { Write-Host hdc 已在 PATH 中 } # 验证配置 hdc version这段脚本的逻辑是先检查用户级 PATH 中是否已包含 hdc 目录避免重复添加然后通过 .NET 方法写入环境变量不需要管理员权限。执行后需要新开一个终端窗口否则 PATH 不会刷新。hdc version能正常输出版本号说明环境变量配置成功。设备连接分两种方式USB 直连和网络连接。USB 直连时设备需要开启“开发者模式”和“USB 调试”。连接后执行# 查看已连接设备列表 hdc list targets # 如果设备未授权会显示 unauthorized # 此时需要在设备屏幕上点击“允许调试”网络连接适用于设备不在手边的情况前提是设备和电脑在同一局域网# 设备端先开启网络调试端口默认 5555 # 然后在电脑端连接 hdc tconn 192.168.1.100:5555 # 连接成功后再次查看设备列表 hdc list targetstconn是 TCP connect 的缩写后面跟设备 IP 和端口。网络连接的好处是摆脱线缆束缚但要注意设备 IP 变化后需要重新连接。我一般会在路由器里给测试设备绑定静态 IP省去每次查 IP 的麻烦。2.3 常见连接失败排查设备连不上是最高频的问题按以下顺序排查能覆盖九成情况检查 USB 线有些线只能充电不能传数据换一根确认。检查设备授权hdc list targets显示 unauthorized 时看设备屏幕是否有弹窗。检查驱动Windows 设备管理器里看是否有未识别设备需要手动安装驱动。检查端口占用hdc 默认使用 8710 端口如果被其他进程占用会连接失败。重启 hdc 服务hdc kill后重新执行hdc start相当于给连接链路来一次“重启”。提示如果以上都试过还是不行把设备重启一次。鸿蒙设备的调试授权有时会进入玄学状态重启能解决大部分莫名其妙的问题。3. hdc 核心命令与批量操作实战3.1 应用安装与卸载hdc 最常用的功能就是安装和卸载应用。单次安装很简单# 安装应用-r 表示替换已存在的应用 hdc install -r entry-default-signed.hap # 卸载应用后面跟包名 hdc uninstall com.example.myapp-r参数在迭代开发时特别有用不需要先卸载再安装。但要注意如果新旧包的签名不一致-r会失败这时候需要先卸载再安装。包名可以通过hdc shell bm dump -a查看设备上所有已安装应用的包名。批量安装是工具包里脚本模板的核心场景。假设你有一个存放多个 hap 文件的目录需要一次性安装到设备#!/bin/bash # batch_install.sh - 批量安装指定目录下的所有 hap 文件 # 用法./batch_install.sh /path/to/hap/dir HAP_DIR$1 if [ -z $HAP_DIR ]; then echo 请指定 hap 文件目录 exit 1 fi # 检查设备连接 DEVICE_COUNT$(hdc list targets | grep -c device) if [ $DEVICE_COUNT -eq 0 ]; then echo 未检测到已连接设备请检查连接 exit 1 fi # 遍历目录下所有 hap 文件 for hap_file in $HAP_DIR/*.hap; do if [ -f $hap_file ]; then echo 正在安装$(basename $hap_file) hdc install -r $hap_file if [ $? -eq 0 ]; then echo 安装成功$(basename $hap_file) else echo 安装失败$(basename $hap_file) fi fi done echo 批量安装完成脚本逻辑分三步先校验参数和设备连接状态避免空跑然后遍历目录下所有.hap文件每个文件安装后检查退出码成功和失败分别输出不同提示。$?是上一条命令的退出码0 表示成功。这个脚本在 Linux 和 macOS 下可以直接运行Windows 下需要用 Git Bash 或 WSL。3.2 文件传输与日志抓取hdc 的文件传输命令是file send和file recv方向是相对于电脑而言的# 从电脑发送文件到设备 hdc file send ./config.json /data/local/tmp/config.json # 从设备接收文件到电脑 hdc file recv /data/log/faultlog/faultlogger/ ./crash_logs/发送文件时目标路径需要有写入权限。/data/local/tmp/是常用的临时目录权限相对宽松。接收文件时如果目标路径是目录hdc 会把源文件复制到该目录下。日志抓取是排查线上问题的关键手段。hdc 提供了hilog命令来查看系统日志# 实时查看日志-T 表示按 tag 过滤 hdc shell hilog -T MyAppTag # 将日志输出到文件 hdc shell hilog full_log.txt # 按日志级别过滤只显示 Error 及以上 hdc shell hilog -L E-T参数按 tag 过滤适合只看自己应用的日志。-L参数按级别过滤E 表示 ErrorW 表示 WarnI 表示 InfoD 表示 Debug。实际排查问题时我一般先抓全量日志再用 grep 筛选关键字比直接过滤更不容易漏掉上下文。3.3 设备信息查询与 Shell 命令hdc 可以直接在设备上执行 shell 命令相当于一个轻量级的远程终端# 查看设备系统版本 hdc shell param get const.ohos.apiversion # 查看设备型号 hdc shell param get const.product.model # 查看当前运行的应用进程 hdc shell ps -ef | grep com.example # 查看内存占用 hdc shell free -m这些命令在写测试报告或排查设备兼容性问题时很有用。param get读取的是系统参数不同鸿蒙版本支持的参数名可能有差异如果读不到值可以先执行hdc shell param dump查看所有可用参数。工具包里的scripts目录还附带了一个设备信息采集脚本执行后会生成一份包含系统版本、内存、存储、已安装应用列表的文本报告。这个脚本在批量测试时特别省事不用一台台设备手动查。4. hdc 使用避坑与常见问题排查4.1 设备显示 offline 或 unauthorized现象hdc list targets显示设备状态为 offline 或 unauthorized无法执行任何命令。原因offline 通常是 hdc 服务与设备端协议不匹配或者 USB 连接不稳定unauthorized 是设备端没有确认调试授权。解决unauthorized 直接在设备屏幕上点击“允许”即可。offline 需要先hdc kill结束服务再hdc start重启然后重新插拔 USB。如果还是 offline检查 hdc 版本是否与设备系统版本匹配版本差异过大时需要更换工具包中的 hdc 主程序。4.2 安装应用时报错“签名不一致”现象执行hdc install -r时提示签名不一致安装失败。原因设备上已安装的应用使用了不同的签名证书-r替换安装要求新旧包签名一致。解决先执行hdc uninstall 包名卸载旧应用再执行hdc install安装新包。如果不想丢失应用数据需要确保新旧包使用同一套签名证书。在团队协作中签名证书通常由专人管理不要随意更换。4.3 文件发送失败提示“Permission denied”现象hdc file send发送文件到设备时提示权限不足。原因目标路径对当前用户不可写。鸿蒙系统对系统目录有严格的权限控制。解决将文件发送到/data/local/tmp/目录这是调试用的临时目录权限相对宽松。如果需要发送到其他目录需要先通过hdc shell获取 root 权限或修改目录权限。但要注意正式版设备通常不允许 root这种情况下只能发送到允许的目录。4.4 日志抓取时中文乱码现象hdc shell hilog输出的日志中中文显示为乱码。原因终端编码与设备日志编码不一致Windows 终端默认使用 GBK 编码而设备日志使用 UTF-8。解决在 Windows 终端中执行chcp 65001切换到 UTF-8 编码再执行日志命令。或者在 PowerShell 中设置$OutputEncoding [System.Text.Encoding]::UTF8。如果使用 Git Bash 或 WSL默认就是 UTF-8不会有这个问题。4.5 网络连接频繁断开现象hdc tconn连接成功后过一段时间自动断开需要反复重连。原因设备休眠导致网络断开或者路由器对长时间空闲连接有回收策略。解决在设备端关闭休眠策略保持网络常连。如果设备支持可以设置“充电时不休眠”。另外在电脑端写一个定时重连脚本每隔几分钟检查一次连接状态断开时自动重连。工具包里的scripts目录有一个keep_alive.sh模板就是做这个用的。5. 进阶技巧用 hdc 做自动化回归测试单次调试用 hdc 命令就够了但如果要做自动化回归测试需要把 hdc 命令串成完整的测试流程。我一般会写一个 Python 脚本用subprocess调用 hdc实现“安装-启动-操作-抓日志-卸载”的闭环。import subprocess import time import os HDC hdc # 已配置环境变量直接调用 PACKAGE com.example.myapp HAP_PATH ./entry-default-signed.hap LOG_DIR ./test_logs def run_hdc(args, timeout30): 执行 hdc 命令并返回输出 try: result subprocess.run( [HDC] args, capture_outputTrue, textTrue, timeouttimeout ) return result.stdout.strip(), result.returncode except subprocess.TimeoutExpired: return , -1 def check_device(): 检查设备连接状态 output, code run_hdc([list, targets]) if device not in output: raise RuntimeError(设备未连接) return True def install_app(): 安装应用 output, code run_hdc([install, -r, HAP_PATH], timeout60) if code ! 0: raise RuntimeError(f安装失败{output}) print(安装成功) def start_app(): 启动应用主 Ability output, code run_hdc([ shell, aa, start, -a, EntryAbility, -b, PACKAGE ]) if code ! 0: raise RuntimeError(f启动失败{output}) print(启动成功) def capture_log(duration10): 抓取指定时长的日志 os.makedirs(LOG_DIR, exist_okTrue) log_file os.path.join(LOG_DIR, flog_{int(time.time())}.txt) with open(log_file, w, encodingutf-8) as f: proc subprocess.Popen( [HDC, shell, hilog], stdoutf, stderrsubprocess.STDOUT ) time.sleep(duration) proc.terminate() print(f日志已保存{log_file}) return log_file def uninstall_app(): 卸载应用 run_hdc([uninstall, PACKAGE]) print(卸载完成) if __name__ __main__: check_device() install_app() start_app() capture_log(10) uninstall_app() print(回归测试流程完成)这段脚本的核心思路是用subprocess.run同步执行 hdc 命令用subprocess.Popen异步抓取日志。timeout参数防止命令卡死capture_output捕获输出用于判断执行结果。aa start是鸿蒙的 Ability 启动命令-a指定 Ability 名称-b指定包名。实际跑回归时我会把这个脚本接入 CI 流水线每次代码提交后自动触发。设备用 USB Hub 集中管理每台设备跑一个测试实例。这里有个血泪经验不要在一台设备上并行跑多个测试脚本hdc 的命令通道会互相干扰导致安装或启动随机失败。一台设备同一时间只跑一个测试任务这是最稳的做法。从那以后我每次写自动化脚本都会在开头强制检查设备连接状态并且给每个 hdc 命令加上超时时间。看起来是多写了几行代码但省去了后面排查“为什么脚本卡住不动”的时间。希望帮到你。本文还有配套的精品资源点击获取