【鸿蒙开发】OpenHarmony调测工具hdc使用教程(应用开发者)

沧海一笑-dj2025-03-10 9:21

00. 目录

文章目录

    • [00. 目录](#00. 目录)
    • [01. OpenHarmony概述](#01. OpenHarmony概述)
    • [02. hdc简介](#02. hdc简介)
    • [03. hdc获取](#03. hdc获取)
    • [04. hdc命令列表](#04. hdc命令列表)
    • [05. 基本使用方法](#05. 基本使用方法)
    • [06. 设备连接管理](#06. 设备连接管理)
      • [6.1 查询设备列表](#6.1 查询设备列表)
      • [6.2 连接指定的目标设备](#6.2 连接指定的目标设备)
      • [6.3 等待设备正常连接](#6.3 等待设备正常连接)
      • [6.4 USB连接场景](#6.4 USB连接场景)
      • [6.5 TCP连接场景](#6.5 TCP连接场景)
      • [6.6 远程连接场景](#6.6 远程连接场景)
      • [6.7 usb调试和无线调试切换](#6.7 usb调试和无线调试切换)
    • [07. 执行交互命令](#07. 执行交互命令)
    • [08. 应用管理](#08. 应用管理)
    • [09. 文件传输](#09. 文件传输)
    • [10. 端口转发](#10. 端口转发)
    • [11. 服务进程管理](#11. 服务进程管理)
    • [12. 设备操作](#12. 设备操作)
    • [13. 安全相关命令](#13. 安全相关命令)
    • [14. 查询版本号](#14. 查询版本号)
    • [15. hdc调试日志](#15. hdc调试日志)
      • [15.1 server端日志](#15.1 server端日志)
      • [15.2 设备端日志](#15.2 设备端日志)
    • [16. 常见问题](#16. 常见问题)
      • [16.1 设备无法识别](#16.1 设备无法识别)
      • [16.2 hdc无法运行](#16.2 hdc无法运行)
      • [16.3 其他问题排查常用步骤](#16.3 其他问题排查常用步骤)
    • [17. 附录](#17. 附录)

01. OpenHarmony概述

OpenHarmony是由开放原子开源基金会（OpenAtom Foundation）孵化及运营的开源项目，目标是面向全场景、全连接、全智能时代，基于开源的方式，搭建一个智能终端设备操作系统的框架和平台，促进万物互联产业的繁荣发展。

OpenHarmony整体遵从分层设计，从下向上依次为：内核层、系统服务层、框架层和应用层。系统功能按照"系统 > 子系统 > 组件"逐级展开，在多设备部署场景下，支持根据实际需求裁剪某些非必要的组件。OpenHarmony技术架构如下所示：

内核层

  • 内核子系统：采用多内核（Linux内核或者LiteOS）设计，支持针对不同资源受限设备选用适合的OS内核。内核抽象层（KAL，Kernel Abstract Layer）通过屏蔽多内核差异，对上层提供基础的内核能力，包括进程/线程管理、内存管理、文件系统、网络管理和外设管理等。
  • 驱动子系统：驱动框架（HDF）是系统硬件生态开放的基础，提供统一外设访问能力和驱动开发、管理框架。

系统服务层

系统服务层是OpenHarmony的核心能力集合，通过框架层对应用程序提供服务。该层包含以下几个部分：

  • 系统基本能力子系统集：为分布式应用在多设备上的运行、调度、迁移等操作提供了基础能力，由分布式软总线、分布式数据管理、分布式任务调度、公共基础库、多模输入、图形、安全、AI等子系统组成。
  • 基础软件服务子系统集：提供公共的、通用的软件服务，由事件通知、电话、多媒体、DFX（Design For X） 等子系统组成。
  • 增强软件服务子系统集：提供针对不同设备的、差异化的能力增强型软件服务，由智慧屏专有业务、穿戴专有业务、IoT专有业务等子系统组成。
  • 硬件服务子系统集：提供硬件服务，由位置服务、用户IAM、穿戴专有硬件服务、IoT专有硬件服务等子系统组成。

根据不同设备形态的部署环境，基础软件服务子系统集、增强软件服务子系统集、硬件服务子系统集内部可以按子系统粒度裁剪，每个子系统内部又可以按功能粒度裁剪。

框架层

框架层为应用开发提供了C/C++/JS等多语言的用户程序框架和Ability框架，适用于JS语言的ArkUI框架，以及各种软硬件服务对外开放的多语言框架API。根据系统的组件化裁剪程度，设备支持的API也会有所不同。

应用层

应用层包括系统应用和第三方非系统应用。应用由一个或多个FA（Feature Ability）或PA（Particle Ability）组成。其中，FA有UI界面，提供与用户交互的能力；而PA无UI界面，提供后台运行任务的能力以及统一的数据访问抽象。基于FA/PA开发的应用，能够实现特定的业务功能，支持跨设备调度与分发，为用户提供一致、高效的应用体验。

技术特性

硬件互助，资源共享

主要通过下列模块达成

  • 分布式软总线

    分布式软总线是多设备终端的统一基座，为设备间的无缝互联提供了统一的分布式通信能力，能够快速发现并连接设备，高效地传输任务和数据。

  • 分布式数据管理

    分布式数据管理基于分布式软总线，实现了应用程序数据和用户数据的分布式管理。用户数据不再与单一物理设备绑定，业务逻辑与数据存储分离，应用跨设备运行时数据无缝衔接，为打造一致、流畅的用户体验创造了基础条件

  • 分布式任务调度

    分布式任务调度基于分布式软总线、分布式数据管理、分布式Profile等技术特性，构建统一的分布式服务管理（发现、同步、注册、调用）机制，支持对跨设备的应用进行远程启动、远程调用、绑定/解绑、以及迁移等操作，能够根据不同设备的能力、位置、业务运行状态、资源使用情况并结合用户的习惯和意图，选择最合适的设备运行分布式任务

  • 设备虚拟化

    分布式设备虚拟化平台可以实现不同设备的资源融合、设备管理、数据处理，将周边设备作为手机能力的延伸，共同形成一个超级虚拟终端。

一次开发，多端部署

OpenHarmony提供用户程序框架、Ability框架以及UI框架，能够保证开发的应用在多终端运行时保证一致性。一次开发、多端部署。

多终端软件平台API具备一致性，确保用户程序的运行兼容性。

  • 支持在开发过程中预览终端的能力适配情况（CPU/内存/外设/软件资源等）。
  • 支持根据用户程序与软件平台的兼容性来调度用户呈现。

统一OS，弹性部署

OpenHarmony通过组件化和组件弹性化等设计方法，做到硬件资源的可大可小，在多种终端设备间，按需弹性部署，全面覆盖了ARM、RISC-V、x86等各种CPU，从百KiB到GiB级别的RAM。

02. hdc简介

hdc（OpenHarmony 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自定义监听的端口号。

03. hdc获取

hdc工具通过OpenHarmony 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。

说明

环境变量配置完成后，关闭并重启命令行或其他使用到OpenHarmony SDK的软件。

使用举例：

下面以windows侧使用方式举例：

获取windows的sdk，将hdc.exe放到磁盘某个位置即可使用。

注意事项

  • 使用hdc，如果出现异常，可以尝试通过hdc kill命令杀掉hdc服务，或者通过hdc start -r命令重启服务进程进行解决。
  • 如果出现hdc list targets获取不到设备信息，通过任务管理器查看是否有hdc进程存在，如果进程存在，可以通过杀掉该进程进行解决。

04. hdc命令列表

全局参数

全局参数是指运行部分hdc命令时，可以跟随在hdc后面的参数，例如： 选择指定的设备执行命令，使用-t参数：

shell 复制代码 
hdc -t connect-key shell echo "Hello world"
参数 说明
-t 连接指定的目标设备，连接一台设备时为可选参数，连接多台设备时为必选参数。
-l 可选参数，指定运行时日志等级，范围为数字0-6，默认为3（LOG_INFO）。
-s 可选参数，指定客户端连接服务端时，服务进程的网络监听参数，格式为ip:port。
-p 可选参数，绕过对服务进程的查询步骤，用于快速执行客户端命令。
-m 可选参数，使用前台启动模式启动服务进程。

命令列表

命令 说明
list targets 查询已连接的所有目标设备。
wait 等待设备正常连接。
tmode usb 该命令已经废弃，不会实际操作设备连接通道，需要在设备设置界面通过USB调试开关进行设置。
tmode port 打开设备网络连接通道。
tmode port close 关闭设备网络连接通道。
tconn 指定连接设备：通过"IP地址：端口号"来指定连接的设备。
shell 在设备侧执行单次命令。
install 安装指定的应用文件。
uninstall 卸载指定的应用包。
file send 从本地发送文件至远端设备。
file recv 从远端设备发送文件至本地。
fport ls 列出全部转发端口转发任务。
fport 设置正向端口转发任务：监听"主机端口"，接收请求并进行转发， 转发到"设备端口"。
rport 设置反向端口转发任务：监听"设备端口"，接收请求并进行转发，转发到"主机端口"。
fport rm 删除指定的端口转发任务。
start 启动hdc服务进程。
kill 终止hdc服务进程。
hilog 打印设备端的日志信息。
jpid 显示设备上所有开启了JDWP调试协议的应用的PID。
track-jpid 实时显示设备上开启了JDWP调试协议的应用的PID和应用名。
target boot 重启目标设备。
target mount 以读写模式挂载系统分区（非root的设备不可用）。
smode 授予设备端hdc后台服务进程root权限， 使用-r参数取消授权（非root的设备不可用）。
keygen 生成一个新的秘钥对。
version 打印hdc版本信息，也可使用hdc -v打印版本信息。
checkserver 获取客户进程与服务进程版本信息。

说明

全局参数在使用时需要放在命令之前。

05. 基本使用方法

在使用hdc前，请在设备上开启usb调试功能，用usb线连接设备和PC。

查询连接的设备

shell 复制代码 
hdc list targets

执行shell命令

shell 复制代码 
hdc shell echo "Hello world"

获取帮助

命令 说明
-h [verbose] 显示hdc相关的帮助信息。可选参数：verbose，显示详细的帮助信息。
help 显示hdc相关的帮助信息。

显示hdc相关的帮助信息，命令格式如下：

hdc -h [verbose]
hdc help

使用方法：

shell 复制代码 
hdc -h
hdc help

// 显示详细帮助信息
hdc -h verbose

使用注意事项

  • 使用hdc时如出现异常，可尝试通过hdc kill -r命令杀掉异常进程并重启hdc服务。
  • 如出现hdc list targets获取不到设备信息的情况，参见设备无法识别章节。

06. 设备连接管理

6.1 查询设备列表

通过命令list targets，查询已连接的所有目标设备。 添加-v参数，则会打印设备详细信息。 命令格式如下：

shell 复制代码 
hdc list targets [-v]

返回值：

返回值 说明
设备标识符列表 已连接的设备标识符列表，-t参数使用的connect-key即为此信息。
[Empty] 没有查询到设备信息。

使用方法：

shell 复制代码 
hdc list targets
hdc list targets -v

6.2 连接指定的目标设备

连接单台设备时，执行命令无需指定设备标识符； 连接了多台设备时，每次执行命令时需要使用-t参数指定目标设备的标识符，命令格式如下：

hdc -t [connect-key] [command]

参数：

参数名 说明
connect-key 设备标识符，即为hdc list targets返回的信息。
command hdc支持的命令。

说明：

connect-key为每个设备唯一的标识符。如果通过usb连接，标识符为序列号；如果通过网络连接设备，标识符为"IP地址:端口号"。

返回值：

返回值 说明
命令执行返回内容 请参考对应命令的返回值。
[Fail]Not match target founded, check connect-key please 没有找到与connect-key匹配的设备。
[Fail]Device not founded or connected 设备未找到或尚未连接。
[Fail]ExecuteCommand need connect-key? please confirm a device by help info 多设备连接时需要指定一个设备。
Unknown operation command... 不支持的命令。

说明：

返回的错误提示信息后续会调整优化，请勿用于自动化脚本或程序的结果判断。

使用方法：

该方法需要与具体的操作命令搭配使用，下面以shell命令举例：

shell 复制代码 
hdc list targets  // 查询已连接的所有目标设备的connect-key
hdc -t [connect-key] shell // -t 后面添加的connect-key需要替换为指定的设备标识符

6.3 等待设备正常连接

命令格式如下：

shell 复制代码 
hdc wait // 等待设备正常连接
hdc -t connect-key wait // 等待指定的设备正常连接，connect-key需要替换为指定的设备标识符

返回值：

返回值 说明
无 hdc wait命令执行后，识别到正常连接的设备后结束。

使用方法：

hdc wait
hdc -t connect-key wait

6.4 USB连接场景

  • 环境确认
确认项 正常 异常处理
USB调试选项 开启 设备的USB调试模式如无法自动开启，请尝试重启设备。
USB数据连接线 使用USB数据连接线连接到调试PC的USB接口 如使用低带宽、无数据通信功能的USB连接线可能导致无法识别HDC设备，建议更换官方USB数据连接线。
USB接口 主板直出USB接口（台式机为后面板的USB接口，笔记本为机身的USB接口） 如使用转接头/拓展坞/台式机前面板USB接口，存在带宽低和USB同步异常等问题，会导致频繁断连，推荐使用直连方式连接PC和设备。
hdc环境变量 终端命令行输入hdc -h有回显帮助信息内容 参见环境准备章节。
驱动 连接HDC设备后，设备管理器通用串行总线设备存在设备"HDC Device"或"HDC Interface" 参见设备无法识别章节。
  • 连接步骤

  1. PC通过USB连接设备。

  2. 查看已连接设备，执行以下命令：

    hdc list targets

    返回值中存在对应设备的标识符，即为usb连接成功。

  3. 可以查询到设备后，即可运行设备相关命令和设备进行交互。如果希望不带设备标识符进行USB命令操作，需要确认设备不在tcp连接模式（hdc list targets查询的设备不包含IP:port形式的连接信息），直接连接即可，例如：

    hdc shell

6.5 TCP连接场景

注意：

TCP调试功能尚未稳定，请谨慎用于生产环境。

  • 环境确认
确认项 正常 异常处理
网络连接 PC、手机设备处于同一网络。 连接同一WiFi或手机开启热点。
网络状态 telnet IP:port正常，网速稳定。 请选择稳定的网络连接方式。
hdc环境变量 终端命令行输入hdc -h有回显帮助信息内容 参见环境准备章节。
  • 连接步骤

  1. 在设备设置界面打开无线调试开关。

  2. 记录设备界面显示的监听端口号，记为PORT，用于后面的tcp连接。

  3. 通过tcp连接设备（需要事先知道设备IP和打开的PORT），执行以下命令：

    shell 复制代码 
    hdc tconn IP:PORT

    IP地址可在设备侧的设置里面查看到，端口号为上一步设备无线调试界面显示的端口号。

  4. 查看已连接设备，执行以下命令：

    shell 复制代码 
    hdc list targets

    返回值为IP:PORT形式即为连接成功。

  5. 如果需要关闭TCP连接模式，可以在设备中关闭无线调试开关。

6.6 远程连接场景

远程连接场景是指客户端通过网络远程连接服务端，客户端和服务端在不同的PC运行，服务端连接设备。 远程连接如图所示:

hdc client（客户端）在PC1中运行，hdc server（服务端）在PC2中运行，PC2中的hdc server连接设备。

  • 连接命令

    命令 说明
    -s 指定当前服务进程的网络监听参数。

    远程连接使用-s参数来指定服务端的网络参数，包括地址和端口号，该设置只在当前命令执行期间有效，命令格式如下：

    shell 复制代码 
    hdc -s [ip]:[port] [command]

    参数：

    参数 说明
    ip 指定监听的IP地址，支持IPv4和IPv6。
    port 指定监听的端口，范围：1~65535。
    command hdc支持的命令。

    返回值：

    返回值 说明
    Connect server failed 与服务进程建立连接失败。
    -s content port incorrect. 端口号超出可设置范围（1~65535）。

    使用方法：

    shell 复制代码 
    # 在已有服务进程，且服务进程的网络监听参数为127.0.0.1:8710的环境中，执行查询设备命令
hdc -s 127.0.0.1:8710 list targets

    说明：

    当命令行中明确使用 -s 参数指定服务端口时，系统将忽略OHOS_HDC_SERVER_PORT环境变量中定义的端口设置。

  • 连接步骤

    1. 服务端配置

    服务端通过USB连接到对应的HDC设备后执行以下命令：

    shell 复制代码 
    hdc kill          // 关闭本地hdc服务
hdc -s IP:8710 -m // 启动网络转发的hdc服务
                  // 其中IP为服务端自身的IP，windows可通过ipconfig查询，unix系统可通过ifconfig查询
                  // 8710为默认端口号，也可设置为其他端口号如：18710
                  // 启动后服务端将打印日志
    1. 客户端连接

    客户端连接需要确保可以连通服务端IP地址，满足前述条件后执行以下命令：

    shell 复制代码 
    hdc -s IP:8710 [command] // 其中IP为服务端IP，8710为第一步服务端启动时设置的端口号，
                        // 如果端口号有变化，这里也需要变更。
                        // command可以为任意hdc可用命令，例如list targets

6.7 usb调试和无线调试切换

用于连接模式切换的命令如下表所示：

当前推荐通过设备端的usb调试开关和无线调试开关来控制连接通道的开启和关闭。

命令 说明
tmode usb 该命令已经废弃，不会实际操作设备连接通道，需要在设备设置界面通过USB调试开关进行设置。
tmode port [port-number] 打开设备网络连接通道：设备端daemon进程会重启，已建立的USB连接会中断，需要重新连接。
tmode port close 关闭设备网络连接通道：设备端daemon进程会重启，已建立的USB连接会中断，需要重新连接。
tconn [IP]:[port] [-remove] 连接指定的设备，通过"IP地址：端口号"来指定连接的设备，使用-remove参数断开连接。

  1. 打开设备网络连接通道，命令格式如下：

    shell 复制代码 
    hdc tmode port [port-number]

    参数：

    参数 参数说明
    port-number 监听连接的网络端口号，范围:1~65535。

    返回值：

    返回值 说明
    Set device run mode successful. 打开成功。
    [Fail]ExecuteCommand need connect-key 打开失败，设备列表无设备，无法打开设备无线调试通道。
    [Fail]Incorrect port range 端口号超出可设置范围（1~65535）。

    使用方法：

    shell 复制代码 
    hdc tmode port 1234

    注意：

    切换前，请确保条件满足：远端设备与近端PC处于同一网络，且PC可ping通远端设备IP。

    如不满足以上条件请勿使用该命令进行切换。
    说明：

    执行完毕后，远端daemon进程将会退出并重启，USB连接将会断开，需要重新连接。

  2. 关闭设备网络连接通道，命令格式如下：

    shell 复制代码 
    hdc tmode port close

    返回值：

    返回值 说明
    [Fail]ExecuteCommand need connect-key 设备列表无设备，无法执行命令。

    使用方法：

    shell 复制代码 
    hdc tmode port close

    说明： 执行完毕后，远端daemon进程将会退出并重启，USB连接将会断开，需要重新连接。

  3. 通过TCP连接指定的设备，命令格式如下：

    shell 复制代码 
    hdc tconn [IP]:[port] [-remove]

    参数：

    参数 参数说明
    [IP]:[port] 设备的IP地址与端口号。
    -remove 可选参数，断开指定设备的连接。

    返回值：

    返回值 说明
    Connect OK 连接成功
    [Info]Target is connected, repeat opration 设备当前已连接
    [Fail]Connect failed 连接失败

    使用方法：

    hdc tconn 192.168.0.1:8888
hdc tconn 192.168.0.1:8888 -remove  // 断开指定网络设备连接

07. 执行交互命令

命令格式如下：

shell 复制代码 
hdc shell [command]

参数：

参数 说明
[command] 需要在设备侧执行的单次命令，不同类型或版本的系统支持的command命令有所差异，可以通过hdc shell ls /system/bin查阅支持的命令列表。当前许多命令都是由toybox提供，可通过 hdc shell toybox --help 获取命令帮助。

返回值：

返回值 说明
交互命令返回内容 返回内容详情请参见其他交互命令返回内容。
/bin/sh: XXX : inaccessible or not found 不支持的交互命令。

使用方法：

hdc shell ps -ef
hdc shell help -a // 查询全部可用命令

08. 应用管理

命令 说明
install src 安装指定的应用文件。
uninstall packageName 卸载指定的应用包package包名。

  1. 安装APP package，命令格式如下：

    shell 复制代码 
    hdc install [-r|-s] src

    参数：

    参数名 说明
    src 应用安装包的文件名
    -r 替换已存在应用（.hap）
    -s 安装一个共享包（.hsp）

    返回值：

    返回值 说明
    AppMod finish 成功情况下返回安装信息和AppMod finish。
    具体安装失败原因 失败情况下返回具体安装失败信息。

    使用方法：

    以安装example.hap包为例：

    shell 复制代码 
    hdc install E:\example.hap

  2. 卸载应用，命令格式如下：

    shell 复制代码 
    hdc uninstall [-k|-s] packageName

    参数：

    参数名 说明
    packageName 应用安装包。
    -k 保留/data和/cache目录。
    -s 卸载共享包。

    返回值：

    返回值 说明
    AppMod finish 成功情况下返回卸载信息和AppMod finish。
    具体卸载失败原因 失败情况下返回具体卸载失败信息。

    使用方法：

    以卸载com.example.hello包为例：

    hdc uninstall com.example.hello

09. 文件传输

命令 说明
file send localpath remotepath 从本地发送文件至远端设备。
file recv remotepath localpath 从远端设备发送文件至本地。

  1. 从本地发送文件至远端设备，命令格式如下：

    shell 复制代码 
    hdc file send [-a|-sync|-z|-m] localpath remotepath

    参数：

    参数名 说明
    localpath 本地待发送的文件路径。
    remotepath 远程待接收的文件路径。
    -a 保留文件时间戳。
    -sync 只传输文件mtime有更新的文件。
    -z 通过LZ4格式压缩传输，此功能未开放，请勿使用。
    -m 文件传输时同步文件DAC权限，uid，gid，MAC权限。

    返回值：

    文件发送成功，返回传输成功的结果信息。文件发送失败，返回传输失败的具体信息。

    使用方法：

    shell 复制代码 
    hdc file send E:\example.txt /data/local/tmp/example.txt

  2. 从远端设备发送文件至本地，命令格式如下：

    shell 复制代码 
    hdc file recv [-a|-sync|-z|-m] remotepath localpath

    参数：

    参数名 说明
    localpath 本地待接收的文件路径。
    remotepath 远程待发送的文件路径。
    -a 保留文件时间戳。
    -sync 只传输文件mtime有更新的文件。
    -z 通过LZ4格式压缩传输，此功能未开放，请勿使用。
    -m 文件传输时同步文件DAC权限，uid，gid，MAC权限。

    返回值：

    文件接收成功，返回传输成功的结果信息。文件接收失败，返回传输失败的具体信息。

    使用方法：

    hdc file recv  /data/local/tmp/a.txt   ./a.txt

10. 端口转发

命令 说明
fport ls 列出全部转发端口转发任务。
fport localnode remotenode 设置正向端口转发任务：监听"主机端口"，接收请求并进行转发， 转发到"设备端口"。
rport remotenode localnode 设置反向端口转发任务：监听"设备端口"，接收请求并进行转发，转发到"主机端口"。
fport rm taskstr 删除指定的端口转发任务。

PC端支持的端口转发类型：tcp。

设备端支持的端口转发类型：tcp，dev，localabstract，localfilesystem，jdwp，ark。

  1. 列出全部转发端口转发任务，命令格式如下：

    shell 复制代码 
    hdc fport ls

    返回值：

    返回值 说明
    tcp:1234 tcp:1080 [Forward] 正向端口转发任务
    tcp:2080 tcp:2345 [Reverse] 反向端口转发任务
    [empty] 无端口转发任务

    使用方法：

    shell 复制代码 
    hdc fport ls

  2. 设置正向端口转发任务，执行后将设置指定的"主机端口"转发数据到"设备端口"转发任务，命令格式如下：

    shell 复制代码 
    hdc fport localnode remotenode

    返回值：

    返回值 说明
    Forwardport result:OK 端口转发任务设置正常。
    [Fail]Incorrect forward command 端口转发任务设置失败，端口转发参数错误。
    [Fail]TCP Port listen failed at XXXX 端口转发任务设置失败，本地转发端口被占用。

    使用方法：

    shell 复制代码 
    hdc fport tcp:1234 tcp:1080

  3. 设置反向端口转发任务，执行后将设置指定的"设备端口"转发数据到"主机端口"转发任务，命令格式如下：

    shell 复制代码 
    hdc rport remotenode localnode

    返回值：

    返回值 说明
    Forwardport result:OK 端口转发任务设置正常。
    [Fail]Incorrect forward command 端口转发任务设置失败，端口转发参数错误。
    [Fail]TCP Port listen failed at XXXX 端口转发任务设置失败，本地转发端口被占用。

    使用方法：

    shell 复制代码 
    hdc rport tcp:1234 tcp:1080

  4. 删除端口转发任务，执行后将指定的转发任务删除，命令格式如下：

    shell 复制代码 
    hdc fport rm taskstr

    参数：

    参数 说明
    taskstr 端口转发任务，形如 tcp:XXXX tcp:XXXX。

    返回值：

    返回值 说明
    Remove forward ruler success, ruler:tcp:XXXX tcp:XXXX 端口转发任务删除正常。
    [Fail]Remove forward ruler failed, ruler is not exist tcp:XXXX tcp:XXXX 端口转发任务删除失败，不存在指定的转发任务。

    使用方法：

    hdc fport rm tcp:1234 tcp:1080

11. 服务进程管理

命令 说明
start [-r] 启动hdc服务进程，使用-r参数触发服务进程重新启动。
kill [-r] 终止hdc服务进程，使用-r参数触发服务进程重新启动。
-p 绕过对服务进程的查询步骤，用于快速执行客户端命令。
-m 使用前台启动模式启动服务进程。

  1. 启动hdc服务进程，命令格式如下：

    shell 复制代码 
    hdc start [-r]

    返回值：

    返回值 说明
    无返回值 服务进程启动成功

    使用方法：

    shell 复制代码 
    hdc start
hdc start -r // 服务进程启动状态下，触发服务进程重新启动

    说明：

    当启动hdc服务进程且系统未检测到运行的服务进程时，日志等级的设置优先级如下：若同时指定了-l参数和配置了OHOS_HDC_LOG_LEVEL环境变量，则使用环境变量配置的日志等级；如果仅指定了-l参数，则采用该参数配置的日志等级；若两者均未指定，则服务进程将以默认的LOG_INFO等级启动。

  2. 终止hdc服务进程，命令格式如下：

    shell 复制代码 
    hdc kill [-r]

    返回值：

    返回值 说明
    Kill server finish 服务进程终止成功
    [Fail]具体失败信息 服务进程终止失败

    使用方法：

    shell 复制代码 
    hdc kill
hdc kill -r  // 重启并终止服务进程

  3. 绕过对服务进程的查询步骤，用于快速执行客户端命令，命令格式如下：

    shell 复制代码 
    hdc -p [command]

    参数：

    参数 说明
    command hdc支持的命令

    返回值：

    返回值 说明
    Connect server failed 与服务进程建立连接失败

    使用方法：

    shell 复制代码 
    # 启动后台服务进程
hdc start
# 跳过进程查询，直接执行命令
hdc -p list targets

    说明：

    在未指定 -p 参数的情况下直接执行 command 命令时，客户端将首先检查本地是否已有运行的服务进程。若系统未检测到运行的服务进程，客户端将自动启动服务进程，并建立连接以传递命令；若系统检测到运行的服务进程，客户端将直接与该后台服务建立连接并下发相应的命令。

  4. 使用前台启动模式启动服务进程，命令格式如下：

    shell 复制代码 
    hdc -m

    返回值：

    返回值 说明
    Initial failed 服务进程初始化失败。
    [I][1970-01-01 00:00:00.000 ][abcd ][session.cpp:25 ] Program running. Ver: X.X.Xa Pid:12345 正常打印对应等级的日志，显示服务端活动状态。

    使用方法：

    shell 复制代码 
    # 指定当前服务进程的网络监听参数并启动服务进程
hdc -s 127.0.0.1:8710 -m

    说明：

    1. 使用前台启动参数时，可通过附加 -s 参数来指定服务进程的网络监听参数。如果既没有使用 -s 指定网络监听参数，也没有配置环境变量OHOS_HDC_SERVER_PORT配置监听端口，系统将采用默认网络监听参数:127.0.0.1:8710。
    2. 在服务进程前台启动模式下，系统默认的日志输出等级设置为 LOG_DEBUG。如需变更日志等级，可通过结合使用 -l 参数来进行相应的调整。
    3. 在运行环境中，仅允许单一的服务进程实例存在。若运行环境中已存在一个活跃的后台服务进程，那么尝试在前台启动新的服务进程实例将不会成功。

12. 设备操作

命令 说明
hilog [-h] 打印设备端的日志信息，可通过hdc hilog -h查阅支持的参数列表。
jpid 显示设备上所有开启了JDWP调试协议的应用的PID。
track-jpid [-a|-p] 实时显示设备上开启了JDWP调试协议的应用的PID和应用名，不加参数只显示debug的应用的进程，使用-a参数显示debug和release应用的进程，使用-p参数不显示debug和release的标签。
target boot [-bootloader|-recovery] 重启目标设备，使用-bootloader参数重启后进入fastboot模式，使用-recovery参数重启后进入recovery模式。
target boot [MODE] 重启目标设备，加参数重启后进入相应的模式，其中MODE为/bin/begetctl命令中reboot支持的参数。
target mount 以读写模式挂载系统分区（设备root后支持此命令）。
smode [-r] 授予设备端hdc后台服务进程root权限， 使用-r参数取消授权（设备root后支持此命令）。

  1. 打印设备端的日志信息，命令格式如下：

    shell 复制代码 
    hdc hilog [-h]

    参数：

    参数 说明
    [-h] hilog支持的参数，可通过hdc hilog -h查阅支持的参数列表。

    返回值：

    返回值 说明
    返回具体信息 抓取的日志信息。

    使用方法：

    shell 复制代码 
    hdc hilog

  2. 显示设备上所有开启了JDWP调试协议的进程的PID，命令格式如下：

    shell 复制代码 
    hdc jpid

    返回值：

    返回值 说明
    进程号列表 开启了JDWP调试协议的应用的PID。
    [empty] 无开启了JDWP调试协议的进程。

    使用方法：

    xhdc 复制代码 
    hdc jpid
shell

  3. 实时显示设备上开启了JDWP调试协议的进程的PID和应用名，命令格式如下：

    shell 复制代码 
    track-jpid [-a|-p]

    参数：

    参数 说明
    不加参数 只显示debug的应用的进程号和包名/进程名。
    -a 显示debug和release应用的进程号和包名/进程名。
    -p 显示debug和release应用的进程号和包名/进程名，但不显示debug和release的标签。

    返回值：

    返回值 说明
    进程号和包名/进程名列表 -
    [empty] 不加参数时表示无开启了JDWP调试协议的debug应用的进程，使用-a或-p参数时表示无开启了JDWP调试协议的进程。

    使用方法：

    shell 复制代码 
    hdc track-jpid

  4. 重启目标设备，命令格式如下：

    shell 复制代码 
    target boot [-bootloader|-recovery]
target boot [MODE]

    参数：

    参数名 说明
    不加参数 重启设备
    -bootloader 重启后进入fastboot模式。
    -recovery 重启后进入recovery模式。
    MODE 重启后进入MODE模式，MODE为/bin/begetctl命令中reboot支持的参数。 可通过hdc shell "/bin/begetctl -h | grep reboot"查看。

    使用方法：

    shell 复制代码 
    hdc target boot -bootloader // 重启后进入fastboot模式
hdc target boot -recovery  // 重启后进入recovery模式
hdc target boot shutdown  // 关机

  5. 以读写模式挂载系统分区，命令格式如下：

    shell 复制代码 
    hdc target mount

    返回值：

    返回值 说明
    Mount finish 挂载成功
    [Fail]Mount failed 挂载失败

    使用方法：

    shell 复制代码 
    hdc target mount

    说明：

    设备root后才支持此命令，对系统分区的修改存在一定的风险，请谨慎使用。

  6. 授予设备端hdc后台服务进程root权限，命令格式如下：

    shell 复制代码 
    hdc smode [-r]

    返回值：

    返回值 说明
    无返回值 授予权限成功
    [Fail]具体失败信息 授予权限失败

    使用方法：

    shell 复制代码 
    hdc smode
hdc smode -r  // 取消root权限

    说明：

    设备root后才支持此命令。

13. 安全相关命令

命令 说明
keygen FILE 生成一个新的秘钥对，并将私钥和公钥分别保存到FILE和FILE.pub，其中文件名FILE可自定义。

  1. 生成一个新的秘钥对，命令格式如下：

    shell 复制代码 
    hdc keygen FILE

    参数：

    参数 说明
    FILE FILE为自定义的文件名

    使用方法：

    hdc keygen key // 在当前目录下生成key和key.pub文件

14. 查询版本号

命令 说明
-v/version 打印hdc版本信息。
checkserver 获取客户端与服务进程版本。

  1. 显示hdc的版本信息，命令格式如下：

    shell 复制代码 
    hdc -v/version

    返回值：

    返回值 说明
    Ver: X.X.Xa hdc（SDK）的版本信息。

    使用方法：

    shell 复制代码 
    hdc -v 或 hdc version

  2. 获取客户端与服务进程版本，命令格式如下：

    shell 复制代码 
    hdc checkserver

    返回值：

    返回值 说明
    Client version: Ver: X.X.Xa, Server version: Ver: X.X.Xa client（客户端），server（服务进程）版本号。

    使用方法：

    hdc checkserver

15. hdc调试日志

15.1 server端日志

指定运行时日志等级

hdc运行时日志等级，默认为LOG_INFO，命令格式如下：

shell 复制代码 
hdc -l [level] [command]

参数：

参数 说明
[level] 指定运行时日志等级 0：LOG_OFF 1：LOG_FATAL 2：LOG_WARN 3：LOG_INFO 4：LOG_DEBUG 5：LOG_ALL 6：LOG_LIBUSB。
command hdc支持的命令。

说明：

  1. 当配置运行时日志级别为6（LOG_LIBUSB）时，将激活libusb相关的增量日志输出，增量日志级别的详细程度高、数据量大，有助于精确诊断服务进程中与USB相关的异常情况。USB相关操作主要由服务进程执行，因此，只有服务进程具备打印增量日志的功能。相应地，客户端侧的日志几乎不包含增量日志信息。
  2. 指定运行时日志等级仅适用于当前进程（包括客户端与服务进程），无法更改已存在的进程日志等级。

返回值：

返回值 说明
命令执行返回内容 请参考对应命令的返回值。
日志信息 对应指定的运行时等级日志打印。

使用方法：

客户端打印LOG_DEBUG级别日志，以执行shell ls为例，命令示例如下:

shell 复制代码 
hdc -l 5 shell ls

服务进程前台模式启动指定LOG_LIBUSB级别日志，命令示例如下:

shell 复制代码 
hdc kill && hdc -l 6 -m

说明： -m参数指定以前台模式启动服务进程，可以直接观察前台日志输出，按下Ctrl+C退出进程。

服务进程后台启动模式指定LOG_LIBUSB级别日志，命令示例如下:

shell 复制代码 
hdc kill && hdc -l 6 start

说明： 以后台模式启动，可以在hdc.log中观察日志输出，日志路径可以查看日志获取章节的描述。

日志获取

执行以下命令开启日志获取：

shell 复制代码 
hdc kill
hdc -l5 start

收集到的完整日志存放路径：

平台 路径 备注
Windows %temp%\hdc.log 实际路径参考，实际使用请替换用户名变量 C:\Users\用户名\AppData\Local\Temp\hdc.log。
Linux /tmp/hdc.log -
MacOS $TMPDIR/hdc.log -

日志相关环境变量：

环境变量名称 默认值 说明
OHOS_HDC_LOG_LEVEL 5 用于配置服务进程日志记录级别，日志级别详情参考： server端日志指定运行时日志等级章节。

环境变量配置方法：

以下通过配置OHOS_HDC_LOG_LEVEL环境变量为例，配置环境变量值为：5，介绍环境变量配置方法。

操作系统 配置方法
Windows 在此电脑 > 属性 > 高级系统设置 > 高级 > 环境变量中，添加环境变量名称为OHOS_HDC_LOG_LEVEL，变量值为5。配置完毕后点击确认。环境变量配置完成后，关闭并重启命令行或其他使用到OpenHarmony SDK的软件，以生效新配置的环境变量。
Linux 在~/.bash_profile文件末尾追加内容export OHOS_HDC_LOG_LEVEL=5并保存后，执行source ~/.bash_profile生效当前环境变量。
MacOS 在~/.zshrc文件末尾追加内容export OHOS_HDC_LOG_LEVEL=5并保存后，执行source ~/.zshrc生效当前环境变量。环境变量配置完成后，关闭并重启命令行或其他使用到OpenHarmony SDK的软件，以生效新配置的环境变量。

15.2 设备端日志

开启hilog日志工具，获取对应日志，命令如下：

hdc shell hilog -w start                              // 开启hilog日志落盘
hdc shell ls /data/log/hilog                          // 查看已落盘hilog日志
hdc file recv /data/log/hilog                         // 获取hilog已落盘日志（包含内核日志）

16. 常见问题

16.1 设备无法识别

现象描述

命令行执行hdc list targets命令后，返回结果为[empty]。

可能原因&解决方法

可通过以下方式排查。

  • 情况一：查看设备管理是否显示HDC设备。

    Windows环境：

    在设备管理器>通用串行总线设备中是否显示HDC Device（单一端口设备）或HDC Interface（复合端口设备）。

    Linux环境：

    在命令行执行lsusb,在返回的内容中查看是否有HDC Device（单一端口设备）或HDC Interface（复合端口设备）。

    MacOS环境：

    使用系统信息或系统概述来查看USB设备，步骤如下：

    1. 按住键盘上的Option键，点按菜单。
    2. 选取系统信息或系统概述。
    3. 在随后出现的窗口中，选择左边的USB。
    4. 在随后显示的设备树查看是否有HDC Device（单一端口设备）或HDC Interface（复合端口设备）。

    可采取的解决方法

    以上环境如没有显示HDC设备，则说明无法识别设备，可以根据实际场景尝试以下方法：

    • 使用其他USB物理接口。
    • 更换USB数据连接线。
    • 使用其他计算机调试。
    • 设备开启USB调试模式。
    • 设备出现弹窗点击允许调试。
    • 如可通过TCP模式连接，可执行hdc tmode usb命令恢复USB连接。
    • 设备恢复出厂设置。

  • 情况二：存在USB设备，但是驱动损坏，显示"HDC Device"⚠警告图标。

    现象描述：该问题常见于Windows环境，现象为设备管理器>通用串行总线设备中，HDC Device显示为黄标警告，且描述信息为该设备无法正常工作。可尝试重新安装驱动解决，如重新安装驱动无法解决，可以尝试更换USB连接数据线/拓展坞/USB接口。

    重新安装驱动的方法

    1. 打开设备管理器，右键点击存在警告图标的HDC Device；
    2. 出现的菜单中点击更新驱动程序；
    3. 出现的提示窗口（第1/3个）中，选取浏览我的电脑以查找驱动程序；
    4. 出现的提示窗口（第2/3个）中，选取让我从计算机上的可用驱动程序列表中选取；
    5. 出现的提示窗口（第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。

    出现该现象，可能有如下原因：

    • 端口抢占

      解决方法如下：

      1. 排查自带hdc的软件进程。

        包括自带hdc的软件（DevEco Studio、DevEco Testing），如存在请关闭这些软件后再执行hdc相关命令。

      2. 查询HDC端口情况。

        以设置的OHOS_HDC_SERVER_PORT为8710端口为例，在不同平台查询命令如下：

        Unix：

        shell 复制代码 
        netstat -an |grep 8710

        Windows:

        shell 复制代码 
        netstat -an |findstr 8710

        如存在抢占的软件，可以关闭该软件进程或者更换OHOS_HDC_SERVER_PORT环境变量为其他端口号。

      3. 排查未关闭的其他版本hdc server。

        Windows：

        使用任务管理器>详细信息查询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）

    • 注册表异常

      解决方法：清理注册表，步骤如下：

      1. 同时按下Win+R键，启动运行工具，输入栏输入regedit打开注册表。

      2. 注册表地址栏输入以下内容并按下回车，即可进入USB类设备驱动程序的注册表。

        shell 复制代码 
        计算机\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Class\{88bae032-5a81-49f0-bc3d-a4ff138216d6}

      3. 找到UpperFilters键，右键修改编辑，备份并清空其中数值数据内容（如清空后无法解决问题可依照备份恢复）。

      4. 刷新设备管理器/插拔USB接口/重启计算机。

linux系统非root权限运行hdc无法找到设备

linux环境可以选择开启非root用户USB设备操作权限，方法如下：

  • （临时权限）设置USB设备操作权限最大化:

    shell 复制代码 
    sudo chmod -R 777 /dev/bus/usb/

  • （永久权限）永久修改USB设备权限:

    1. 使用lsusb找出USB设备的vendorID和productID。

    2. 创建一个新的udev规则。

      编辑udev加载规则，用设备的"idVendor"和"idProduct"来替换默认值。

      MODE="0666"来表示USB设备的权限GROUP；GROUP代表用户组，要确保此时登录的系统用户在该用户组中：

      shell 复制代码 
      sudo vim /etc/udev/rules.d/90-myusb.rules
SUBSYSTEMS=="usb", ATTRS{idVendor}=="067b", ATTRS{idProduct}=="2303", GROUP="users", MODE="0666"

    3. 重启电脑或重新加载udev规则：

      shell 复制代码 
      sudo udevadm control --reload

注意： 开启非root用户USB设备操作权限 可以解决Linux环境在非root权限下使用hdc无法找到设备的情况，但权限最大化可能存在潜在安全问题，请开发者根据使用场景自行评估是否开启。

16.2 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工具，而非鼠标双击文件。

16.3 其他问题排查常用步骤

  1. 命令行执行hdc list targets查看返回值。
  2. 查看设备管理是否有HDC Device。
  3. 执行hdc kill关闭server后，执行hdc -l5 start收集日志（hdc.log位于执行端TEMP目录，不同平台目录位置存在差异，可参考server端日志）。
  4. 通过hdc.log日志定位相关问题。

17. 附录

相关推荐
别说我什么都不会41 分钟前
当OpenHarmony遇上OpenEuler
操作系统·嵌入式·harmonyos
没有了遇见1 小时前
鸿蒙学习ArkTS之工程目录说
harmonyos
没有了遇见1 小时前
鸿蒙学习ArkTS之Module创建和引用
harmonyos
万少2 小时前
喜大普奔 DevEco Studio 官方接 入 DeepSeek 了
人工智能·harmonyos·ai 编程
遇到困难睡大觉哈哈2 小时前
HarmonyOS 音频录制与播放模块
华为·音视频·harmonyos·鸿蒙
IT乐手4 小时前
2.2、层叠布局（Stack）
harmonyos
IT乐手4 小时前
2.1、线性布局（Row/Column）
harmonyos
Georgewu5 小时前
【HarmonyOS Next】鸿蒙加固方案调研和分析
前端·面试·harmonyos
月未央5 小时前
HarmonyOS Next 开发系列：Provider和Consumer状态修饰器实践
ios·harmonyos
全栈若城5 小时前
16 HarmonyOS NEXT UVList组件开发指南(三)
harmonyos
热门推荐
01DeepSeek各版本说明与优缺点分析02从零安装 LLaMA-Factory 微调 Qwen 大模型成功及所有的坑03如何在WPS和Word/Excel中直接使用DeepSeek功能04本地化部署AI知识库：基于Ollama+DeepSeek+AnythingLLM保姆级教程05DeepSeek R1本地化部署 Ollama + Chatbox 打造最强 AI 工具06本地部署DeepSeek教程（Mac版本）07本地部署DeepSeek后的调用与删除全攻略08Windows 11 安装 Dify 完整指南 非docker环境09保姆级教程：利用Ollama与Open-WebUI本地部署 DeedSeek-R1大模型10如何本地部署AI智能体平台，带你手搓一个AI Agent