很多从安卓开发转过来的朋友拿到鸿蒙开发板或者HarmonyOS真机后的第一个动作就是下意识敲adb devices然后发现设备列表是空的。这不是操作不对而是鸿蒙生态用的压根不是adb是hdcHarmonyOS Device Connector。我最初从Android转鸿蒙时也在这上面卡了半天后来把hdc环境搭好、命令摸熟之后才意识到这玩意儿就是鸿蒙开发的生命线。这篇东西不绕弯子直接把我搭建hdc环境的过程、常用命令、以及踩过的坑整理出来给正在折腾鸿蒙开发环境的朋友做个参考。1. 先搞清楚hdc和adb到底什么关系1.1 它不是adb的套壳但设计上有明显继承关系hdc全称HarmonyOS Device Connector翻译过来就是鸿蒙设备连接器负责宿主机你的电脑和设备手机、平板、开发板、模拟器之间的通信。很多教程会告诉你“hdc就相当于鸿蒙版adb”这话方向没错但容易让人误以为hdc就是adb改了名字。实际上hdc是面向OpenHarmony和HarmonyOS重新实现的工具链设备侧的守护进程、协议栈、认证方式都重新做了设计只是在使用习惯上刻意向adb靠拢——命令长得很像端口也是5037。目的很简单就是让从安卓转过来的开发者能零成本上手。1.2 为什么不能用adb操作鸿蒙设备这个问题我在开发群里被问过很多次。原因其实在设备侧HarmonyOS设备上跑的守护进程是hdc daemon监听逻辑和协议格式都跟adb daemon不同adb客户端连上去根本对不上话。另外从安全角度讲鸿蒙对设备连接增加了一层密钥握手和授权校验旧版adb那套机制过不了这一关。所以别浪费时间试adb能不能连鸿蒙设备老老实实把hdc配好才是正路。1.3 hdc的整体架构客户端、服务端、设备端三件套hdc跟adb一样采用了经典的client/server架构理解了这个架构后面排查问题会容易很多hdc client你敲的hdc命令就是客户端负责把指令发出去。hdc server跑在你电脑上的后台服务进程负责任务分发和设备状态管理客户端所有请求都先到它这里。hdc daemon跑在鸿蒙设备上的守护进程收到server转发的指令后去执行把结果一路回传。这套架构带来的一个实际影响是你启动hdc list targets时如果发现server没在运行hdc会自动帮你在后台拉起一个。所以绝大多数情况下你感知不到server的存在但如果端口被占或者server状态异常这套架构的问题就会暴露出来。后面讲踩坑时我会详细说。2. 环境搭建实操三种方式按需自取2.1 方式一装好DevEco Studio就等于装了hdc如果你已经装了DevEco Studio做鸿蒙应用开发那hdc其实已经躺在你的电脑上了只是没加进环境变量你直接在终端敲hdc会提示找不到命令。它藏在SDK的toolchains目录里不同版本路径略有差异大致在你安装DevEco Studio的目录/sdk/default/openharmony/toolchains/hdcWindows下大概率是hdc.exemacOS和Linux下是hdc。先找到这个文件把它的目录记下来后面配置环境变量时用得上。DevEco Studio每升级一次hdc版本也会跟着更新用这种方式的好处是版本跟IDE联动不容易出现hdc和SDK版本不匹配的问题。2.2 方式二单独下载hdc命令行工具包如果只想用命令行、不想装全家桶或者你是给CI服务器配环境那单独下command-line-tools更合适。鸿蒙官网的开发者页面里能找到Command Line Tools下载入口选对应你操作系统的包即可。下载解压后hdc同样是在toolchains目录下。这种方式的适用场景很典型我见过不少做自动化测试的团队测试机纯净系统上只装了hdc相关组件配合鸿蒙真机构建了一套命令行驱动的测试环境轻量干净出问题了也好排除变量。另外像小熊派这类开发板用户往往也没装完整IDE拿单独的工具包就够用了。2.3 方式三自己编或者拿系统镜像自带的hdc还有一条路是源码编译OpenHarmony的代码库里本身就包含hdc的源码如果你是自己编译的OpenHarmony系统镜像构建产物里会带上对应的hdc工具位置通常在out/版本号/linux_x86_64/toolchains/之类的地方。这种方式适合系统定制玩家普通应用开发基本用不上不过知道有这么回事遇到问题时思路会更宽。顺带提醒一句hdc这个工具有时候会被安全软件误判因为它的能力和adb一样强能安装应用、执行shell命令、读写文件。如果你下载后被杀毒软件拦截大概率是误报添加信任即可但前提是你确实是从官方渠道下载的。2.4 环境变量配置Windows、macOS、Linux三种系统一次说清找到hdc文件之后把它所在的目录加进PATH这样在任意目录敲hdc都能用了。Windows打开系统环境变量设置新建或编辑Path变量把toolchains目录追加进去比如D:\Program Files\Huawei\DevEco Studio\sdk\default\openharmony\toolchains。有些人还习惯单独建一个HDC_HOME变量再引用这样后续升级路径变化时只要改一处就行看个人习惯了。macOS / Linux编辑shell配置文件~/.bashrc、~/.zshrc都行加一行export PATH$PATH:$HOME/你的hdc目录然后source ~/.zshrc让配置立即生效。配置完验证是否成功执行hdc -v能输出版本号就说明环境变量没配错。我个人的习惯是验证完再执行一次hdc list targets确保server能正常启动。3. 把设备连上来USB、无线、模拟器全流程3.1 USB连接先开开发者模式再处理驱动和授权环境变量配好只是第一步更关键的是让hdc识别到你的设备。以HarmonyOS手机或平板为例连接前必须在设备上打开开发者模式进“设置-关于本机”连续点击版本号7次直到提示已进入开发者模式然后回到设置里找到“开发者选项”打开“USB调试”开关。用数据线连上电脑后设备上会弹出一个授权对话框显示允许USB调试吗一定要点允许。这个授权机制是双向确认的防止陌生电脑直接控制你的设备。如果用的是开发板有些板子默认就开着调试模式不需要这个步骤。Windows下还有一个坑是驱动。有些非华为品牌的鸿蒙设备或开发板插上后Windows无法正确识别设备管理器里会出现黄色感叹号。解决办法是装对应厂商的USB驱动或者让Windows自动联网搜索驱动。驱动不对的时候现象是设备连上了但hdc list targets始终是空的。连接成功后执行hdc list targets会看到一串设备序列号这就代表通了。3.2 无线连接摆脱数据线束缚的正规姿势日常调app时插根线还好但做自动化测试、长时间抓日志的时候无线连接就舒服多了。hdc支持通过TCP/IP连接设备前提是电脑和设备在同一局域网内。操作分两步第一步先让设备进入无线调试监听状态需要设备用USB连着电脑或者设备本身已通过其他方式连接hdc tconn 192.168.1.100:5555这里的IP是设备的局域网IP在设备的WiFi设置里能看到5555是hdc无线调试的默认端口。执行成功后这台设备就会出现在hdc list targets里。此时可以拔掉数据线了。再强调一个细节无线连接的效率远不如USB传大文件、做长时间录像时延迟和稳定性都有差距建议常规操作用USB偶尔图方便才用无线。3.3 模拟器连接也没问题如果你用的是DevEco Studio自带的模拟器hdc天然就支持。模拟器启动后hdc list targets里会自动出现模拟器设备不需要额外配置。有些第三方模拟器声称支持鸿蒙系统但对hdc的兼容性参差不齐遇到问题优先考虑官方模拟器。3.4 多设备管理用-t参数精准定位连了多台设备时hdc list targets会列出所有设备。此时执行命令如果不指定设备hdc可能报错提示有多个设备解决办法是加-t参数hdc -t 序列号 shell设备序列号就是list targets输出的那串字符串。这个参数在自动化测试中非常有用很多脚本就是靠它来区分真机和模拟器。4. 每天都要用的hdc命令实操4.1 看设备信息和系统参数拿到环境后的第一件事往往是确认系统版本和设备型号。最常用的几条hdc shell param get const.product.name hdc shell param get const.product.model hdc shell param get const.ohos.apiversionparam get是hdc里读取系统参数的入口类似Android的getprop。查CPU架构用hdc shell uname -m查磁盘占用用hdc shell df -h这些命令底层走的是设备上的shell环境用法跟Linux基本一致对搞过Linux的人特别友好。4.2 文件传输hdc file send和recv开发中经常要在电脑和设备之间互传文件比如推送测试配置文件到设备、把设备里抓到的日志拉回电脑。命令格式hdc file send 本地文件路径 设备目标路径 hdc file recv 设备文件路径 本地目标路径例如把电脑上的test.txt推到设备的/data/local/tmp目录hdc file send ./test.txt /data/local/tmp/反过来把设备上的日志拉回电脑hdc file recv /data/log/hilog.log ./一个实操小技巧传大量零散小文件时先打包再传输效率会高非常多。直接传几千个小文件会慢到让人怀疑人生。4.3 安装和卸载应用真机上装测试包、跑冒烟测试靠的就是这几条命令# 安装应用 hdc install /path/to/app.hap # 覆盖安装保留数据 hdc install -r /path/to/app.hap # 卸载应用需要知道包名 hdc uninstall com.example.myapp这里要注意鸿蒙应用安装包的后缀名是.hap或者.app新格式不是安卓的.apk。有一种情况是安装时报错大概率是签名和现有版本不一致需要先卸载再安装或者用-r参数覆盖。卸载时如果不知道包名可以通过hdc shell bm dump -a查看设备上已安装的包列表。4.4 启动并调试应用调试阶段常用的是通过包名和Ability名拉起应用。格式是hdc shell aa start -a Ability名 -b 包名举个例子启动一个应用的MainAbilityhdc shell aa start -a MainAbility -b com.example.myapp对应用开发来说aaAbility Assistant和bmBundle Manager这两个命令组是hdc里跟应用生命周期关系最密切的工具。aa负责管理Ability的启动、停止bm负责管理包的安装卸载。不清楚具体参数时可以分别执行hdc shell aa --help和hdc shell bm --help查看帮助。4.5 抓日志hilog是排查问题的主战场鸿蒙系统的日志系统叫hilog对应安卓的logcat。最基础的用法是实时看日志hdc shell hilog但实际使用时我会先清空缓存日志再复现问题最后一次性倒出日志这样拿到的日志干净有针对性# 先清空旧日志 hdc shell hilog -r # 操作设备复现问题后导出全部日志到文件 hdc shell hilog -x crash.log-x参数会把缓存日志一次性刷出来。如果只想看某个进程的日志可以配合grep过滤hdc shell hilog | grep com.example.myapp真机调试时hilog的输出量很大不习惯的话可以先加-x导出后离线分析。4.6 截图和录屏UI调试和bug反馈场景下截图录屏是刚需# 截图并保存到电脑 hdc shell snapshot_display -f /data/local/tmp/screen.png hdc file recv /data/local/tmp/screen.png ./ # 录屏默认保存到设备 hdc shell screenrecord /data/local/tmp/demo.mp4录屏命令会一直执行直到按CtrlC中断结束后视频文件就在设备上了再file recv拉回来。录屏在复现一些偶现UI问题时很好用。4.7 模拟按键和输入自动化测试里常需要模拟用户操作最常见的几个# 按Home键 hdc shell input keyevent 1 # 按返回键 hdc shell input keyevent 2 # 点亮屏幕 hdc shell input keyevent 3 # 滑动屏幕起点x y 终点x y 时长毫秒 hdc shell input swipe 500 1000 500 100keyevent的键码映射和安卓接近但又不完全一样建议用到哪个先查一下鸿蒙键码定义表凭经验猜容易翻车。5. 环境搭建和使用中的高频踩坑实录5.1 设备死活不出现先排查server和授权hdc list targets结果为空这是新手问得最多的问题。我按排查顺序列一下hdc -v确认hdc能正常运行。设备上开发者模式和USB调试是否都打开了USB调试没开是头号原因。设备连接电脑后有没有弹授权窗口没弹的话重新插拔数据线。数据线是只充电不能传数据的“充电线”换线试试。这个问题出现的频率远超想象。检查设备管理器里有没有感叹号有的话装驱动。5.2 5037端口被占hdc server起不来hdc和adb共用了5037这个默认端口而且在hdc的机制里如果发现已有server在运行就直接复用。问题是你如果先跑了adbadb server很可能占着5037而hdc不一定能正确接管——具体表现就是hdc命令卡住或者报错。最直接的解决办法是把所有相关进程清掉# 杀掉adb server和hdc server adb kill-server hdc kill # 再重新启动 hdc list targets如果还不行Windows下用资源监视器或者netstat -ano | findstr 5037查看是谁占着端口再针对性地结束进程。这个坑在同时搞安卓和鸿蒙开发的环境里极其常见我一度一天遇到好几次。5.3 Linux下连不上开发板USB权限问题在Linux上用hdc连鸿蒙开发板比如小熊派这类经常遇到一个诡异现象hdc list targets啥都没有但lsusb能看到设备。这是因为当前用户没有访问USB设备的权限。解决办法是添加udev规则。先执行lsusb找到设备的VendorID和ProductID形如XXXX:XXXX然后创建规则文件sudo vim /etc/udev/rules.d/51-hdc.rules写入SUBSYSTEMusb, ATTR{idVendor}你的VendorID, ATTR{idProduct}你的ProductID, MODE0666, GROUPplugdev保存后执行sudo udevadm control --reload-rules sudo udevadm trigger重新插拔设备hdc list targets应该就能看到了。另外提醒一点OpenHarmony源码编译环境里其实还提供了一个setup.sh脚本或者文档会说明如何配置udev规则你去翻一下自己下载源码包里的README比网上找的通用规则更对症。5.4 hdc版本和设备系统版本不匹配有时候hdc list targets能列出设备但执行具体命令时报错或者设备端的行为表现异常。这个大概率是hdc版本老旧设备是较新系统。我从DevEco Studio 3.0用到现在的版本期间遇到过至少两次因为hdc太旧导致file send到设备后文件权限不正确的情况。解决办法就是把hdc更新到和系统同期的版本。如果用的是IDE内置hdc升级IDE或SDK即可如果是独立工具包重新下载当前版本即可。6. 从手敲命令到自动化一些提升效率的思路6.1 把常用操作封装成脚本hdc命令本身不难难的是组合起来做事情。比如我本地维护着一个devtools.sh脚本把初始化调试环境的步骤一键打包#!/bin/bash # 初始化鸿蒙调试环境 hdc kill hdc list targets # 清空旧日志 hdc shell hilog -r # 安装指定包 if [ -n $1 ]; then hdc install $1 fi # 启动应用 hdc shell aa start -a MainAbility -b $2配合参数执行一条命令完成安装加启动省掉了一堆中间操作。对于频繁做回归测试的人来说这种脚本能省不少时间。6.2 崩溃日志的自动化采集做真机稳定性测试时日志采集是重头戏。我封装过一个简单的采集函数先清日志、跑测试、最后自动导出并打时间戳命名。capture_log() { local tag$1 hdc shell hilog -r # ... 跑测试用例的指令 ... hdc shell hilog -x ./logs/${tag}_$(date %Y%m%d_%H%M%S).log }自动化产出的日志文件按时间戳命名后续分析对照问题时非常方便。如果配合grep再做一级过滤直接抓出FATAL级别的崩溃信息效率还能再上一截。6.3 把hdc集成进CI流水线团队做持续集成时也可以把hdc用起来CI机器上连接着一台或多台鸿蒙真机构建完成后自动安装到设备、跑smoke test、回传结果。关键点有两个一是CI机器上hdc环境要单独配置好不要依赖IDE二是多设备时要善用-t参数区分设备避免同时跑测试时互相干扰。我之前的一套流程是构建产物出现后脚本执行hdc install然后通过hdc shell aa start拉起应用再截图判断启动页是否正常。整个过程不依赖任何图形界面完全是命令行驱动。如果你的测试场景经常要重复跑验证把这一套搭起来相当值得。6.4 一条实用建议给日常命令写个备注清单hdc命令数量不少全记住不现实。我的做法是在本地维护一个hdc-cheatsheet.md按场景分类记录常用命令比如设备管理、文件操作、日志、应用调试各一个区块。遇到不常用的命令时直接查自己的笔记比翻文档快多了。这也是我给所有刚开始接触hdc的同事的第一个建议——别硬记写下来。hdc这个工具用顺了之后会感觉它比adb在某些方面更贴心比如文件传输和日志导出的命令设计得更清晰。刚开始搭建环境时可能觉得处处是坑但把server、授权、驱动这几个关键点理顺之后后面基本就是一路顺畅了。希望我这份实操记录能帮你少走几步弯路。