搞开发这几年我养成了一个习惯不管用什么工具链第一件事不是翻文档而是先把它的命令行工具摸一遍。命令行是效率的底线图形界面再方便等你要写脚本、做自动化、批量处理的时候终究还得回到终端。hdcHarmonyOS Device Connector就是这样一款工具它是 HarmonyOS 开发者和测试人员连接设备、调试应用、抓取日志的“总开关”。说白了hdc 就是安卓开发里 adb 在 HarmonyOS 世界的对应物但又不能完全画等号。它的定位是设备连接器核心功能覆盖设备管理、应用安装卸载、文件传输、日志抓取、Shell 执行、性能调优等。日常开发中无论是给真机装一个 HAP 包还是想看应用崩溃时的 hilog 日志或者往设备里 push 一个配置文件几乎都离不开它。这篇博文不打算做成官方文档的复读机而是把我实际用了一年多 hdc 的常用命令、踩过的坑、总结出的技巧一次讲清楚争取让你看完就能直接上手干活。1. 核心思路为什么我建议你先掌握 hdc 而非图形工具不少刚从 DevEco Studio 入门的朋友习惯用 IDE 里集成的可视化面板完成设备管理和日志查看。这当然没问题但一旦进入批量处理、持续集成、自动化测试、远程调试这类场景图形界面就明显不够用了。我强烈建议你花一个下午把 hdc 的基础命令过一遍原因有三点。第一hdc 是很多自动化能力的地基。你在 DevEco Studio 里看到的“一键安装 HAP”“一键抓取日志”“一键截图”底层调用的其实就是 hdc 命令。理解了这条命令行就等于理解了 IDE 图形操作背后的执行逻辑出问题时也能更快定位是设备问题、命令问题还是 IDE 的封装问题。第二hdc 是跨平台的统一入口。日常开发你可能在 Windows 上用 DevEco Studio但写自动化脚本可能跑在 Linux 服务器上。hdc 在这些平台上都有对应版本命令语法几乎一致。我常用的套路就是本地 Windows 手动排查服务器 Linux 跑回归脚本两者配合效率高出不止一截。第三hdc 能帮你“看见”更多细节。图形工具往往只展示整理后的结果而命令行直接输出原始数据。比如查看进程内存、查询设备网络状态、执行任意 shell 指令这些操作在图形界面上绕好几个弯都未必能做在终端里一条命令搞定。一句话总结我的观点hdc 不是 IDE 的替代品而是你从“会用工具”走向“理解工具”的必经之路。尤其是做系统开发、应用稳定性测试、性能优化的朋友hdc 熟练度应该是基本功。1.1 hdc 的版本选择与获取方式先解决工具从哪来的问题。hdc 并不是单独发布的开源工具而是随 HarmonyOS SDK 一起分发的。一般来说你安装好 DevEco Studio 并配置了 SDK 之后hdc 就躺在 SDK 目录下的某个固定路径里。常见的路径大致是这样# Windows 环境注意具体版本号可能不同 %LOCALAPPDATA%\Huawei\Sdk\HarmonyOS-NEXT-DB1\toolchains\hdc.exe # Linux 环境 ~/Huawei/Sdk/HarmonyOS-NEXT-DB1/toolchains/hdc # macOS 环境 ~/Library/Huawei/Sdk/HarmonyOS-NEXT-DB1/toolchains/hdc如果找不到最简单的方法是在 DevEco Studio 的 SDK Manager 里查看 SDK 安装路径然后顺着目录找 toolchains 文件夹。Linux 服务器上如果只装了命令行 SDK 而没有 IDE那可以单独下载 command line tools 包里面同样包含 hdc。我还见过一种“野生”做法从某个项目包里直接拷 hdc 二进制出来用。这种做法在版本匹配不严格的情况下确实能跑但我不推荐因为 hdc 和设备端的通信协议会随系统版本更新老版本 hdc 可能连不上新版本设备或者缺少新功能。最稳妥的做法是用与设备系统版本匹配的 SDK 自带的 hdc开发机上多版本 SDK 共存也不冲突用时把对应 toolchains 目录加入 PATH 即可。1.2 hdc 与 adb 的核心差异别踩惯性思维的坑如果你有过 adb 的使用背景学 hdc 会很快但越是有经验越要警惕几个关键差异否则很容易被惯性思维坑到。第一个差异是服务启动方式。adb 需要在主机上跑一个 adb server通过adb start-server启动hdc 也有类似机制但它默认用的是端口 8710而且很多时候会自动拉起 daemon 进程。你不需要每次都手动启停但要知道hdc start和hdc kill的存在遇到连接异常时第一反应应该是重启服务而不是重启电脑。第二个差异是命令命名不完全一致。比如 adb 的adb shell在 hdc 里写作hdc shell但设备的安装命令从 adb 的adb install变成了 hdc 的hdc install这在语义上没毛病。然而hdc 里很多子命令的参数和输出格式并不照搬 adb拿hdc shell进去后部分 shell 工具和文件系统布局也与传统 Linux 有一些差别千万别把 adb 时代写的脚本拿过来直接跑。第三个差异是 hilog 取代了 logcat。日志抓取这块差异最大HarmonyOS 使用 hilog 作为日志系统命令格式、过滤方式、输出字段都不同。这一点后面我用专门一节展开讲因为它实在太常用了。搞清楚这三点你就不会带着 adb 的旧地图在 hdc 的新世界里迷路。接下来进入正题把最常用的命令分类梳理一遍。2. 环境准备hdc 启动、连接与设备管理速查工欲善其事必先利其器。这一节我把从环境准备到设备连接的基础链路讲透掌握了这些后面所有操作才有落脚点。2.1 PATH 配置与 hdc 版本确认拿到 hdc 之后第一步把它加进 PATH。Windows 用户可以在“系统属性-环境变量”里把 toolchains 目录路径追加到 PathLinux/macOS 用户推荐在 shell 配置文件里追加export PATH$PATH:~/Huawei/Sdk/HarmonyOS-NEXT-DB1/toolchains配置好后新开一个终端验证hdc -v能输出版本号就说明环境通了。我习惯顺手跑一条hdc list targets看看当前有没有设备在线这条命令使用频率极高它同时也是排查连接问题的一把钥匙。2.2 设备连接与状态查看HarmonyOS 真机连接开发机通常有两种方式USB 数据线直连和 Wi-Fi 无线连接。USB 连接是最稳的方式。首次连接时手机端会弹出“允许 USB 调试吗”的授权对话框记得勾选“始终允许”否则每次重连都要手动确认一次在自动化场景下会直接卡住。确认授权后执行hdc list targets如果输出了一行类似1234567890 device的信息说明设备已就绪。这里device状态表示设备在线可操作如果出现offline状态优先检查数据线是否支持数据传输很多线只能充电、USB 调试是否开启、授权弹窗是否被误点成“拒绝”。无线连接的配置稍微多一点。先把设备通过 USB 连上然后执行# 查看设备 IP需设备连接 Wi-Fi hdc shell ifconfig # 启动无线连接服务指定端口 hdc tconn ip地址:端口比如设备 IP 是 192.168.1.100端口一般用 5555那命令就是hdc tconn 192.168.1.100:5555。无线连接调试在办公场景下非常实用设备可以放在工位上充电人坐在座位上敲命令省去反复插拔线的麻烦。但无线连接稳定性受网络环境影响较大如果跑大批量安装任务时老断老老实实回到 USB 线。2.3 多设备管理target 选择是命令的“后置开关”一个值得注意的细节是hdc 的大多数命令都支持指定目标设备。当你同时插着多台手机或平板时直接执行hdc install会报错因为系统不知道你要操作哪一台。正确姿势是给相关命令加-t参数# 指定设备序列号sn号执行操作 hdc -t 1234567890 install entry-default-signed.hap hdc -t 1234567890 shell hdc -t 1234567890 hilog序列号从哪里找就是上面hdc list targets输出的第一列。多设备并行调试时我给每台设备贴了便签写上 sn 后四位命令行里一眼就能认出来省得每次现查。2.4 服务异常时的重启三板斧连接类问题里最烦人的就是 hdc 服务状态异常。症状通常是hdc list targets一直空白或者设备的在线状态在 online/offline 之间反复横跳。这时候先别慌按顺序执行三条命令# 1. 杀掉 hdc 服务 hdc kill # 2. 重新启动 hdc 服务 hdc start # 3. 再查设备列表 hdc list targets90% 的怪问题这么一搞都能恢复。如果还不行拔掉 USB 线重启设备端 USB 调试开关或者在开发机上关掉占用 8710 端口的进程后再试。记住这个排查顺序先杀服务、再查线材、最后看授权能省下大量无效折腾的时间。3. 文件传输与 HAP 包安装日常使用频率最高的两类操作对应用开发来说把一个 HAP 包装进设备、把设备上的文件拉出来这两件事占了日常操作的一半以上。这一节把相关命令拆透。3.1 安装 HAPhdc install 的参数细节HAP 是 HarmonyOS 的应用安装包它在设备上的安装命令是hdc install entry-default-signed.hap这在所有 hdc 命令里应该是最常用的一条。如果包已经存在于设备某个目录也可以指定设备上的路径hdc install /data/local/tmp/entry-default-signed.hap这条命令从设备端路径安装的好处是可以先批量把 HAP push 到设备再依次安装减少 USB 传输次数在大规模测试机部署时效率提升非常明显。带参安装的场景也很常见。比如你需要在安装时保留应用数据用-r参数hdc install -r entry-default-signed.hap这在覆盖安装测试场景下特别好用开发改一行代码重新打包直接-r装上去应用之前的登录状态和数据都还在省得每次从头配置环境。如果以后要做自动化分发可以像这样用循环批量安装for hap in *.hap; do hdc install $hap; done有人可能会问hdc install支不支持从网络 URL 安装我实测下来 hdc 本身没有直接拉取网络包的能力需要自己先下载到本地再安装。自动化流水线里建议搭配 curl 或 wget 先下载再走本地安装这步。3.2 卸载 HAP查找包名的两种方式卸载之前得先拿到应用的包名。HarmonyOS 应用包名的格式类似com.example.myapplication常见两种查法。方法一直接列出当前所有第三方应用包名hdc shell bm dump -abm是 HarmonyOS 的包管理工具输出内容较多时可以过滤一下hdc shell bm dump -a | grep com.example方法二如果你在设备上打开了应用可以查当前前台进程包名hdc shell bm dump -l | grep # 输出包含当前已安装应用的 bundle name拿到包名后执行hdc uninstall com.example.myapplication注意hdc uninstall后面跟的是包名不是 HAP 文件名这个别搞混。我用 shell 脚本批量卸载时经常这样写for pkg in com.example.app1 com.example.app2; do hdc uninstall $pkg done3.3 文件推送与拉取本地与设备的数据搬运hdc 文件操作类似于 Linux 的 scp方向明确file send是从本地传向设备file recv是从设备拉向本地。# 本地文件推送到设备 hdc file send ./local_config.json /data/local/tmp/config.json # 从设备拉取文件到本地 hdc file recv /data/local/tmp/log.txt ./logs/log.txt # 从设备拉取整个目录到本地 hdc file recv /data/local/tmp/logs ./backup_logs这里有几条实战经验值得记下来。第一设备的/data/local/tmp是应用测试常用的临时目录大家约定俗成把测试用文件放在这里权限相对宽松应用也常有权限读取。第二向设备发送目录时目标路径要写到具体目录名否则可能直接把目录本身推成了文件。比如hdc file send ./mydir /data/local/tmp/mydir而不是hdc file send ./mydir /data/local/tmp。第三拉取设备日志、数据库文件这类持续变化的文件时最好先停掉相关应用避免拿到半截文件。我在抓取崩溃现场时就会先执行hdc shell aa force-stop com.example.app确保文件一致后再落盘。第四文件操作在大文件场景下可能会慢别盯着终端发呆可以先压成 tar 包再传。比如# 在设备上打包指定目录 hdc shell tar -czf /data/local/tmp/data.tar.gz -C /data/app data # 再把包拉回本地 hdc file recv /data/local/tmp/data.tar.gz ./这个组合拳在处理设备上几百 MB 的数据时效果拔群比直接拉一堆零散小文件快得多。3.4 截图与录屏测试报告和远程协作的刚需测试过程中总要截图留痕hdc 有专门的截图命令hdc shell snapshot_display -f /data/local/tmp/screen.png hdc file recv /data/local/tmp/screen.png ./screen.png第一句在设备上生成截图第二句把图拉到本地。多设备对比测试时我会用-t指定不同 sn 循环截图然后统一拉回来贴进对比报告效率比手动在每台设备上操作高一个量级。录屏命令稍微冷门一点但遇到需要复现偶现问题时就很有用hdc shell hidumper --录屏 # 此命令视版本而定有些版本不支持更通用的做法是用hdc shell进入设备后用系统自带的录屏工具但要注意启动和停止命令要配对。这块如果你常做系统级演示值得专门查一下对应版本的具体语法不同 SDK 版本差异较大我这里就不给出可能过时的命令了。4. 日志诊断hilog 的正确打开方式做应用开发最烦的事情不是写代码而是查日志。HarmonyOS 的日志系统是 hilog它的输出量巨大、格式复杂不懂得过滤的话用起来相当痛苦。这一节我把 hilog 的常用姿势全部盘一遍保证你查崩溃日志的效率翻倍。4.1 实时日志查看与过滤三件套tag、level、keyword一个典型的需求场景是我的应用在启动时崩溃了如何快速看到崩溃原因命令的基本形态是进入 hilog 并实时输出hdc shell hilog不加任何参数时它就像一只没头苍蝇一样输出全系统日志信息量巨大到肉眼根本看不过来。所以日常使用必然要带过滤参数。按日志级别过滤比如只想看错误和致命级别hdc shell hilog -e -L ERROR这里的核心逻辑是用-L指定要输出的最低级别常用级别包括 DEBUG、INFO、WARN、ERROR、FATAL。-e表示按表达式过滤其实在你手动加一堆关键词之前先用级别把低价值日志去掉输出立马干净很多。按 tag 过滤是另一种刚需。日志里每个输出点都有自己的 tag比如你的应用模块可以叫MyApp想看这个模块的日志就hdc shell hilog -e -I MyApp-I表示只显示指定 tag 的日志。多个 tag 用逗号隔开hdc shell hilog -e -I MyApp,NetworkModule如果你不记得 tag 但记得关键词直接 grephdc shell hilog | grep OutOfMemory日常排障我基本是“级别优先、tag 辅助、关键词兜底”三件套组合使用。比如查一次网络请求异常我会这样hdc shell hilog -e -L WARN -I NetworkModule | grep timeout这条命令相当于告诉系统只看 NetworkModule 模块的警告级以上日志并且只保留包含 timeout 的行。在自动化脚本里把输出重定向到文件再分析是标准做法。4.2 历史日志与环形缓冲区hilog 默认是在内存环形缓冲区中保留一定量的历史日志设备重启后就没了。如果要查看本次开机以来的全部日志通常的做法是先开启持久化或者在崩溃前就持续抓取。实际开发里我在复现偶现 bug 时会在复现前手动开一个后台抓取任务# 方案 A抓取一段时间后停止 hdc shell hilog -L INFO bug_repro.log 21 # 一段时间后按 CtrlC 停止 # 方案 B用 timeout 限制抓取时长 timeout 120 hdc shell hilog -L INFO bug_repro.log 21方案 B 的timeout 120会自动在 120 秒后结束抓取适合定时采集。用21把标准错误也重定向到同一个文件避免日志分成两个流导致遗漏。有些版本的 hdc/hilog 还支持把日志直接输出成二进制文件再用工具离线解析适合做长时间的稳定性测试留档。这个要看具体 SDK 版本的支持情况不是每个版本都提供同样参数用时随手hdc shell hilog --help确认最保险。4.3 抓取崩溃现场的正确姿势真出问题的时候我最常用的排查流程是这样的先在崩溃复现前开启全面日志hdc shell hilog -L DEBUG crash_all.log 21快速操作设备复现崩溃。停止抓取后搜索关键词FATAL、Exception、Abort、崩溃等grep -nE FATAL|Exception|Signal crash_all.log | tail -50如果崩溃带堆栈把相邻几十行日志一并截出来分析。有一点必须提醒崩溃日志里经常出现多个线程的堆栈交织在一起千万别只截一句话就去搜社区那样很容易误判。正确做法是找到FATAL那一条之后把从崩溃发生到进程退出之间的完整片段都保留下来对照着看各个线程在做什么。5. 远程 Shell 与系统信息查看像操作本地机一样操作设备hdc shell让你能直接进入设备内部的 Linux shell 环境这是排查系统问题的终极手段。注意这里的 shell 并不是完整的 bash很多命令集是精简过的但常用的ps、ls、cat、ifconfig、netstat等基本都在。5.1 应用进程管理与强制停止开发过程中经常需要强制停止某个应用等效于把应用从后台杀掉hdc shell aa force-stop com.example.myapplication这条命令用于重启应用场景特别灵。很多“偶现”的问题杀一次进程再启动复现概率大幅提升。在自动化测试里也可以在每次用例开始前 force-stop保证用例从干净状态启动。查看进程信息hdc shell ps -ef | grep com.example进程的内存占用hdc shell hidumper --memapp com.example.myapplicationhidumper是 HarmonyOS 的系统信息导出工具内容覆盖面极广内存只是冰山一角。遇到性能优化场景hidumper比ps能拿到更多细粒度数据。5.2 网络、CPU 与系统属性查看设备 IPhdc shell ifconfig查看当前 CPU 负载hdc shell top查看系统属性的方式与 Linux 类似但如果是 HarmonyOS 定制过的系统部分属性名可能不同hdc shell param get const.product.name hdc shell param get const.product.model这类信息在做兼容性适配时特别有用比如用户反馈只有某款设备上应用显示异常远程一查设备型号和系统版本很快就能定位是不是适配问题。5.3 提高 shell 操作的效率别名与脚本化单独一条hdc shell命令好敲但每次都要打前缀还是麻烦。我习惯在 shell 配置里写几个 alias把常用命令缩短alias hdhdc alias hlshdc list targets alias hshellhdc shell alias hloghdc shell hilog alias hinstallhdc install alias hpushhdc file send alias hpullhdc file recv配置好之后再干活敲命令的速度提升是实打实的。另外如果你的工作流里反复出现同一串命令直接把它写成脚本。举个例子我常写的一个“快速装包启动”脚本#!/bin/bash # install_and_launch.sh HAP_PATH$1 BUNDLE_NAME$2 ABILITY_NAME$3 hdc install $HAP_PATH hdc shell aa start -a $ABILITY_NAME -b $BUNDLE_NAME调用方式./install_and_launch.sh entry-default-signed.hap com.example.myapplication com.example.myapplication.MainAbility这一串手动操作至少需要两分钟写成脚本后两秒钟搞定而且不会漏步骤。类似的脚本多了之后整个开发和测试的自动化程度自然就上来了。6. 常见问题与排查技巧实录用 hdc 时间久了遇到和听到的问题五花八门。这一节我把出现频率高的几类整理成速查方便你以后直接按图索骥。6.1 连接类问题速查表现象可能原因处理方式hdc list targets无输出服务未启动或端口被占用依次执行hdc kill、hdc start后重试设备显示offlineUSB 线不支持数据传输 / 授权被拒换数据线检查设备端 USB 调试授权弹窗无线连接连不上IP 或端口错误 / 设备休眠确认 IP 和端口默认 5555点亮设备屏幕重试频繁断连USB 接触不良 / 无线网络抖动换数据线或改用 USB 连接检查 Wi-Fi 信号命令提示hdc: command not foundPATH 未配置将 hdc 所在 toolchains 目录加入 PATH 并重开终端多设备时报error: multiple targets未指定目标设备加-t sn号指定设备6.2 权限与路径问题设备端文件操作常常会遇到 permission denied。/data/local/tmp是相对安全的区域但如果你尝试读写/data/app下的某些文件普通进程可能没权限。遇到权限问题先看两处一是当前操作是否通过hdc shell运行在设备侧 shell 用户下二是目标路径的挂载方式和 SELinux 限制。HarmonyOS 设备对应用沙箱的限制比传统 Linux 更严格哪怕你有 shell 权限也不代表能直接读所有应用数据。这时候不要硬扛改用应用自有的调试能力导出数据或者用系统工具生成报告绕过去才是正解。6.3 我的实操避坑经验第一命令里路径别用反斜杠。Windows 下写本地路径习惯用C:\xxx但在 hdc 命令中传给设备侧的路径一律用/data/local/tmp这种格式。混用反斜杠时经常解析错乱干脆统一正斜杠省心。第二先看 hdc 版本再找资料。HarmonyOS 迭代速度快不同版本的 hdc 参数有细微差别。搜索引擎上找到的老博客很可能是旧版语法套用前一定先hdc -v看清版本再决定是否全盘照搬。我踩过最典型的坑就是把旧版hilog参数拿新版设备上用结果参数不认得直接报错。第三脚本里加超时保护。凡是会在脚本里运行的 hdc 命令我都建议用timeout包一层或者加wait逻辑避免因为设备断连导致脚本卡死。比如timeout 10 hdc shell echo alive || echo device not reachable这句如果 10 秒内设备没响应就返回不可达脚本继续往下走不会无限挂起。第四日志文件定期清理。hilog 的输出量大得吓人开启重定向抓半小时可能就产生几个 GB 的文件。测试机上无论本地还是设备侧都要定时清掉旧的日志和临时文件不然磁盘满了之后设备行为会非常诡异。7. 写在最后的一些建议这篇文章里提到的命令都是我日常开发中使用频率极高的涵盖了设备管理、文件传输、安装部署、日志抓取、远程 shell 几个核心模块。hdc 的完整命令远不止这些但掌握了这些核心技能你已经能覆盖绝大多数日常工作场景剩下的可以在遇到具体问题时用hdc help或hdc 子命令 --help慢慢展开。我个人实际操作中的体会是hdc 这类命令行工具真正熟练的标志不是背下多少参数而是形成“快速试错”的直觉。当你面对一台设备时能下意识判断该用哪条命令去探测状态、哪条命令去获取信息这个工具就算真正长在你手上了。最后再分享一个小技巧把你的常用 hdc 命令整理成一个 markdown 速查表放在本地项目仓库的 docs 目录里让团队成员一起维护。命令行工具这种东西代码写多了就会忘细节一份可检索、可更新的速查表比收藏一堆报错帖实用得多。