hdc（HarmonyOS Device Connector）是为开发人员提供的用于调试的命令行工具，通过该工具可以在windows/linux/mac系统上与设备进行交互。
hdc分为三部分：
client：运行在电脑端的进程，开发者在执行hdc命令时启动该进程，命令结束后进程退出。
server：运行在电脑端的后台服务进程，用来管理client进程和设备端的daemon进程之间的数据交互，以及设备发现等。
daemon：作为守护进程运行在设备端，用来响应电脑端server发来的请求。
关系如下图所示：
说明
hdc client在启动时，默认会判断server是否正在运行，如果没有运行则会启动一个新的hdc程序作为server，运行在后台。
hdc server运行时，默认会监听PC的8710端口，开发者可通过设置系统环境变量
OHOS_HDC_SERVER_PORT自定义监听的端口号。
环境准备
hdc工具通过HarmonyOS SDK获取，存放于SDK的toolchains目录下。
（可选）命令行直接执行hdc程序
开发者可通过命令行进入SDK的toolchains目录，在目录中执行hdc相关命令进行调试。
为了方便在命令行中直接执行hdc程序，开发者也可以将hdc程序文件路径添加到操作系统命令搜索路径的环境变量中。
例如，Windows系统可以添加到系统环境变量Path中。
（可选）server监听端口配置
hdc server启动时，默认会监听PC的8710端口，hdc client使用tcp协议通过此端口连接server。如果PC的8710端口已经被使用或者希望使用其他端口，可以通过添加环境变量OHOS_HDC_SERVER_PORT到系统环境变量中来修改server启动时监听的端口号。
例如，添加变量名为：OHOS_HDC_SERVER_PORT，变量值可设置为任意未被占用的端口，如18710。
说明
环境变量配置完成后，关闭并重启命令行或其他使用到HarmonyOS SDK的软件。
hdc命令列表
全局参数
全局参数是指运行部分hdc命令时，可以跟随在hdc后面的参数，例如：
选择指定的设备执行命令，使用-t参数：
hdc -t connect-key shell echo "Hello world"命令列表
说明
全局参数在使用时需要放在命令之前。
基本使用方法
在使用hdc前，请在设备上开启usb调试功能，用usb线连接设备和PC。
查询连接的设备
hdc list targets执行shell命令
hdc shell echo "Hello world"获取帮助
显示hdc相关的帮助信息，命令格式如下：
hdc -h [verbose]
hdc help
返回值：
使用方法：
hdc -h
hdc help
// 显示详细帮助信息
hdc -h verbose
注意事项
使用hdc时如出现异常，可尝试通过hdc kill -r命令杀掉异常进程并重启hdc服务。
如出现
hdc list targets获取不到设备信息的情况，参见设备无法识别章节。
设备连接管理
查询设备列表
显示所有已连接的设备列表，命令格式如下：
hdc list targets [-v]返回值：
使用方法：
hdc list targetshdc list targets -v连接指定的目标设备
连接单台设备时，执行命令无需指定设备标识符；
连接了多台设备时，每次执行命令时需要使用-t参数指定目标设备的标识符，命令格式如下：
hdc -t [connect-key] [command]参数：
说明
connect-key为每个设备唯一的标识符。如果通过usb连接，标识符为序列号；如果通过网络连接设备，标识符为“IP地址:端口号”。
返回值：
说明
返回的错误提示信息后续会调整优化，请勿用于自动化脚本或程序的结果判断。
使用方法：
该方法需要与具体的操作命令搭配使用，下面以shell命令举例：
hdc list targets // 查询已连接的所有目标设备的connect-key
hdc -t [connect-key] shell // -t 后面添加的connect-key需要替换为指定的设备标识符
等待设备正常连接
命令格式如下：
hdc wait // 等待设备正常连接
hdc -t connect-key wait // 等待指定的设备正常连接，connect-key需要替换为指定的设备标识符
返回值：
使用方法：
hdc waithdc -t connect-key wait常见连接场景
USB连接场景
环境确认
连接步骤
PC通过USB连接设备。
查看已连接设备，执行以下命令：
hdc list targets返回值中存在对应设备的标识符，即为usb连接成功。
可以查询到设备后，即可运行设备相关命令和设备进行交互。如果希望不带设备标识符进行USB命令操作，需要确认设备不在tcp连接模式（
hdc list targets查询的设备不包含IP:port形式的连接信息），直接连接即可，例如：hdc shell
TCP连接场景
注意
TCP调试功能尚未稳定，请谨慎用于生产环境。
环境确认
连接步骤
在设备设置界面打开无线调试开关。
记录设备界面显示的监听端口号，记为PORT，用于后面的tcp连接。
通过tcp连接设备（需要事先知道设备IP和打开的PORT），执行以下命令：
hdc tconn IP:PORTIP地址可在设备侧的设置里面查看到，端口号为上一步设备无线调试界面显示的端口号。
查看已连接设备，执行以下命令：
hdc list targets返回值为IP:PORT形式即为连接成功。
如果需要关闭TCP连接模式，可以在设备中关闭无线调试开关。
远程连接场景
远程连接场景是指客户端通过网络远程连接服务端，客户端和服务端在不同的PC运行，服务端连接设备。
远程连接如图所示:
hdc client（客户端）在PC1中运行，hdc server（服务端）在PC2中运行，PC2中的hdc server连接设备。
连接命令
远程连接使用-s参数来指定服务端的网络参数，包括地址和端口号，以确保连接的即时配置，该设置将在当前会话中有效，命令格式如下：
hdc -s [ip]:[port] [command]参数：
返回值：
使用方法：
# 在已有服务进程，且服务进程的网络监听参数为127.0.0.1:8710的环境中，执行查询设备命令
hdc -s 127.0.0.1:8710 list targets
说明
当命令行中明确使用
-s参数指定服务端口时，系统将忽略OHOS_HDC_SERVER_PORT环境变量中定义的端口设置。
连接步骤
服务端配置
服务端通过USB连接到对应的HDC设备后执行以下命令：
hdc kill // 关闭本地hdc服务
hdc -s IP:8710 -m // 启动网络转发的hdc服务
// 其中IP为服务端自身的IP，windows可通过ipconfig查询，unix系统可通过ifconfig查询
// 8710为默认端口号，也可设置为其他端口号如：18710
// 启动后服务端将打印日志
客户端连接
客户端连接需要确保可以连通服务端IP地址，满足前述条件后执行以下命令：
hdc -s IP:8710 [command] // 其中IP为服务端IP，8710为第一步服务端启动时设置的端口号，
// 如果端口号有变化，这里也需要变更。
// command可以为任意hdc可用命令，例如list targetsusb调试和无线调试切换
用于连接模式切换的命令如下表所示：
当前推荐通过设备端的usb调试开关和无线调试开关来控制连接通道的开启和关闭。
打开设备网络连接通道，命令格式如下：
hdc tmode port [port-number]参数：
返回值：
使用方法：
hdc tmode port 1234注意
切换前，请确保条件满足：远端设备与近端PC处于同一网络，且PC可ping通远端设备IP。
如不满足以上条件请勿使用该命令进行切换。
说明
执行完毕后，远端daemon进程将会退出并重启，USB连接将会断开，需要重新连接。
关闭设备网络连接通道，命令格式如下：
hdc tmode port close返回值：
使用方法：
hdc tmode port close说明
执行完毕后，远端daemon进程将会退出并重启，USB连接将会断开，需要重新连接。
通过TCP连接指定的设备，命令格式如下：
hdc tconn [IP]:[port] [-remove]参数：
返回值：
使用方法：
hdc tconn 192.168.0.1:8888hdc tconn 192.168.0.1:8888 -remove // 断开指定网络设备连接
执行交互命令
命令格式如下：
hdc shell [command]参数：
返回值：
使用方法：
hdc shell ps -efhdc shell help -a // 查询全部可用命令应用管理
安装APP package，命令格式如下：
hdc install [-r|-s] src参数：
返回值：
使用方法：
以安装example.hap包为例：
hdc install E:\example.hap卸载应用，命令格式如下：
hdc uninstall [-k|-s] packageName参数：
返回值：
使用方法：
以卸载
com.example.hello包为例：hdc uninstall com.example.hello
文件传输
从本地发送文件至远端设备，命令格式如下：
hdc file send [-a|-sync|-z|-m] localpath remotepath参数：
返回值：
文件发送成功，返回传输成功的结果信息。文件发送失败，返回传输失败的具体信息。
使用方法：
hdc file send E:\example.txt /data/local/tmp/example.txt从远端设备发送文件至本地，命令格式如下：
hdc file recv [-a|-sync|-z|-m] remotepath localpath参数：
返回值：
文件接收成功，返回传输成功的结果信息。文件接收失败，返回传输失败的具体信息。
使用方法：
hdc file recv /data/local/tmp/a.txt ./a.txt
端口转发
PC端支持的端口转发类型：tcp。
设备端支持的端口转发类型：tcp，dev，localabstract，localfilesystem，jdwp，ark。
列出全部转发端口转发任务，命令格式如下：
hdc fport ls返回值：
使用方法：
hdc fport ls设置正向端口转发任务，执行后将设置指定的“主机端口”转发数据到“设备端口”转发任务，命令格式如下：
hdc fport localnode remotenode返回值：
使用方法：
hdc fport tcp:1234 tcp:1080设置反向端口转发任务，执行后将设置指定的“设备端口”转发数据到“主机端口”转发任务，命令格式如下：
hdc rport remotenode localnode返回值：
使用方法：
hdc rport tcp:1234 tcp:1080删除端口转发任务，执行后将指定的转发任务删除，命令格式如下：
hdc fport rm taskstr参数：
返回值：
使用方法：
hdc fport rm tcp:1234 tcp:1080
服务进程管理
启动hdc服务进程，命令格式如下：
hdc start [-r]返回值：
使用方法：
hdc starthdc start -r // 服务进程启动状态下，触发服务进程重新启动说明
当启动hdc服务进程且系统未检测到运行的服务进程时，日志等级的设置优先级如下：若同时指定了-l参数和配置了OHOS_HDC_LOG_LEVEL环境变量，则使用环境变量配置的日志等级；如果仅指定了-l参数，则采用该参数配置的日志等级；若两者均未指定，则服务进程将以默认的LOG_INFO等级启动。
终止hdc服务进程，命令格式如下：
hdc kill [-r]返回值：
使用方法：
hdc killhdc kill -r // 重启并终止服务进程绕过对服务进程的查询步骤，用于快速执行客户端命令，命令格式如下：
hdc -p [command]参数：
返回值：
使用方法：
# 启动后台服务进程 hdc start # 跳过进程查询，直接执行命令 hdc -p list targets说明
在未指定 -p 参数的情况下直接执行 command 命令时，客户端将首先检查本地是否已有运行的服务进程。若系统未检测到运行的服务进程，客户端将自动启动服务进程，并建立连接以传递命令；若系统检测到运行的服务进程，客户端将直接与该后台服务建立连接并下发相应的命令。
使用前台启动模式启动服务进程，命令格式如下：
hdc -m返回值：
使用方法：
# 指定当前服务进程的网络监听参数并启动服务进程 hdc -s 127.0.0.1:8710 -m说明
使用前台启动参数时，可通过附加 -s 参数来指定服务进程的网络监听参数。如果既没有使用 -s 指定网络监听参数，也没有配置环境变量OHOS_HDC_SERVER_PORT配置监听端口，系统将采用默认网络监听参数:127.0.0.1:8710。
在服务进程前台启动模式下，系统默认的日志输出等级设置为 LOG_DEBUG。如需变更日志等级，可通过结合使用 -l 参数来进行相应的调整。
在运行环境中，仅允许单一的服务进程实例存在。若运行环境中已存在一个活跃的后台服务进程，那么尝试在前台启动新的服务进程实例将不会成功。
设备操作
打印设备端的日志信息，命令格式如下：
hdc hilog [-h]参数：
返回值：
使用方法：
hdc hilog显示设备上所有开启了JDWP调试协议的进程的PID，命令格式如下：
hdc jpid返回值：
使用方法：
hdc jpid实时显示设备上开启了JDWP调试协议的进程的PID和应用名，命令格式如下：
track-jpid [-a|-p]参数：
返回值：
使用方法：
hdc track-jpid重启目标设备，命令格式如下：
target boot [-bootloader|-recovery]target boot [MODE]参数：
使用方法：
hdc target boot -bootloader // 重启后进入fastboot模式 hdc target boot -recovery // 重启后进入recovery模式 hdc target boot shutdown // 关机
安全相关命令
生成一个新的秘钥对，命令格式如下：
hdc keygen FILE参数：
使用方法：
hdc keygen key // 在当前目录下生成key和key.pub文件
查询版本号
显示hdc的版本信息，命令格式如下：
hdc -v/version返回值：
使用方法：
hdc -v 或 hdc version
获取客户端与服务进程版本，命令格式如下：
hdc checkserver返回值：
使用方法：
hdc checkserverhdc调试日志
server端日志
指定运行时日志等级
hdc运行时日志等级，默认为LOG_INFO，命令格式如下：
hdc -l [level] [command]参数：
说明
当配置运行时日志级别为6（LOG_LIBUSB）时，将激活libusb相关的增量日志输出，增量日志级别的详细程度高、数据量大，有助于精确诊断服务进程中与USB相关的异常情况。USB相关操作主要由服务进程执行，因此，只有服务进程具备打印增量日志的功能。相应地，客户端侧的日志几乎不包含增量日志信息。
指定运行时日志等级仅适用于当前进程（包括客户端与服务进程），无法更改已存在的进程日志等级。
返回值：
使用方法：
客户端打印LOG_DEBUG级别日志，以执行shell ls为例，命令示例如下:
hdc -l 5 shell ls服务进程前台模式启动指定LOG_LIBUSB级别日志，命令示例如下:
hdc kill && hdc -l 6 -m说明
-m参数指定以前台模式启动服务进程，可以直接观察前台日志输出，按下Ctrl+C退出进程。
服务进程后台启动模式指定LOG_LIBUSB级别日志，命令示例如下:
hdc kill && hdc -l 6 start说明
以后台模式启动，可以在hdc.log中观察日志输出，日志路径可以查看日志获取章节的描述。
日志获取
执行以下命令开启日志获取：
hdc killhdc -l5 start收集到的完整日志存放路径：
日志相关环境变量：
环境变量配置方法：
以下通过配置OHOS_HDC_LOG_LEVEL环境变量为例，配置环境变量值为：5，介绍环境变量配置方法。
设备端日志
开启hilog日志工具，获取对应日志，命令如下：
hdc shell hilog -w start // 开启hilog日志落盘
hdc shell ls /data/log/hilog // 查看已落盘hilog日志
hdc file recv /data/log/hilog // 获取hilog已落盘日志（包含内核日志）
常见问题
设备无法识别
现象描述
命令行执行hdc list targets命令后，返回结果为[empty]。
可通过以下方式排查。
情况一：查看设备管理是否显示HDC设备。
Windows环境：
在设备管理器>通用串行总线设备中是否显示
HDC Device（单一端口设备）或HDC Interface（复合端口设备）。Linux环境：
在命令行执行lsusb,在返回的内容中查看是否有
HDC Device（单一端口设备）或HDC Interface（复合端口设备）。MacOS环境：
使用系统信息或系统概述来查看USB设备，步骤如下：
按住键盘上的Option键，点按菜单。
选取系统信息或系统概述。
在随后出现的窗口中，选择左边的USB。
在随后显示的设备树查看是否有
HDC Device（单一端口设备）或HDC Interface（复合端口设备）。
可采取的解决方法
以上环境如没有显示HDC设备，则说明无法识别设备，可以根据实际场景尝试以下方法：
使用其他USB物理接口。
更换USB数据连接线。
使用其他计算机调试。
设备开启USB调试模式。
设备出现弹窗点击允许调试。
如可通过TCP模式连接，可执行
hdc tmode usb命令恢复USB连接。设备恢复出厂设置。
情况二：存在USB设备，但是驱动损坏，显示"HDC Device"⚠警告图标。
现象描述：该问题常见于Windows环境，现象为设备管理器>通用串行总线设备中，
HDC Device显示为黄标警告，且描述信息为该设备无法正常工作。可尝试重新安装驱动解决，如重新安装驱动无法解决，可以尝试更换USB连接数据线/拓展坞/USB接口。重新安装驱动的方法
打开设备管理器，右键点击存在警告图标的
HDC Device；出现的菜单中点击更新驱动程序；
出现的提示窗口（第1/3个）中，选取浏览我的电脑以查找驱动程序；
出现的提示窗口（第2/3个）中，选取让我从计算机上的可用驱动程序列表中选取；
出现的提示窗口（第3/3个）中，取消勾选显示兼容硬件，选择厂商：WinUSB设备，选择型号：WinUSB设备，选择完成后点击下一步按钮。
情况三：连接设备时出现
[Fail]Failed to communicate with daemon。现象描述：命令行执行hdc相关命令，执行失败返回
[Fail]Failed to communicate with daemon。可能存在以下原因，可参考排查：
hdc或SDK版本与设备不匹配: 如果设备更新到最新版本，可更新hdc或SDK工具至最新版本。
端口被占用：
常见于hdc和hdc_std使用同一端口，同时运行时
OHOS_HDC_SERVER_PORT设置的端口互相冲突（未设置则使用默认端口8710，仍然会冲突），注意只运行其中一个。其他软件占用hdc默认端口也会导致该问题发生。情况四：连接设备时出现
Connect server failed。出现该现象，可能有如下原因：
端口抢占
解决方法如下：
排查自带hdc的软件进程。
包括自带hdc的软件（DevEco Studio、DevEco Testing），如存在请关闭这些软件后再执行hdc相关命令。
查询HDC端口情况。
以设置的
OHOS_HDC_SERVER_PORT为8710端口为例，在不同平台查询命令如下：Unix：
netstat -an |grep 8710Windows:
netstat -an |findstr 8710如存在抢占的软件，可以关闭该软件进程或者更换
OHOS_HDC_SERVER_PORT环境变量为其他端口号。排查未关闭的其他版本
hdc serverWindows：
使用任务管理器>详细信息查询
hdc.exe进程,右键打开文件所在位置，核对位置是否为配置的环境变量中的hdc文件位置，如果不一致，可尝试结束hdc.exe进程(hdc kill或者任务管理器直接结束进程)并重新执行hdc命令。（关闭hdc server后执行hdc命令会重新启动hdc server）Unix：
使用
ps -ef |grep hdc查询hdc后台server进程，核对进程启动位置是否为配置的环境变量中的hdc文件位置，如果不一致，可尝试结束hdc进程(hdc kill或者kill -9 hdc进程的PID)并重新执行hdc命令。（关闭hdc server后执行hdc命令会重新启动hdc server）
注册表异常
解决方法：清理注册表，步骤如下：
同时按下
Win+R键，启动运行工具，输入栏输入regedit打开注册表。注册表地址栏输入以下内容并按下回车，即可进入USB类设备驱动程序的注册表。
计算机\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Class\{88bae032-5a81-49f0-bc3d-a4ff138216d6}找到UpperFilters键，右键修改编辑，备份并清空其中数值数据内容（如清空后无法解决问题可依照备份恢复）。
刷新设备管理器/插拔USB接口/重启计算机。
hdc无法运行
现象描述
使用命令行执行hdc.exe/hdc 二进制文件无法运行。
可能原因&解决方法
运行环境异常
Linux运行环境：建议使用Ubuntu18.04及以上64版本，如出现
libc++.so引用错误，请使用ldd/readelf等命令检查库引用。MacOS运行环境：建议使用MacOS 11及以上版本。
Windows运行环境：建议使用Windows10/Windows11 64位版本，如低版本缺失WinUSB库/驱动，请使用Zadig工具更新。对于符合设备，需要使用Zadig工具安装
libusb-win32驱动。详情请见：Zadig链接。运行方式不当：请使用命令行依照正确命令运行hdc工具，而非鼠标双击文件。
其他问题排查常用步骤
命令行执行
hdc list targets查看返回值。查看设备管理是否有
HDC Device。执行
hdc kill关闭server后，执行hdc -l5 start收集日志（hdc.log位于执行端TEMP目录，不同平台目录位置存在差异，可参考server端日志）。通过
hdc.log日志定位相关问题。