hdc（HarmonyOS Device Connector）是提供给开发人员的命令行调试工具，用于与设备进行交互调试、数据传输、日志查看以及应用安装等操作。该工具支持在Windows/Linux/MacOS系统上运行，为开发者提供高效，便捷的设备调试能力。

hdc包含三部分：

**客户端（client）**：运行在电脑端的进程，开发者在执行hdc命令时启动该进程，命令结束后进程自动退出。

**服务器（server）**：运行在电脑端的后台服务进程，用来管理客户端进程和设备端守护进程之间的数据交互，设备发现等。

**守护程序（daemon）**：运行在调试设备端的进程，用来响应服务器发来的请求。

如图所示：

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/c4/v3/TPd6gXhFRey9EAjejXRFLg/zh-cn_image_0000002571171987.png?HW-CC-KV=V1&HW-CC-Date=20260414T050858Z&HW-CC-Expire=86400&HW-CC-Sign=17508AA62E58992A6CF47BCF18619FB5C9C067593B2DC11BBD023F64854D922F)

说明

客户端进程在启动时，默认会判断服务器进程是否正在运行。如果没有运行则会启动一个新的hdc进程作为服务器进程，运行在后台。

服务器运行时，默认会监听电脑端的8710端口。开发者可通过设置系统环境变量OHOS\_HDC\_SERVER\_PORT自定义监听的端口号，范围为1~65535。

## 环境准备

hdc可以选择以下任意一种方式获取：

1.通过HarmonyOS SDK获取hdc工具。HarmonyOS SDK已嵌入[DevEco Studio](https://developer.huawei.com/consumer/cn/deveco-studio/)中，无需额外下载配置。hdc默认安装在DevEco Studio/sdk/default/openharmony/toolchains路径下，MacOS系统的sdk位于DevEco Studio/Contents目录下。

2.通过[Command Line Tools](https://developer.huawei.com/consumer/cn/download/)工具中的sdk目录获取相关工具。hdc程序默认安装在Command Line Tools/sdk/default/openharmony/toolchains路径下。

hdc支持USB和无线两种连接调试方式。在设备的设置>系统>开发者选项中开启或关闭调试开关 ，无需重启设备即可生效。如果设备未启用“开发者选项”，可参考[开发者选项](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-developer-mode#section530763213432)进行启用。具体调试连接方式及操作步骤请参考[USB连接场景](/consumer/cn/doc/harmonyos-guides/hdc#usb连接场景)和[TCP连接场景](/consumer/cn/doc/harmonyos-guides/hdc#tcp连接场景)。

### （可选）命令行直接执行hdc程序

**安装目录下的调试**

1. 开发者可以在HarmonyOS SDK的toolchains子目录下执行hdc命令进行设备调试。
2. hdc支持独立运行。将toolchains子目录下的hdc可执行文件和libusb\_shared依赖文件集中存放至自定义目录中，在自定义目录下直接执行hdc命令，实现独立调试。

**添加hdc到系统环境变量**

1. Windows环境变量设置方法：

   * 按下Windows键，搜索栏输入“设置”，点击进入设置窗口；
   * 在搜索栏中搜索“查看高级系统设置”。在环境变量>系统变量>Path>编辑中，将hdc.exe所在目录添加到Path。环境变量配置完成后，请重启电脑，即可在命令行窗口执行hdc命令。
2. Linux/MacOS系统：

   * 打开终端工具，执行以下命令，根据输出结果分别执行不同的命令。

     收起

     自动换行

     深色代码主题

     复制

     ```
     1. echo $SHELL
     ```

     + 如果输出结果为bin/bash，执行以下命令打开.bashrc文件。

       收起

       自动换行

       深色代码主题

       复制

       ```
       1. vi ~/.bashrc
       ```
     + 如果输出结果为/bin/zsh，执行以下命令打开.zshrc文件。

       收起

       自动换行

       深色代码主题

       复制

       ```
       1. vi ~/.zshrc
       ```
   * 切换至英文输入法，按下键盘字母“i”，进入Insert模式。
   * 在文件末尾添加PATH信息。

     收起

     自动换行

     深色代码主题

     复制

     ```
     1. export PATH={DevEco Studio}/sdk/default/openharmony/toolchains:$PATH
     ```

     其中{DevEco Studio}需替换为DevEco Studio实际安装目录的绝对路径，例如/home/DevEco-Studio。
   * 编辑完成后，单击Esc键退出编辑模式，输入“:wq”并且单击Enter键保存。
   * 请执行以下命令，使配置的环境变量生效。

     + 如果步骤1打开的是.bashrc文件，请执行如下命令：

       收起

       自动换行

       深色代码主题

       复制

       ```
       1. source ~/.bashrc
       ```
     + 如果步骤1打开的是.zshrc文件，请执行如下命令：

       收起

       自动换行

       深色代码主题

       复制

       ```
       1. source ~/.zshrc
       ```
   * 环境变量配置完成后，重启系统。

### （可选）服务器配置

配置系统环境变量可修改服务器进程的监听端口、日志打印级别或特性开关等。详细介绍请查看[可选配置项](/consumer/cn/doc/harmonyos-guides/hdc#可选配置项)章节。

说明

环境变量配置完成后，重启命令行窗口或其他使用到HarmonyOS SDK的软件，以生效新配置的环境变量。

## hdc命令列表

### 全局参数

全局参数是指运行hdc命令时，可以添加在hdc和具体执行命令之间的参数。例如，使用-t参数可以选择指定的设备执行命令：

收起

自动换行

深色代码主题

复制

```
1. hdc -t connect-key shell echo "Hello world"
```

展开

| 参数 | 说明 |
| --- | --- |
| [-t](/consumer/cn/doc/harmonyos-guides/hdc#连接指定的目标设备) | 通过设备标识符连接指定的目标设备。单台设备连接时为可选参数，连接多台设备时为必选参数。 |
| [-l](/consumer/cn/doc/harmonyos-guides/hdc#服务器进程日志) | 可选参数，指定运行时日志等级，范围为数字0-6，默认为3（LOG\_INFO）。 |
| [-s](/consumer/cn/doc/harmonyos-guides/hdc#远程连接场景) | 可选参数，指定客户端连接服务器时，服务进程的网络监听参数，格式为IP:port。 |
| [-p](/consumer/cn/doc/harmonyos-guides/hdc#快速执行命令) | 可选参数，绕过对服务进程的查询步骤，用于快速执行客户端命令。 |
| [-m](/consumer/cn/doc/harmonyos-guides/hdc#前台启动服务) | 可选参数，使用前台启动模式启动服务进程。 |
| [-e](/consumer/cn/doc/harmonyos-guides/hdc#创建正向端口转发任务) | 可选参数，指定在TCP端口转发时，本地监听的IP地址，默认是127.0.0.1。该参数必须和-m一起使用。  使用-e参数指定监听地址时，如果监听地址不是本地回环地址（如127.0.0.1），需注意访问安全问题。  **说明**：从API version 20开始，支持该接口。 |

### 命令列表

展开

| 命令 | 说明 |
| --- | --- |
| [list targets](/consumer/cn/doc/harmonyos-guides/hdc#查询设备列表) | 查询已连接的所有目标设备。 |
| [wait](/consumer/cn/doc/harmonyos-guides/hdc#等待设备正常连接) | 等待设备正常连接。 |
| [tmode usb](/consumer/cn/doc/harmonyos-guides/hdc#usb调试和无线调试切换) | 3.1.0e版本起已废弃，不会操作设备连接通道，需在设备设置界面通过USB调试开关设置。 |
| [tmode port](/consumer/cn/doc/harmonyos-guides/hdc#打开设备网络连接通道) | 打开设备网络连接通道。 |
| [tmode port close](/consumer/cn/doc/harmonyos-guides/hdc#关闭网络连接通道) | 关闭设备网络连接通道。 |
| [tconn](/consumer/cn/doc/harmonyos-guides/hdc#tcp连接设备) | 指定连接设备：通过“IP:port”来指定连接的设备。 |
| [shell](/consumer/cn/doc/harmonyos-guides/hdc#执行交互命令) | 在设备端执行单次命令，例如hdc shell ls。无命令参数可进入设备端终端执行命令。 |
| [install](/consumer/cn/doc/harmonyos-guides/hdc#安装应用文件) | 安装指定的应用文件。 |
| [uninstall](/consumer/cn/doc/harmonyos-guides/hdc#卸载应用) | 卸载指定的应用包。 |
| [file send](/consumer/cn/doc/harmonyos-guides/hdc#本地发送文件至远端设备) | 从本地发送文件至远端设备。 |
| [file recv](/consumer/cn/doc/harmonyos-guides/hdc#接收远端设备文件至本地) | 接收远端设备文件至本地。 |
| [fport ls](/consumer/cn/doc/harmonyos-guides/hdc#查询端口转发任务列表) | 列出全部转发端口任务。 |
| [fport](/consumer/cn/doc/harmonyos-guides/hdc#创建正向端口转发任务) | 设置正向端口转发任务：监听“主机端口”，接收请求并转发到“设备端口”。 |
| [rport](/consumer/cn/doc/harmonyos-guides/hdc#创建反向端口转发任务) | 设置反向端口转发任务：监听“设备端口”，接收请求并转发到“主机端口”。 |
| [fport rm](/consumer/cn/doc/harmonyos-guides/hdc#删除端口转发任务) | 删除指定的端口转发任务。 |
| [start](/consumer/cn/doc/harmonyos-guides/hdc#启动服务) | 启动hdc服务进程。 |
| [kill](/consumer/cn/doc/harmonyos-guides/hdc#终止服务) | 终止hdc服务进程。 |
| [hilog](/consumer/cn/doc/harmonyos-guides/hdc#打印设备端日志) | 打印设备端的日志信息。 |
| [jpid](/consumer/cn/doc/harmonyos-guides/hdc#显示设备已打开应用的进程pid) | 显示设备上已打开应用的进程pid。 |
| [track-jpid](/consumer/cn/doc/harmonyos-guides/hdc#实时显示设备已打开应用的进程pid和应用名) | 实时显示设备上已打开应用的进程pid和应用名。 |
| [target boot](/consumer/cn/doc/harmonyos-guides/hdc#重启目标设备) | 重启目标设备。 |
| [keygen](/consumer/cn/doc/harmonyos-guides/hdc#安全相关命令) | 生成一个新的密钥对。 |
| [version](/consumer/cn/doc/harmonyos-guides/hdc#查询hdc版本号) | 打印hdc版本信息，也可使用hdc -v打印版本信息。 |
| [checkserver](/consumer/cn/doc/harmonyos-guides/hdc#查询客户端和服务器进程版本) | 获取客户进程与服务进程版本信息。 |
| [bugreport](/consumer/cn/doc/harmonyos-guides/hdc#导出系统信息) | 导出系统信息 |

## 基本使用方法

以USB调试方式为例，执行命令前请在设备上开启USB调试功能，用USB线连接设备和电脑。

### 查询连接的设备

收起

自动换行

深色代码主题

复制

```
1. hdc list targets
```

### 执行shell命令

收起

自动换行

深色代码主题

复制

```
1. hdc shell echo "Hello world"
```

### 常用调试工具

hdc支持和其他调试工具配套使用，工具列表如下：

展开

| 命令 | 说明 |
| --- | --- |
| [aa](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/aa-tool) | 应用调试工具 |
| [bm](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/bm-tool) | 包管理工具 |
| [cem](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/cem-tool) | 公共事件管理工具 |
| [anm](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/anm-tool) | 通知管理工具 |
| [edm](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/edm-tool) | 企业设备管理工具 |
| [param](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/param-tool) | 操作系统参数管理工具 |
| [power-shell](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/power-shell) | 设备电源状态转换工具 |
| [atm](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/atm-tool) | 程序访问控制管理工具 |
| [hilog](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hilog) | 日志管理工具 |
| [hidumper](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hidumper) | 系统信息导出工具 |
| [hitrace](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hitrace) | 系统打点及采集工具 |
| [hiperf](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hiperf) | 性能分析工具 |
| [uinput](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/uinput) | 模拟操作工具 |
| [mediatool](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/mediatool) | 媒体资源库工具 |
| [devicedebug](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/devicedebug-tool) | 调试应用发送信号工具 |
| [rawheap-translator](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/rawheap-translator) | rawheap文件解析工具 |
| [UItest](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/uitest-guidelines) | UI测试框架 |
| [HiSmartPerf Device daemon](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/smartperf-guidelines#section17658386337) | HiSmartPerf Device-daemon端工具命令 |
| [wukong](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/wukong-guidelines) | wukong稳定性工具 |

### 获取帮助

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

收起

自动换行

深色代码主题

复制

```
1. hdc -h [verbose]
2. hdc help
```

展开

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

**返回信息**：

展开

| 返回信息 | 说明 |
| --- | --- |
| OpenHarmony device connector(hdc) ...  ---------------------------------global commands:----------------------------------  -h/help [verbose] - Print hdc help, 'verbose' for more other cmds  ...（此处省略详细帮助信息） | hdc命令使用帮助信息。 |

注意

使用hdc时如出现异常，可尝试通过hdc kill -r命令终止异常进程并重启hdc服务。

如出现hdc list targets无法获取设备信息的情况，请参见[设备无法识别](/consumer/cn/doc/harmonyos-guides/hdc#设备无法识别)章节。

## 设备连接管理

### 查询设备列表

收起

自动换行

深色代码主题

复制

```
1. hdc list targets [-v]
```

**参数**：

展开

| 参数名 | 说明 |
| --- | --- |
| -v | 显示设备更多详情。 |

**返回信息**：

展开

| 返回信息 | 说明 |
| --- | --- |
| 设备标识符列表 | 已连接的设备标识符列表。  命令添加-v参数显示更多详情：设备标识符、连接方式（TCP/USB）、连接状态（Unknown/Ready/Connected/Offline/Unauthorized）、设备名称和hdc标识。 |
| 设备标识符 Unauthorized | 设备处于未授权状态。 |
| [Empty] | 没有查询到设备信息。 |

**使用方法**：

收起

自动换行

深色代码主题

复制

```
1. $ hdc list targets
2. connect-key1
3. ...

5. $ hdc list targets -v
6. connect-key1            USB     Connected       localhost       hdc
7. 127.0.0.1:5555          TCP     Offline         localhost       hdc
8. connect-key2            USB     Offline         localhost       hdc
9. ...
```

### 连接指定的目标设备

收起

自动换行

深色代码主题

复制

```
1. hdc -t [connect-key] [command]
```

**参数**：

展开

| 参数名 | 说明 |
| --- | --- |
| -t | 通过设备标识符连接指定目标设备。  连接单台设备时为可选参数，连接多台设备时为必填参数。 |
| command | hdc支持的命令。 |

说明

connect-key为每个设备唯一的标识符。通过USB连接，标识符为设备序列号；通过网络无线连接设备，标识符格式为IP:port。

**返回信息**：

展开

| 返回信息 | 说明 |
| --- | --- |
| 正常执行返回信息，参考[命令列表](/consumer/cn/doc/harmonyos-guides/hdc#命令列表)具体说明。 | - |
| [Fail]Not match target founded, check connect-key please. | 使用-t参数匹配不存在的connect-key，请检查connect-key是否正确。 |
| [Fail]Device not founded or connected. | 设备未找到或未连接。 |
| [Fail]ExecuteCommand need connect-key? please confirm a device by help info. | 请确保已连接设备并打开调试开关。 |
| Unknown operation command... | 不支持的命令。 |

说明

命令返回的错误信息仅供开发者参考，后续可能会优化调整。请勿将此类信息用于自动化脚本或程序的逻辑判断，实际程序交互建议使用系统异常提供的标准错误码，具体详情可参考[hdc错误码](/consumer/cn/doc/harmonyos-guides/hdc#hdc错误码)。

**使用方法**：

此调试方法需要与具体的操作命令搭配使用，下面以shell命令为例：

收起

自动换行

深色代码主题

复制

```
1. $ hdc list targets
2. connect-key1
3. ...

5. $ hdc -t connect-key1 shell echo "hello world!"
6. hello world!
```

### 等待设备正常连接

收起

自动换行

深色代码主题

复制

```
1. hdc wait # 等待设备正常连接。
2. hdc -t [connect-key] wait # 等待指定的设备正常连接，connect-key需要替换为指定的设备标识符。
```

**参数**：

展开

| 参数名 | 说明 |
| --- | --- |
| -t connect-key | 3.1.0a版本新增参数：  连接单台设备时，为可选参数。  连接多台设备时，为必填参数。 |

**返回信息**：

展开

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

**使用方法**：

收起

自动换行

深色代码主题

复制

```
1. # 如果设备正常连接，则命令执行结束无任何打印信息。
2. $ hdc wait # 单台设备。
3. $ hdc -t connect-key1 wait # 多设备需使用-t指定连接设备。
```

### USB连接场景

**环境确认**

展开

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

**连接步骤**

1. 通过USB连接设备。
2. 执行以下命令查看已连接设备：

   收起

   自动换行

   深色代码主题

   复制

   ```
   1. hdc list targets
   ```

   返回信息中包含设备标识符，表示USB连接成功。
3. 查询到设备后，运行相关命令与设备交互。如果希望不带设备标识符执行hdc命令，需要确认设备不在TCP连接模式（hdc list targets查询的设备不包含IP:port形式的连接信息），直接连接即可，例如：

   收起

   自动换行

   深色代码主题

   复制

   ```
   1. hdc shell
   ```

### TCP连接场景

注意

TCP调试功能尚未稳定，建议仅在测试环境中使用。

**环境确认**

展开

| 确认项 | 正常 | 异常处理 |
| --- | --- | --- |
| 网络连接 | 电脑、设备处于同一网络。 | 连接同一WiFi。 |
| 网络状态 | telnet IP:port正常，网速稳定。 | 请选择稳定网络。 |
| hdc环境变量 | 终端命令行输入hdc -h有回显帮助信息内容。 | 参见[环境准备](/consumer/cn/doc/harmonyos-guides/hdc#环境准备)章节。 |

**连接步骤**

1. 在设备端设置>系统>开发者选项>无线调试>打开无线调试。
2. 记录设备界面显示的IP地址和端口，格式为IP:port。
3. 通过tcp连接设备，执行以下命令：

   收起

   自动换行

   深色代码主题

   复制

   ```
   1. hdc tconn IP:port
   ```

   命令执行返回“Connect OK”表示连接成功。
4. 查看已连接设备，执行以下命令：

   收起

   自动换行

   深色代码主题

   复制

   ```
   1. hdc list targets
   ```

   返回信息为IP:port格式。

   说明

   如果需要关闭TCP连接模式，可在设备中关闭无线调试开关或断开网络连接。

### 远程连接场景

远程连接场景指客户端（通常是开发者使用的本地电脑）通过网络与服务器（通常是连接了调试设备的服务器或开发机）建立连接，实现客户端对目标设备的远程调试，控制和管理。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/cd/v3/OCyjUbAgQZmiQjOPo-U4ng/zh-cn_image_0000002540771646.png?HW-CC-KV=V1&HW-CC-Date=20260414T050858Z&HW-CC-Expire=86400&HW-CC-Sign=DBCFF89AB80D4317924EAA8668C3F782CD4BEF3C0C00DD25175C8DEC0ADE0134)

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

收起

自动换行

深色代码主题

复制

```
1. hdc -s [IP:]port [command]
```

展开

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

**参数**：

展开

| 参数 | 说明 |
| --- | --- |
| IP | 可选参数，指定监听的IP地址，支持IPv4和IPv6。不指定IP默认监听本机127.0.0.1。 |
| port | 指定监听的端口，范围为1~65535。 |
| command | hdc支持的命令，参见[hdc命令列表](/consumer/cn/doc/harmonyos-guides/hdc#hdc命令列表)。 |

**返回信息**：

展开

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

**使用方法**

收起

自动换行

深色代码主题

复制

```
1. # 在已有服务进程，且服务进程的网络监听参数为127.0.0.1:8710的环境中，执行查询设备命令。
2. $ hdc -s 127.0.0.1:8710 list targets
```

**连接步骤**

1. 服务器配置

   服务器通过USB连接对应hdc设备后，执行以下命令：

   收起

   自动换行

   深色代码主题

   复制

   ```
   1. $ hdc kill          # 关闭本地hdc服务。
   2. $ hdc -s IP:8710 -m # 启动网络转发的hdc服务，
   3. # 其中IP为服务器自身的IP，windows可通过ipconfig查询，unix系统可通过ifconfig查询，
   4. # 8710是默认端口号，也可设置其他端口号如：18710，
   5. # 启动后服务器将打印日志。
   ```
2. 客户端连接

   客户端可以连通服务器IP地址，满足条件后执行以下命令：

   收起

   自动换行

   深色代码主题

   复制

   ```
   1. $ hdc -s IP:8710 [command] # 其中IP为服务器IP，8710为第一步服务器进程启动时设置的端口号，
   2. # 如果端口号有变化，这里也需要变更，
   3. # command可以为任意hdc可用命令，例如list targets。
   ```

说明

当命令行中明确使用 -s 参数指定服务器进程端口时，系统将忽略OHOS\_HDC\_SERVER\_PORT环境变量中定义的端口设置。使用 -s 参数指定服务器地址时，如果监听地址不是本地回环地址（如127.0.0.1），需注意访问安全问题。

### USB调试和无线调试切换

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

展开

| 命令 | 说明 |
| --- | --- |
| tmode usb | 该命令已废弃，不会操作设备连接通道，请在设备设置界面通过USB调试开关进行设置。 |
| tmode port [port-number] | 打开设备网络连接通道：设备端守护程序会重启，已建立的连接需要重新连接。 |
| tmode port close | 关闭设备网络连接通道：设备端守护程序会重启，已建立的连接需要重新连接。 |
| tconn IP:port [-remove] | 连接指定设备，使用“IP:port”指定，使用-remove参数断开。 |

说明

推荐通过设备端的USB调试开关和无线调试开关来控制连接通道。

### 打开设备网络连接通道

命令格式如下：

收起

自动换行

深色代码主题

复制

```
1. 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。 |

**使用方法**：

收起

自动换行

深色代码主题

复制

```
1. $ hdc tmode port 65512
2. Set device run mode successful.
```

注意

切换前，请确保条件满足：远端设备与近端电脑处于同一网络，可通过ping命令检查：

1. 近端电脑在命令行中执行命令ping 远端设备的IP地址；
2. 如果能接收到远端设备的回应数据包，表明二者处于同一网络。

如不满足以上条件，切勿使用该命令进行切换。

执行完毕后，远端守护程序将退出并重启，需要重新连接。

### 关闭网络连接通道

命令格式如下：

收起

自动换行

深色代码主题

复制

```
1. hdc tmode port close
```

**返回信息**：

展开

| 返回信息 | 说明 |
| --- | --- |
| [Fail]ExecuteCommand need connect-key. | 设备列表为空，无法执行命令。 |

**使用方法**：

收起

自动换行

深色代码主题

复制

```
1. hdc tmode port close
```

说明

执行完毕后，远端设备上的守护程序将退出并重启，需要重新连接。

### TCP连接设备

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

收起

自动换行

深色代码主题

复制

```
1. hdc tconn IP:port [-remove]
```

**参数**：

展开

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

**返回信息**：

展开

| 返回信息 | 说明 |
| --- | --- |
| Connect OK. | 连接成功。 |
| [Info]Target is connected, repeat operation. | 设备当前已连接。 |
| [Fail]Connect failed. | 连接失败。 |

**使用方法**：

收起

自动换行

深色代码主题

复制

```
1. $ hdc tconn 192.168.0.1:8888
2. Connect OK

4. # 断开指定网络设备连接。
5. $ hdc tconn 192.168.0.1:8888 -remove
```

## 执行交互命令

收起

自动换行

深色代码主题

复制

```
1. hdc shell [-b bundlename] [command]
```

**参数**：

展开

| 参数 | 说明 |
| --- | --- |
| -b bundlename | 3.1.0e版本新增参数。指定可调试应用包名，在可调试应用数据目录内，以非交互式模式执行命令。  [命令行方式访问应用沙箱](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-device-file-explorer#section48216711204)。  此参数当前仅支持以非交互式模式执行命令，不支持缺省command参数执行命令进入交互式shell会话。  未配置此参数时，默认执行路径为系统根目录。 |
| command | 需要在设备上执行的单次命令，不同类型或版本的系统支持的command命令有所差异，可以通过hdc shell ls /system/bin查阅支持的命令列表。当前大多数命令都是由[toybox](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/toybox)提供，可通过 hdc shell toybox --help 获取命令帮助。  缺省该参数，hdc将会启动一个交互式的shell会话，开发者可以在命令提示符下输入命令，比如 ls、cd、pwd 等。 |

说明

使用参数[-b bundlename]指定包名，该包名对应的已安装应用必须满足以下条件：使用调试证书签名，并且已在设备上启动。有关如何申请调试证书及签名可参考：[申请调试证书](https://developer.huawei.com/consumer/cn/doc/app/agc-help-add-debugcert-0000001914263178)。

**返回信息**：

展开

| 返回信息 | 说明 |
| --- | --- |
| 交互命令返回内容。 | 返回内容详情请参见其他交互命令返回内容。 |
| /bin/sh: XXX : inaccessible or not found. | 不支持的交互命令。 |
| [Fail]具体失败信息。 | 执行失败，参见[hdc错误码](/consumer/cn/doc/harmonyos-guides/hdc#hdc错误码)。 |

**使用方法**：

收起

自动换行

深色代码主题

复制

```
1. # 进入交互式模式执行命令。
2. $ hdc shell
3. $

5. # 以非交互式模式执行命令。
6. $ hdc shell "ps -ef | grep hdcd"
7. shell         39491      1 1 14:40:58 ?     00:00:00 hdcd

9. # 查询全部可用命令。
10. $ hdc shell help -a
11. ---toybox---------------------------------------------------------------------

13. usage: toybox [--long | --help | --version | [command] [arguments...]]

15. With no arguments, shows available commands. First argument is
16. name of a command to run, followed by any arguments to that command.

18. --long  Show path to each command
19. ...

21. # 在指定包名的应用数据目录内以非交互式模式执行命令，支持touch、rm、ls、stat、cat、mkdir等命令。
22. $ hdc shell -b com.example.myapplication ls data/storage/el2/base/
```

## 应用管理

展开

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

### 安装应用文件

应用安装功能在设备端集成bm模块[安装命令（install）](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/bm-tool#安装命令install)，简化了安装流程，开发者可以在电脑端直接执行命令完成应用安装。命令格式如下：

收起

自动换行

深色代码主题

复制

```
1. hdc install [-cwd path|-r|-s|-w waitingTime|-u userId|-p|-h] src
```

**参数**：

展开

| 参数名 | 说明 |
| --- | --- |
| src | 应用安装包的文件路径。支持安装[HAP](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hap-package)、应用内[HSP](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/in-app-hsp)。从API version 22开始，支持安装[APP包](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/application-package-glossary#app)。 |
| -cwd | 修改工作目录。  用于在应用安装时，切换src到指定path。例如，初始安装应用为test.hap，所在目录为C:\，实际安装应用文件路径为C:\test.hap；如果使用-cwd "D:\"，实际安装应用文件路径为D:\test.hap。 |
| -r | 可选参数，覆盖安装一个HAP/HSP。默认缺省，缺省时表示覆盖安装。 |
| -s | 安装应用HSP时为必选参数，其他场景为可选参数。用于指定待安装应用间HSP的路径。指定目录的时候，每个路径目录下只能存在一个HSP。 |
| -w | 可选参数，安装HAP时指定bm工具等待时间，最短的等待时长为180s，最长的等待时长为600s，默认缺省为180s。 |
| -u | 可选参数，指定[用户](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/bm-tool#userid)，默认在当前活跃用户下安装应用。 |
| -p | 可选参数，指定待安装的HAP/HSP路径，多HAP/HSP应用可指定多HAP/HSP所在文件夹路径。从API version 22开始，支持指定待安装的APP路径，也可指定只存在一个APP的文件夹路径。 |
| -h | 可选参数，显示bm模块[安装命令（install）](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/bm-tool#安装命令install)帮助信息。 |

**返回信息**：

展开

| 返回信息 | 说明 |
| --- | --- |
| [Info]App install path:XXX msg:install bundle successfully.  AppMod finish. | 成功情况下返回安装信息及AppMod finish完成的通知。 |
| 具体安装失败原因。 | 失败情况下返回安装失败信息。 |

**使用方法**：

注意

执行install命令使用bm模块命令参数，对-w和-u参数需参数值组合使用的情况，需将参数变量和参数值放在引号内使用，如"-w 180"，"-u 100"，防止参数解析异常导致命令执行失败。

收起

自动换行

深色代码主题

复制

```
1. # 安装example.hap包示例。
2. $ hdc install D:\example.hap
3. [Info]App install path:D:\example.hap msg:install bundle successfully.
4. AppMod finish

6. # 安装example.app包示例。
7. $ hdc install D:\example.app
8. [Info]App install path:D:\example.app msg:install bundle successfully.
9. AppMod finish

11. # 安装example.hap包示例（-r为bm模块install命令支持参数，覆盖安装）。
12. $ hdc install -r D:\example.hap
13. [Info]App install path:D:\example.hap msg:install bundle successfully.
14. AppMod finish

16. # 安装example.hsp包示例（-s为bm模块install命令支持参数，安装hsp必选参数）。
17. $ hdc install -s D:\example.hsp
18. [Info]App install path:D:\example.hsp msg:install bundle successfully.
19. AppMod finish

21. # 安装example.hap包示例（-w为bm模块install命令支持参数，指定bm工具等待时间）。
22. $ hdc install "-w 180" D:\example.hap
23. [Info]App install path:D:\example.hap msg:install bundle successfully.
24. AppMod finish

26. # 安装example.hap包示例（-u为bm模块install命令支持参数，指定用户id）。
27. $ hdc install "-u 100" D:\example.hap
28. [Info]App install path:D:\example.hap msg:install bundle successfully.
29. AppMod finish

31. # 安装D:\hap_dir下应用示例（-p为bm模块install命令支持参数，指定安装路径）。
32. $ hdc install -p D:\hap_dir
33. [Info]App install path:D:\hap_dir msg:install bundle successfully.
34. AppMod finish
```

### 卸载应用

应用卸载功能在设备端集成bm模块[卸载命令（uninstall）](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/bm-tool#卸载命令uninstall)，简化了卸载流程，开发者可以在电脑端直接执行命令完成应用卸载。命令格式如下：

收起

自动换行

深色代码主题

复制

```
1. hdc uninstall [-n|-k|-s|-h] bundlename
```

**参数**：

展开

| 参数名 | 说明 |
| --- | --- |
| bundlename | 应用安装包。 |
| -n | 可选参数，指定Bundle名称卸载应用。 |
| -k | 可选参数，卸载应用时保存应用数据。默认卸载应用时不保存应用数据。 |
| -s | 根据场景判断，卸载应用间HSP时必选参数，其他场景为可选参数。卸载指定的共享库。 |
| -h | 可选参数，bm模块[卸载命令（uninstall）](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/bm-tool#卸载命令uninstall)帮助信息。 |

**返回信息**：

展开

| 返回信息 | 说明 |
| --- | --- |
| [Info]App uninstall path: msg:uninstall bundle successfully.  AppMod finish. | 成功情况下返回卸载信息和AppMod finish完成的通知。 |
| 具体卸载失败的原因。 | 失败时返回卸载失败的信息。 |

**使用方法**：

收起

自动换行

深色代码主题

复制

```
1. # 卸载com.ohos.example包示例。
2. $ hdc uninstall com.ohos.example
3. [Info]App uninstall path: msg:uninstall bundle successfully.
4. AppMod finish

6. # 卸载com.ohos.example包示例（-n为bm模块uninstall命令支持参数，指定bundle名称）。
7. $ hdc uninstall -n com.ohos.example
8. [Info]App uninstall path: msg:uninstall bundle successfully.
9. AppMod finish

11. # 卸载com.ohos.example包示例（-k为bm模块uninstall命令支持参数，卸载应用时保存应用数据）。
12. $ hdc uninstall -k com.ohos.example
13. [Info]App uninstall path: msg:uninstall bundle successfully.
14. AppMod finish

16. # 卸载com.ohos.example包示例（-s为bm模块uninstall命令支持参数，卸载hsp时为必选参数）。
17. $ hdc uninstall -s com.ohos.example
18. [Info]App uninstall path: msg:uninstall bundle successfully.
19. AppMod finish
```

## 文件传输

展开

| 命令 | 说明 |
| --- | --- |
| file send SOURCE DEST | 从本地发送文件至远端设备。 |
| file recv DEST SOURCE | 从远端设备接收文件至本地。 |

### 本地发送文件至远端设备

命令格式如下：

收起

自动换行

深色代码主题

复制

```
1. hdc file send [-a|-sync|-z|-m|-cwd path|-b bundlename] SOURCE DEST
```

**参数**：

展开

| 参数名 | 说明 |
| --- | --- |
| SOURCE | 本地待传输的文件路径。 |
| DEST | 远程目标文件路径。  从API version 21开始，媒体库文件支持通过hdc进行部分操作（低版本使用会提示[Fail]Error opening file: ...）。  媒体库文件路径：/mnt/data/<uid>/media\_fuse/Photo/目录及其子目录，<uid>为当前用户的id。  通过hdc对媒体库操作指导参见[mediatool](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/mediatool#hdc命令)。 |
| -a | 保留文件修改时间戳。 |
| -sync | 只传输文件mtime有更新的文件。  mtime（modified timestamp）：修改后的时间戳。 |
| -z | 通过LZ4格式压缩传输，此功能未开放，请勿使用。 |
| -m | 文件传输时同步文件DAC权限，uid，gid，MAC权限。  DAC（Discretionary Access Control）：自主访问控制，  uid（User identifier）：用户标识符（或用户ID），  gid（Group identifier）：组标识符（或组ID），  MAC（Mandatory Access Control）：强制访问控制（或非自主访问控制）。 |
| -cwd | 修改工作目录。  用于在文件传输时，切换SOURCE到指定path。例如，初始发送文件为test，所在目录为/data，实际发送文件路径为/data/test；如果使用-cwd "/user/"，实际发送文件路径为/user/test。 |
| -b | 3.1.0e版本新增参数（低版本使用会提示[Fail]Unknown file option: -b），用于指定可调试应用包名。  使用方法可参考[通过命令往应用沙箱目录中发送文件](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-device-file-explorer#section48216711204)。 |
| bundlename | 指定可调试应用包名。 |

**返回信息**：

展开

| 返回信息 | 说明 |
| --- | --- |
| FileTransfer finish, Size:1, File count = 1, time:10ms rate:0.00kB/s | 文件发送成功时，返回传输成功的确认信息finish完成的通知。 |
| 具体文件发送失败的原因。 | 文件发送失败时，返回传输失败的具体错误信息。 |

**使用方法**：

收起

自动换行

深色代码主题

复制

```
1. $ hdc file send test /test/
2. FileTransfer finish, Size:xxx, File...

4. $ hdc file send -b com.example.myapplication test /test/ # 导入test文件到com.example.myapplication应用沙箱。
5. FileTransfer finish, Size:xxx, File...

7. $ hdc file send D:\dest\相机 /mnt/data/100/media_fuse/Photo/ # 媒体库操作，导入“D:\dest\相机”的所有文件到/mnt/data/100/media_fuse/Photo/相机/。
8. FileTransfer finish, Size:xxx, File...

10. $ hdc file send D:\dest\新建目录 /mnt/data/100/media_fuse/Photo/相机/ # 媒体库操作，不支持创建目录。
11. [Fail][E005005] Error create directory: ..., path:/mnt/data/100/media_fuse/Photo/相机//新建目录
```

### 接收远端设备文件至本地

命令格式如下：

收起

自动换行

深色代码主题

复制

```
1. hdc file recv [-a|-sync|-z|-m|-cwd path|-b bundlename] DEST SOURCE
```

**参数**：

展开

| 参数名 | 说明 |
| --- | --- |
| SOURCE | 本地待接收的文件路径。 |
| DEST | 远程待传输的文件路径。  从API version 21开始，媒体库文件支持通过hdc进行部分操作（低版本使用会提示[Fail]Error opening file: ...）。  媒体库文件路径：/mnt/data/<uid>/media\_fuse/Photo/目录及其子目录，<uid>为当前用户的id。  媒体库操作更多信息参见[mediatool](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/mediatool#hdc命令)。 |
| -a | 保留文件修改时间戳。 |
| -sync | 只传输文件mtime有更新的文件。  mtime（modified timestamp）：修改后的时间戳。 |
| -z | 通过LZ4格式压缩传输，此功能未开放，请勿使用。 |
| -m | 文件传输时同步文件DAC权限，uid，gid，MAC权限。  DAC（Discretionary Access Control）：自主访问控制，  uid（User identifier）：用户标识符（或用户ID），  gid（Group identifier）：组标识符（或组ID），  MAC（Mandatory Access Control）：强制访问控制（或非自主访问控制）。 |
| -cwd | 修改工作目录。  用于在文件传输时，切换SOURCE到指定path。例如，初始接收文件目录为/data/，如果使用-cwd "/user/"，实际接收文件目录为/user/。 |
| -b | 3.1.0e版本新增参数，用于传输指定的可调试应用进程应用数据目录下的文件。  使用方法可参考[从沙箱目录中下载文件到本地计算机](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-device-file-explorer#section48216711204)。 |
| bundlename | 可调试应用进程的包名。 |

**返回信息**：

展开

| 返回信息 | 说明 |
| --- | --- |
| FileTransfer finish, Size:1, File count = 1, time:10ms rate:0.00kB/s | 文件接收成功时，返回传输成功的确认信息finish完成的通知。 |
| 具体文件接收失败的原因。 | 文件接收失败时，返回传输失败的具体错误信息。 |

**使用方法**：

收起

自动换行

深色代码主题

复制

```
1. $ hdc file recv /test/test ./
2. FileTransfer finish, Size:xxx, File...

4. $ hdc file recv -b com.example.myapplication /test/test # 导出com.example.myapplication应用沙箱文件/test/test。
5. FileTransfer finish, Size:xxx, File...

7. $ hdc file recv /mnt/data/100/media_fuse/Photo/相机/文件A # 导出文件A。
8. FileTransfer finish, Size:xxx, File...

10. $ hdc file recv /mnt/data/100/media_fuse/Photo/相机 # 导出相机目录及里面的文件。
11. FileTransfer finish, Size:xxx, File...
```

说明

使用参数[-b bundlename]指定包名，应满足条件：指定包名的已安装应用为“使用调试证书签名的应用”且在设备上已启动，如何申请调试证书及签名可参考：[申请调试证书](https://developer.huawei.com/consumer/cn/doc/app/agc-help-add-debugcert-0000001914263178)。

**版本更新说明**：从3.1.0a版本开始，支持使用中文字符作为文件传输命令参数，便于多语言环境下使用。

## 端口转发

展开

| 命令 | 说明 |
| --- | --- |
| fport ls | 列出所有端口转发任务。 |
| fport localnode remotenode | 设置正向端口转发任务：监听“电脑端端口”(localnode)请求并转发到“设备端端口”(remotenode)。任务格式为<转发类型>:<转发端口>，如"tcp:1234"。 |
| rport remotenode localnode | 设置反向端口转发任务：监听“设备端端口”(remotenode)请求并转发到“电脑端端口”(localnode)。任务格式为<转发类型>:<转发端口>，如"tcp:1234"。 |
| fport rm taskstr | 删除指定的端口转发任务。 |

说明

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

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

### 查询端口转发任务列表

查询所有的正向端口转发任务和反向端口转发任务，命令格式如下：

收起

自动换行

深色代码主题

复制

```
1. hdc fport ls
```

**返回信息**：

展开

| 返回信息 | 说明 |
| --- | --- |
| tcp:1234 tcp:1080 [Forward] | 正向端口转发任务。 |
| tcp:2080 tcp:2345 [Reverse] | 反向端口转发任务。 |
| [Empty] | 无端口转发任务。 |

**使用方法**：

收起

自动换行

深色代码主题

复制

```
1. $ hdc fport ls
2. connect-key tcp:2080 tcp:2345 [Reverse]
3. connect-key tcp:1234 tcp:1080 [Forward]
```

### 创建正向端口转发任务

设置正向端口转发任务，将指定的“电脑端端口”转发到“设备端端口”，命令格式如下：

收起

自动换行

深色代码主题

复制

```
1. hdc fport localnode remotenode
```

**返回信息**：

展开

| 返回信息 | 说明 |
| --- | --- |
| Forwardport result:OK. | 端口转发任务设置正常。 |
| [Fail]Incorrect forward command. | 端口转发任务设置失败，端口转发参数错误。 |
| [Fail]TCP Port listen failed at XXXX. | 端口转发任务设置失败，本地转发端口被占用。 |
| [Fail]Forward parament failed. | 端口转发任务格式有误、转发端口协议或端口范围有误。 |
| [Fail]Not support forward-type. | 当前平台不支持参数中使用的转发端口协议。 |

**使用方法**：

收起

自动换行

深色代码主题

复制

```
1. $ hdc fport tcp:1234 tcp:1080
2. Forwardport result:OK
```

说明

创建正向端口转发任务时，电脑端使用TCP协议类型且指定端口为port，默认监听127.0.0.1:port。如果在启动服务进程时使用-e参数指定了监听主机IP地址，则电脑端会监听-e指定的IP:port。

### 创建反向端口转发任务

设置反向端口转发任务，系统将指定的“设备端口”转发到“主机端口”，命令格式如下：

收起

自动换行

深色代码主题

复制

```
1. hdc rport remotenode localnode
```

**返回信息**：

展开

| 返回信息 | 说明 |
| --- | --- |
| Forwardport result:OK. | 端口转发任务设置正常。 |
| [Fail]Incorrect forward command. | 端口转发任务设置失败，端口转发参数错误。 |
| [Fail]TCP Port listen failed at XXXX. | 端口转发任务设置失败，本地转发端口被占用。 |
| [Fail]Forward parament failed. | 端口转发任务格式有误、转发端口协议或端口范围有误。 |

**使用方法**：

收起

自动换行

深色代码主题

复制

```
1. $ hdc rport tcp:1234 tcp:1080
2. Forwardport result:OK
```

### 删除端口转发任务

删除指定的正向端口转发任务或反向端口转发任务，命令格式如下：

收起

自动换行

深色代码主题

复制

```
1. hdc fport rm taskstr
```

说明

taskstr参数为具体的正向端口转发任务或反向端口转发任务，建议优先通过hdc fport ls命令查询后删除。

**参数**：

展开

| 参数 | 说明 |
| --- | --- |
| 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. | 端口转发任务删除失败，指定的转发任务不存在。 |

**使用方法**：

收起

自动换行

深色代码主题

复制

```
1. $ hdc fport rm tcp:1234 tcp:1080
2. Remove forward ruler success, ruler:tcp:1234 tcp:1080
```

## 服务进程管理

展开

| 命令 | 说明 |
| --- | --- |
| start [-r] | 启动hdc服务进程，使用-r参数触发服务进程重新启动。 |
| kill [-r] | 终止hdc服务进程，使用-r参数触发服务进程重新启动。 |
| -p | 绕过对服务进程的查询步骤，用于快速执行客户端命令。 |
| -m | 使用前台启动模式启动服务进程。  前台启动模式（添加-m参数）：实时打印服务日志到客户端窗口。  后台启动模式（不添加-m参数）：客户端不打印服务日志，日志内容写入本地磁盘文件，具体文件存放路径可参考[服务器进程日志](/consumer/cn/doc/harmonyos-guides/hdc#服务器进程日志)。 |
| -e | 指定在TCP端口转发时，本地监听的IP地址，默认是127.0.0.1。该参数必须和-m一起使用。 |

### 启动服务

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

收起

自动换行

深色代码主题

复制

```
1. hdc start [-r]
```

**返回信息**：

展开

| 返回信息 | 说明 |
| --- | --- |
| 无返回信息 | 服务进程启动成功。 |

**使用方法**：

收起

自动换行

深色代码主题

复制

```
1. hdc start -r # 服务进程启动状态下，触发服务进程重新启动。
```

说明

当启动hdc服务进程且系统未检测到运行的服务进程时，日志等级的设置优先级如下：若在同一命令中指定了-l参数和配置了OHOS\_HDC\_LOG\_LEVEL环境变量，环境变量优先级高于-l参数；如果仅指定了-l参数，则采用该参数配置的日志等级；若两者均未指定，则服务进程将以默认日志等级LOG\_INFO启动。

### 终止服务

命令格式如下：

收起

自动换行

深色代码主题

复制

```
1. hdc kill [-r]
```

**返回信息**：

展开

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

**使用方法**：

收起

自动换行

深色代码主题

复制

```
1. $ hdc kill -r # 终止并重启服务进程，实际使用可执行hdc -l 5 kill -r命令查看详细重启的log。
2. Kill server finish

4. $ hdc kill # 终止服务进程。
5. Kill server finish
```

### 快速执行命令

绕过对服务进程的查询步骤，用于快速执行客户端命令。服务未启动时执行命令不会重新启动服务，使用参数前确保服务已正常启动。命令格式如下：

收起

自动换行

深色代码主题

复制

```
1. hdc -p [command]
```

**参数**：

展开

| 参数 | 说明 |
| --- | --- |
| command | hdc支持的命令。 |

**返回信息**：

展开

| 返回信息 | 说明 |
| --- | --- |
| Connect server failed. | 与服务器进程建立连接失败。 |

**使用方法**：

收起

自动换行

深色代码主题

复制

```
1. $ hdc start # 启动后台服务进程。

3. $ hdc -p list targets # 跳过检查，直接执行命令。
4. connect-key1
5. connect-key2
6. ...
```

说明

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

### 前台启动服务

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

收起

自动换行

深色代码主题

复制

```
1. hdc -m
```

**返回信息**：

展开

| 返回信息 | 说明 |
| --- | --- |
| Initial failed. | 服务进程初始化失败。 |
| [I][1970-01-01 00:00:00.000] Program running. Ver: X.X.Xx Pid:XXX.  ... | 正常打印对应等级的日志，显示服务器进程活动状态。 |

**使用方法**：

收起

自动换行

深色代码主题

复制

```
1. $ hdc -s 127.0.0.1:8710 -m # 指定当前服务进程的网络监听参数并启动服务进程。
2. [I][1970-01-01 00:00:00.000][4f28][xxxx.xxx:123] Program running. Ver: 3.1.0e Pid:12345
3. ...
4. $ hdc -e 0.0.0.0 -m # 指定端口转发本地监听IP地址为0.0.0.0并启动服务进程。
5. [I][1970-01-01 00:00:00.000][4f28][xxxx.xxx:123] Program running. Ver: 3.2.0b Pid:12345
6. ...
```

说明

1. 在前台启动模式下，可通过附加 -s 参数来指定服务进程的网络监听参数。如果既没有使用 -s 指定网络监听参数，也没有配置环境变量OHOS\_HDC\_SERVER\_PORT配置监听端口，系统将采用默认网络监听参数：127.0.0.1:8710。也可以通过-e参数来指定端口转发时本地主机监听的IP地址，如果没有使用-e参数，则默认监听127.0.0.1。
2. 在服务进程前台启动模式下，系统默认的日志输出等级为 LOG\_DEBUG。如果需要变更日志等级，可通过使用 -l 参数来进行相应的设置。
3. 在运行环境中，仅允许存在一个服务进程实例。如果运行环境中已存在一个活跃的后台服务进程，尝试在前台启动新的服务进程实例将无法成功。

## 设备操作

展开

| 命令 | 说明 |
| --- | --- |
| hilog [-h] | 打印设备端的日志信息，可通过hdc hilog -h查阅支持的参数列表。 |
| jpid | 显示设备上已打开应用的进程pid。 |
| track-jpid [-a|-p] | 实时显示设备上已打开应用的进程pid和应用包名，其中只有debug标签的应用可以被调试。不加参数时只显示已打开debug版本应用的进程pid和应用包名，使用-a参数会显示debug和release的进程标签，使用-p参数不显示debug和release的进程标签。 |
| target boot [-bootloader|-recovery] | 重启目标设备，使用-bootloader参数重启后进入fastboot模式，使用-recovery参数重启后进入recovery模式。 |
| target boot [MODE] | 重启目标设备，加参数重启后进入相应的模式，其中MODE为/bin/begetctl命令中reboot支持的参数，可通过hdc shell "/bin/begetctl -h | grep reboot"查看。 |

### 打印设备端日志

命令格式如下：

收起

自动换行

深色代码主题

复制

```
1. hdc hilog [-h]
```

**参数**：

展开

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

**返回信息**：

展开

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

**使用方法**：

收起

自动换行

深色代码主题

复制

```
1. $ hdc hilog -h
2. Usage:
3. -h --help
4. Show all help information.
5. Show single help information with option:
6. ...
```

### 显示设备已打开应用的进程pid

命令格式如下：

收起

自动换行

深色代码主题

复制

```
1. hdc jpid
```

**返回信息**：

展开

| 返回信息 | 说明 |
| --- | --- |
| 进程号列表 | 设备上已打开应用的pid。 |
| [Empty] | 设备上无打开的进程。 |

**使用方法**：

收起

自动换行

深色代码主题

复制

```
1. $ hdc jpid
2. 1234
3. 1080
4. ...
```

### 实时显示设备已打开应用的进程pid和应用名

实时显示设备上已打开应用的进程pid和应用名称，命令格式如下：

收起

自动换行

深色代码主题

复制

```
1. hdc track-jpid [-a|-p]
```

**参数**：

展开

| 参数 | 说明 |
| --- | --- |
| 不加参数 | 只显示已打开debug版本应用的进程pid和应用包名。 |
| -a | 显示debug和release应用的进程pid和包名/进程名，同时显示debug和release的标签。 |
| -p | 显示debug和release应用的进程pid和包名/进程名，但不显示debug和release的标签。 |

**返回信息**：

展开

| 返回信息 | 说明 |
| --- | --- |
| 进程号和包名/进程名列表。 | 不加参数时仅显示已打开应用的进程pid，使用-p参数额外显示应用包名，使用-a参数同时显示debug和release标签。 |
| [Empty] | 无开启JDWP调试协议的应用进程。 |

**使用方法**：

收起

自动换行

深色代码主题

复制

```
1. $ hdc track-jpid -a
2. 1234 com.example.hello release
3. ...

5. $ hdc track-jpid -p
6. 1234 com.example.hello
7. ...
```

### 重启目标设备

命令格式如下：

收起

自动换行

深色代码主题

复制

```
1. hdc target boot [-bootloader|-recovery]
2. hdc target boot [MODE]
```

**参数**：

展开

| 参数名 | 说明 |
| --- | --- |
| 不加参数 | 重启设备。 |
| -bootloader | 重启后进入fastboot模式。 |
| -recovery | 重启后进入recovery模式。 |
| MODE | 重启后进入MODE模式，MODE为/bin/begetctl命令中reboot支持的参数。 |

**使用方法**：

收起

自动换行

深色代码主题

复制

```
1. hdc target boot -bootloader  # 重启后进入fastboot模式。
2. hdc target boot -recovery    # 重启后进入recovery模式。
3. hdc target boot shutdown     # 关机。
```

## 安全相关命令

展开

| 命令 | 说明 |
| --- | --- |
| keygen FILE | 生成一个新的密钥对，并将私钥和公钥分别保存到FILE和FILE.pub，其中FILE为自定义的文件名。可指定目录，默认为当前工作目录。 |

命令格式如下：

收起

自动换行

深色代码主题

复制

```
1. hdc keygen FILE
```

**参数**：

展开

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

**使用方法**：

收起

自动换行

深色代码主题

复制

```
1. # 在当前目录下生成key和key.pub文件。
2. $ hdc keygen key
```

## 查询hdc版本号

展开

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

### 查询hdc客户端进程版本

查询hdc客户端进程的版本信息，命令格式如下：

收起

自动换行

深色代码主题

复制

```
1. hdc -v
```

**返回信息**：

展开

| 返回信息 | 说明 |
| --- | --- |
| Ver: X.X.Xx. | hdc（SDK）客户端进程版本信息。 |

**使用方法**：

收起

自动换行

深色代码主题

复制

```
1. $ hdc -v
2. Ver: 3.1.0e
```

### 查询hdc服务进程版本

查询hdc服务进程的版本信息，命令格式如下：

收起

自动换行

深色代码主题

复制

```
1. hdc version
```

**返回信息**：

展开

| 返回信息 | 说明 |
| --- | --- |
| Ver: X.X.Xx. | hdc（SDK）服务进程版本信息。 |

**使用方法**：

收起

自动换行

深色代码主题

复制

```
1. $ hdc version
2. Ver: 3.1.0e
```

### 查询客户端和服务器进程版本

命令格式如下：

收起

自动换行

深色代码主题

复制

```
1. hdc checkserver
```

**返回信息**：

展开

| 返回信息 | 说明 |
| --- | --- |
| Client version: Ver: X.X.Xx, Server version: Ver: X.X.Xx. | client（客户端），server（服务器）版本号。 |

**使用方法**：

收起

自动换行

深色代码主题

复制

```
1. $ hdc checkserver
2. Client version: Ver: 3.1.0e, Server version: Ver: 3.1.0e
```

## 导出系统信息

命令格式如下：

收起

自动换行

深色代码主题

复制

```
1. hdc bugreport [FILE]
```

**参数**：

展开

| 参数 | 说明 |
| --- | --- |
| FILE | 可选参数，指定系统信息存储文件名。可指定存储目录，默认存储到当前工作目录。 |

**返回信息**：

展开

| 返回信息 | 说明 |
| --- | --- |
| -------------------------------[base]-------------------------------  BuildId: xxx  RleaseType: xxx  OsVersion: default/default/default/default/xxx  DeviceType: default  Manufacture: default  ----- | 设备基本信息。 |

**使用方法**：

收起

自动换行

深色代码主题

复制

```
1. $ hdc bugreport
2. -------------------------------[base]-------------------------------

4. BuildId: xxx
5. RleaseType: xxx
6. OsVersion: default/default/default/default/xxx
7. DeviceType: default
8. Manufacture: default
9. -----
```

## hdc调试日志

### 服务器进程日志

**指定运行时日志等级**

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

收起

自动换行

深色代码主题

复制

```
1. hdc -l [level] [command]
```

**参数**：

展开

| 参数 | 说明 |
| --- | --- |
| [level] | 指定运行时日志等级，等级随数字递增。设置日志级别时会启用当前及以下所有等级类型。例如，设置日志等级为3，可打印1~3类型的所有日志。  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. 指定运行日志等级仅适用于当前进程（包括客户端与服务进程），无法更改已存在的进程日志等级。

**返回信息**：

展开

| 返回信息 | 说明 |
| --- | --- |
| 日志信息。 | 指定等级的日志打印信息。 |

**使用方法**：

收起

自动换行

深色代码主题

复制

```
1. # 客户端打印LOG_DEBUG及以下级别日志，以执行shell ls为例。
2. $ hdc -l 5 shell ls
3. [D][1970-01-01 00:00:00.000][12dc][xxxx.xxx:123] Mallocchannel:1234567
4. ...

6. # 服务进程前台模式启动指定LOG_LIBUSB级别日志。
7. $ hdc kill && hdc -l 6 -m
8. Kill server finish
9. [I][1970-01-01 00:00:00.000][4f28][xxxx.xxx:123] Program running. Ver: 3.1.0e Pid:12345
10. ...

12. # 服务进程后台启动模式指定LOG_LIBUSB级别日志。
13. $ hdc kill && hdc -l 6 start
14. Kill server finish
15. [D][1970-01-01 00:00:00.000][12dc][xxxx.xxx:123] Mallocchannel:1234567
16. ...
```

说明

使用-m参数可以以前台启动服务进程，从而直接观察前台日志输出。如果需要退出进程，可按下Ctrl+C。

以后台启动时，可以在hdc.log中观察日志输出。

**日志获取**

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

收起

自动换行

深色代码主题

复制

```
1. hdc kill
2. hdc -l 5 start
```

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

展开

| 平台 | 路径 | 备注 |
| --- | --- | --- |
| Windows | %temp%\ | 实际路径参考：C:\Users\用户名\AppData\Local\Temp  （实际使用请替换用户名变量）。 |
| Linux | /tmp/ | - |
| MacOS | $TMPDIR/ | 实际路径可通过echo $TMPDIR查看，执行cd $TMPDIR命令可直接跳转至相应目录。 |

日志文件类型包括：

展开

| 日志类型 | 日志名称格式 | 日志用途 | 备注 |
| --- | --- | --- | --- |
| 实时日志 | hdc.log | 实时记录服务器进程日志。 | 每次重启hdc服务进程，将会重命名原有日志并记录新的hdc.log。 |
| 历史日志临时文件 | hdc-%Y%m%d-%H%M%S.log | 转储历史日志归档生成的中间文件。 | 以时间2024年9月19日16:18:57.921为例，对应时间格式为：20240919-161857921，生成的日志临时文件名为：hdc-20240919-161857921.log。 |
| 历史日志归档文件 | hdc-%Y%m%d-%H%M%S.log.tgz | 压缩存储历史日志。 | 归档文件为.tgz类型压缩文件，可使用解压工具进行解压查看。以历史日志临时文件名hdc-20240919-161857921.log为例，对应的历史日志归档文件名为：hdc-20240919-161857921.log.tgz，历史日志归档文件生成后，对应的历史日志临时文件将自动删除。 |
| 实时日志缓存临时文件 | .hdc.cache.log | 实时日志产生的临时缓存。 | - |

### 设备端日志

使用hilog日志工具获取对应日志，命令如下：

收起

自动换行

深色代码主题

复制

```
1. hdc shell hilog -w start                              # 开启hilog日志落盘(已开启hilog日志工具再次执行会报错)。
2. hdc shell hilog -w stop                               # 关闭hilog日志落盘(已关闭hilog日志工具再次执行会报错)。
3. hdc shell ls /data/log/hilog                          # 查看已落盘hilog日志。
4. hdc file recv /data/log/hilog {local_path}            # 获取hilog已落盘日志（包含内核日志，local_path为本地路径，不同系统有所区别，这里未列举实际示例）。
```

## 可选配置项

### OHOS\_HDC\_SERVER\_PORT

默认值：8710。

用于设置服务器进程运行时监听的端口号，该端口用于客户端与服务器之间的数据通讯。

服务器进程启动时，默认会监听电脑的8710端口，客户端使用TCP协议通过此端口连接服务器。如果电脑的8710端口已经被使用或希望使用其他端口，可以通过添加环境变量OHOS\_HDC\_SERVER\_PORT到系统环境变量中来修改服务器进程启动时监听的端口号。可以设置的端口范围为1~65535。

例如，添加变量名为：OHOS\_HDC\_SERVER\_PORT，变量值可设置为任意未被占用的端口，如18710。

### OHOS\_HDC\_LOG\_LEVEL

默认值：3。

用于设置服务进程日志记录级别，日志级别详情参考：[服务器进程日志](/consumer/cn/doc/harmonyos-guides/hdc#服务器进程日志)指定运行时日志等级章节。

### OHOS\_HDC\_HEARTBEAT

默认：心跳功能开启。

用于设置服务器和守护程序的心跳功能开关。

服务器和守护程序启动后，默认会互相发送心跳数据包，收到心跳数据包后会记录在hdc的日志中，方便后期查看设备的连接情况。

服务器进程运行的电脑中配置环境变量OHOS\_HDC\_HEARTBEAT为“1”后，服务器会关闭心跳特性；当有设备连接这台电脑后，服务器会给守护程序发送心跳特性关闭的信息，双方不再互相发送心跳数据包。

设置为"1"表示关闭心跳功能，设置为其它数字表示开启心跳功能。

### OHOS\_HDC\_CMD\_RECORD

默认：hdc命令录制关闭。

用于设置hdc命令录制功能的开关。此功能仅记录执行的hdc命令，不记录命令的执行结果。

设置为"1"表示开启命令录制功能；不设置或者设置为其它数字表示关闭命令录制功能。

从API version 20开始，支持该参数。

录制日志的存放路径如下：

展开

| 平台 | 路径 | 备注 |
| --- | --- | --- |
| Windows | %temp%\hdc\_cmd\ | 实际路径参考：C:\Users\用户名\AppData\Local\Temp\hdc\_cmd<br/>（实际使用请替换用户名变量）。 |
| Linux | /tmp/hdc\_cmd/ | - |
| MacOS | $TMPDIR/hdc\_cmd/ | - |

### OHOS\_HDC\_ENCRYPT\_CHANNEL

默认：通道加密功能关闭。

用于设置服务器和守护程序之间的TCP连接通道加密功能开关。

设置为"1"表示开启TCP连接的通道加密功能；不设置或者设置为其它数字表示关闭通道加密功能。

从API version 20开始，支持该参数。

说明

服务器进程运行时默认监听电脑端的8710端口，可通过设置系统环境变量OHOS\_HDC\_SERVER\_PORT自定义监听的端口号。

### 环境变量配置方法

以配置OHOS\_HDC\_LOG\_LEVEL值为5举例，介绍环境变量配置方法，更详细的步骤可参考[环境准备](/consumer/cn/doc/harmonyos-guides/hdc#环境准备)。

展开

| 操作系统 | 配置方法 |
| --- | --- |
| Windows | 在电脑设置中搜索“查看高级系统设置”，在环境变量>系统变量>Path>编辑中，添加环境变量名称为OHOS\_HDC\_LOG\_LEVEL，变量值为5。配置完毕后点击确认。环境变量配置完成后，关闭并重启命令行或其他使用到HarmonyOS SDK的软件，以生效新配置的环境变量。 |
| Linux | 在~/.bash\_profile文件末尾追加内容export OHOS\_HDC\_LOG\_LEVEL=5并保存后，执行source ~/.bash\_profile生效当前环境变量。 |
| MacOS | 在~/.zshrc文件末尾追加内容export OHOS\_HDC\_LOG\_LEVEL=5并保存后，执行source ~/.zshrc生效当前环境变量。环境变量配置完成后，关闭并重启命令行或其他使用到HarmonyOS SDK的软件，以生效新配置的环境变量。 |

## hdc版本配套表

展开

| hdc版本 | API版本 | 新增特性 |
| --- | --- | --- |
| 3.1.0a | 12 | wait命令支持-t参数：详细说明参见[等待设备正常连接](/consumer/cn/doc/harmonyos-guides/hdc#等待设备正常连接)。 |
| 3.1.0e | 15及以上版本 | - file send命令支持-b参数：详细说明参见[文件传输](/consumer/cn/doc/harmonyos-guides/hdc#文件传输)。  - file recv命令支持-b参数：详细说明参见[文件传输](/consumer/cn/doc/harmonyos-guides/hdc#文件传输)。  - shell命令支持-b参数：详细说明参见[执行交互命令](/consumer/cn/doc/harmonyos-guides/hdc#执行交互命令)。 |
| 3.2.0b | 20 | - 端口转发任务支持监听远端主机IP：详细说明参见[创建正向端口转发任务](/consumer/cn/doc/harmonyos-guides/hdc#创建正向端口转发任务)。 |

注意

如果开发者当前运行的hdc版本较低，某些功能存在兼容性问题，需要根据功能特性提升版本时，可参考对应API版本说明下载最新版本。

## 常见问题

### 设备无法识别

**现象描述**

命令行执行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设备，说明设备未能被正确识别，开发者可以尝试以下方法解决：

1. 请尝试使用其他USB物理接口。
2. 更换USB数据线。
3. 使用其他计算机进行调试。
4. 启用设备的USB调试模式。
5. 当设备出现授权信任弹窗，请点击“信任”或“永久信任”。
6. 设备执行恢复出厂设置操作。

**情况二**：

存在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。

可能存在以下原因，可参考排查：

1. hdc或SDK版本与设备不匹配：如果设备更新到最新版本，可更新hdc或SDK工具至最新版本。
2. 端口被占用：

当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：

   收起

   自动换行

   深色代码主题

   复制

   ```
   1. netstat -an |grep 8710
   ```

   Windows：

   收起

   自动换行

   深色代码主题

   复制

   ```
   1. netstat -an |findstr 8710
   ```

   如存在抢占的软件，请关闭该软件进程或更换OHOS\_HDC\_SERVER\_PORT环境变量为其他端口号。
3. 排查未关闭的其他版本服务器进程。

   Windows：

   使用任务管理器>详细信息查询hdc.exe进程，右键打开文件所在位置，核对位置是否为配置的环境变量中的hdc文件位置，如果不一致，可尝试结束hdc.exe进程（执行hdc kill命令或者在任务管理器直接结束进程）并重新执行hdc命令。（关闭服务器进程后执行hdc命令会重启服务器）。

   Unix：

   使用ps -ef |grep hdc查询hdc后台服务器进程，核对进程启动位置是否为配置的环境变量中的hdc文件位置，如果不一致，可尝试结束hdc进程（hdc kill或者kill -9 hdc进程的pid）并重新执行hdc命令。（关闭服务器进程后执行hdc命令会重启服务器）。

**注册表异常**

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

1. 同时按下Win+R键，启动运行工具，输入栏输入regedit打开注册表；
2. 在注册表地址栏中输入以下内容并按回车键，即可进入USB类设备驱动程序的注册表；

   收起

   自动换行

   深色代码主题

   复制

   ```
   1. 计算机\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Class\{88bae032-5a81-49f0-bc3d-a4ff138216d6}
   ```
3. 找到UpperFilters，右键点击”修改”，**备份**并清空其中的数值数据内容（如果清空后无法解决问题，可以依照备份恢复）；
4. 刷新设备管理器，插拔USB接口，或重启计算机。

### Linux和MacOS系统非管理员权限运行hdc提示无法找到设备

**现象描述**

Linux和MacOS系统非管理员角色运行hdc后，使用USB方式连接设备后执行hdc list targets命令无法找到设备。

**可能原因&解决方法**

非管理员角色默认无USB设备操作权限，如果需要开启该权限，可按以下方法操作：

1. MacOS系统：停止hdc服务，使用sudo命令重新启动hdc服务。

   收起

   自动换行

   深色代码主题

   复制

   ```
   1. sudo hdc kill
   2. sudo hdc start
   ```
2. Linux系统：

   * （临时权限）设置USB设备操作权限最大化：

     收起

     自动换行

     深色代码主题

     复制

     ```
     1. sudo chmod -R 777 /dev/bus/usb/
     ```
   * （永久权限）永久修改USB设备权限：

     + 使用lsusb命令查找USB设备的vendorID和productID；
     + 创建一个新的udev规则；

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

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

       收起

       自动换行

       深色代码主题

       复制

       ```
       1. $ sudo vim /etc/udev/rules.d/90-myusb.rules
       2. SUBSYSTEMS=="usb", ATTRS{idVendor}=="067b", ATTRS{idProduct}=="2303", GROUP="users", MODE="0666"
       ```
     + 重启电脑或重新加载udev规则：

       收起

       自动换行

       深色代码主题

       复制

       ```
       1. sudo udevadm control --reload
       ```

注意

开启非管理员角色的USB设备操作权限可以解决在Linux环境在非管理员权限下使用hdc因权限不足无法找到设备的情况。但权限最大化可能存在潜在安全问题，请开发者根据使用场景自行评估是否开启此权限。

### hdc无法运行

**现象描述**

使用命令行执行hdc命令无法运行。

**可能原因&解决方法**

1. 运行环境异常。

   Linux运行环境：建议使用Ubuntu18.04及以上64位版本。如出现libc++.so引用错误，请使用ldd或readelf命令检查库引用。

   MacOS运行环境：建议使用MacOS 11及以上版本。

   Windows运行环境：建议使用Windows10或Windows11 64位版本，如低版本缺失WinUSB库或驱动，请使用Zadig工具进行更新。对于需要安装驱动的设备，请使用Zadig工具安装libusb-win32驱动。详情请见：[Zadig链接](https://github.com/pbatard/libwdi/releases)。
2. 运行方式不当：请使用命令行依照正确命令运行hdc工具，而非鼠标双击文件。

### 使用hdc file send/recv传输中文文件出现乱码

**现象描述**

hdc文件传输命令执行出现乱码，如使用file recv从设备端发送带有中文名称的文件到本地，报错提示[Fail]Error opening file: no such file or directory, path:XXXXX，其中path显示中文乱码。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/ba/v3/rARVoZmVQ0uP2OnepTyLiw/zh-cn_image_0000002571291941.png?HW-CC-KV=V1&HW-CC-Date=20260414T050858Z&HW-CC-Expire=86400&HW-CC-Sign=416EDAD6491B75BCBA299838B6A9B3EB1D23DDA97223A2BBA6CC486154CA50FA)

**可能原因&解决方法**

3.1.0a版本开始，文件传输命令支持参数路径中包含中文，版本过低需要更新至最新版本。

执行hdc checkserver命令检查当前版本。如果低于3.1.0a版本，需将SDK升级到API12或更高版本。

### 执行hdc list targets显示"Unauthorized"

**现象描述**

使用hdc list targets命令查询已连接设备，连接设备标识后显示Unauthorized。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/27/v3/gyV1dmx_TsWbovsM5x3egQ/zh-cn_image_0000002540611994.png?HW-CC-KV=V1&HW-CC-Date=20260414T050858Z&HW-CC-Expire=86400&HW-CC-Sign=706B71D58F0A15851293BF5A60871E45D4F97FFA69C263223EE9D5055B2C6679)

**可能原因&解决方法**

1. 首次连接未授权：连接设备后解锁设备，屏幕显示“是否信任此设备？”窗口，点击“始终信任”或“信任”完成授权。
2. 授权窗口关闭或拒绝授权：设备端授权窗口会在超时后关闭，或开发者在授权窗口点击“不信任”拒绝授权。需要再次授权可在设备端 设置>系统>开发者选项>USB调试/无线调试 中，关闭已开启的调试开关后再开启，或执行hdc kill -r重启服务进程。屏幕会再次显示“是否信任此设备？”窗口，点击“始终信任”或“信任”完成授权。

### 执行任意hdc命令报错：CryptAcquireContext second failed

**现象描述**

执行hdc相关命令报错：CryptAcquireContext second failed XXX。

**可能原因&解决方法**

修改电脑环境注册表信息：

1. 同时按下Win+R键，启动运行工具，在输入栏中输入regedit以打开注册表；
2. 注册表地址栏输入以下内容并按下回车

   计算机\HKEY\_LOCAL\_MACHINE\SOFTWARE\Microsoft\Cryptography\Protect\Providers\df9d8cd0-1501-11d1-8c7a-00c04fc297eb；
3. 右键新建DWORD(32位)值(D)，新增值名称为ProtectionPolicy 值为 1（16进制），然后点击确定；
4. 重启电脑后问题解决。

### Windows设备管理器出现 未知USB设备（设备描述符请求失败）

**现象描述**

使用USB方式连接调试设备，电脑端设备管理器通用串行总线控制器出现未知USB设备（设备描述符请求失败）。

**可能原因&解决方法**

1. 进入Windows服务管理（services.msc），禁止后重启Plug and Play服务；
2. 卸载设备管理器中出现故障的USB设备，并拔出USB线；
3. 重启计算机。

尝试后，如果仍然无法识别，或者将设备连接到其他计算机上也无法识别，可能是USB设备的驱动出现故障，可以尝试更换USB连接线。

### hdc命令执行异常

**现象描述**

hdc命令执行后未输出预期内容，可能涉及以下场景。

1. 场景一：执行hdc命令提示：Connect server failed。
2. 场景二：执行hdc命令提示：connect failed status:-4078。
3. 场景三：执行hdc命令无任何输出。

**可能原因&解决方法**

端口异常问题的解决方法如下：

1. 排查自带hdc的软件进程。包括自带hdc的软件（如DevEco Studio、DevEco Testing），如果存在这些软件，请关闭后再执行hdc相关命令。
2. 查询hdc端口情况。以设置的OHOS\_HDC\_SERVER\_PORT为8710端口为例，在不同平台查询命令如下：

   Unix：

   收起

   自动换行

   深色代码主题

   复制

   ```
   1. netstat -an |grep 8710
   ```

   Windows：

   收起

   自动换行

   深色代码主题

   复制

   ```
   1. netstat -an |findstr 8710
   ```

   如存在抢占的软件，可以终止该软件进程，或者修改OHOS\_HDC\_SERVER\_PORT环境变量为其他端口号。
3. 排查未关闭的其他版本服务器进程。

   Windows：使用任务管理器>详细信息查询hdc.exe进程，右键打开文件所在位置，核对位置是否为配置的环境变量中的hdc文件位置，如果不一致，可尝试结束hdc.exe进程（命令行工具中执行hdc kill或者任务管理器直接结束进程）并重新执行hdc命令。（关闭服务器进程后执行hdc命令会重新启动服务器）。

   Unix：使用ps -ef | grep hdc查询hdc后台服务器进程，核对进程启动位置是否为配置的环境变量中的hdc文件位置，如果不一致，可尝试结束hdc进程（hdc kill或者kill -9 hdc进程的pid）并重新执行hdc命令。（关闭服务器进程后执行hdc命令会重新启动服务器）。

### 其他问题排查常用步骤

1. 命令行执行hdc list targets查看返回信息。
2. 检查设备管理是否有HDC Device。
3. 执行hdc kill关闭服务器进程后，执行hdc -l5 start收集日志（hdc.log位于执行端TEMP目录下，不同平台目录位置存在差异，可参考[服务器进程日志](/consumer/cn/doc/harmonyos-guides/hdc#服务器进程日志)）。
4. 通过hdc.log日志定位相关问题。

说明

更多常见问题处理可见[FAQ](https://developer.huawei.com/consumer/cn/doc/harmonyos-faqs/faqs-performance-analysis-kit)。

## hdc错误码

### E000001 hdc版本太低

**错误信息**

The sdk hdc.exe version is too low, please upgrade to the latest version.

**错误描述**

hdc版本太低，需更新至最新版本。

**可能原因**

客户端版本低于3.0.0b时，不支持授权，无法接入系统。

**处理步骤**

可参考[hdc版本配套表](/consumer/cn/doc/harmonyos-guides/hdc#hdc版本配套表)升级到最新版本。

### E000002 设备未授权

**错误信息**

The device unauthorized.

This server's public key is not set.

Please check for a confirmation dialog on your device.

Otherwise try 'hdc kill' if that seems wrong.

**错误描述**

设备未授权。请检查是否在设备授权弹窗“信任”授权，如果已经授权，请尝试执行"hdc kill"命令后重新执行调试命令。

**可能原因**

1. 场景一：首次连接设备未在设备端授权调试计算机。
2. 场景二：授权窗口弹出，如果开发者点击了“信任”而非“始终信任”，在断开设备后重新连接时需要再次授权。

**处理步骤**

1. 场景一：设备端弹出授权窗口，点击授权。具体操作为：连接设备后，系统会自动弹出授权弹窗。
2. 场景二：进入设备端 设置>系统>开发者选项，关闭调试开关后重新打开，重新连接设备进行授权；或者执行命令hdc kill -r后重新启动hdc，再次触发授权弹窗，点击“始终信任”。

### E000003 设备端用户未授权

**错误信息**

The device unauthorized.

The user denied the access for the device.

Please execute 'hdc kill' and redo your command,

then check for a confirmation dialog on your device.

**错误描述**

设备未授权。设备端拒绝授权调试，请执行"hdc kill"命令后重新执行调试命令，并且检查设备端授权窗口提醒。

**可能原因**

1. 设备端授权窗口超时自动关闭，未确认授权。
2. 开发者点击“不信任”，拒绝授权。

**处理步骤**

进入设备端 设置 > 系统 > 开发者选项，关闭调试开关后重新打开，重新连接设备进行授权；或执行命令hdc kill -r后重新启动hdc，再次触发授权弹窗，点击“始终信任”。

### E000004 通信连接不稳定

**错误信息**

The communication channel is being established.

Please wait for several seconds and try again.

**错误描述**

通信通道未建立，请等待几秒后重试。

**可能原因**

网络或USB连接未建立或连接不稳定。

**处理步骤**

连接设备后等待大约10秒，待连接建立后进行调试。

### E001000 tmode不支持设置USB调试

**错误信息**

For USB debugging, please set it on the device's Settings UI.

**错误描述**

执行hdc tmode命令不支持设置USB调试。

**可能原因**

hdc tmode usb命令已废弃，参见[USB调试和无线调试切换](/consumer/cn/doc/harmonyos-guides/hdc#usb调试和无线调试切换)。

**处理步骤**

参见[USB调试和无线调试切换](/consumer/cn/doc/harmonyos-guides/hdc#usb调试和无线调试切换)tmode usb命令说明。

### E001001 命令未知

**错误信息**

Unknown command.

**错误描述**

hdc tmode命令有误。

**可能原因**

hdc tmode命令缺少参数或参数有误。

**处理步骤**

参考[USB调试和无线调试切换](/consumer/cn/doc/harmonyos-guides/hdc#usb调试和无线调试切换)，完善执行命令。

### E001003 USB连接异常

**错误信息**

USB communication abnormal, please check the USB communication link.

**错误描述**

USB通信异常，请检查USB通信链路。

**可能原因**

1. USB连接线松动或断开。
2. 执行hdc shell reboot后，设备重启，连接正常断开，无需处理。
3. 执行hdc tmode port XXX，设备由USB调试方式转换为无线调试方式，连接正常断开，无需处理。

**处理步骤**

1. 确认设备与电脑的USB线连接牢固。正常连接仍有异常，可尝试更换USB线或其他USB端口。
2. 参考[hdc版本配套表](/consumer/cn/doc/harmonyos-guides/hdc#hdc版本配套表)章节，将版本升级到最新。

### E001104 tconn命令IP地址非法

**错误信息**

IP address incorrect.

**错误描述**

IP地址格式不正确。

**可能原因**

使用tconn命令无线调试连接时，输入IP地址不符合IPv4格式。

**处理步骤**

检查输入IP地址是否合法，正确IP格式参照127.0.0.1:8888保证无异常非法字符，修正后重新连接。

### E001005 设备未知或断连

**错误信息**

Device not found or connected.

**错误描述**

找不到连接设备或为非连接状态。

**可能原因**

设备断连。

**处理步骤**

参考[设备无法识别](/consumer/cn/doc/harmonyos-guides/hdc#设备无法识别)中描述的实际场景对应的解决方式进行操作。

### E001300 模拟器不支持tmode命令

**错误信息**

Not support tmode for Emulator.

**错误描述**

模拟器场景不支持hdc tmode命令。

**可能原因**

DevEco Studio中模拟器调试不支持hdc tmode命令。

**处理步骤**

如需调试tmode相关命令，请连接实体设备后进行调试。

### E002101 服务器进程无法结束

**错误信息**

Terminal hdc process failed, please terminal the hdc process in the task manager first.

**错误描述**

服务器进程无法结束。

**可能原因**

当删除.hdcserver.pid文件后执行hdc kill时，由于无法获取服务器的进程pid，导致无法结束进程。

**处理步骤**

在任务管理器中手动结束hdc进程。

### E002105 命令不支持

**错误信息**

Unsupport command.

**错误描述**

命令不支持。

**可能原因**

设备端版本过低，不支持执行调试命令。

**处理步骤**

尝试升级设备版本，或参考[hdc命令列表](/consumer/cn/doc/harmonyos-guides/hdc#hdc命令列表)检查命令是否准确。

### E002106 设备通信异常

**错误信息**

Failed to communicate with daemon.

**错误描述**

服务器与设备端守护程序通信异常。

**可能原因**

1. USB调试连接断开。
2. TCP无线调试方式网络不稳定。

**处理步骤**

1. 检查并确保设备已正常连接。
2. 检查网络状态，网络稳定后重新尝试连接。

### E003001 （命令行）指定的包名非法

**错误信息**

Invalid bundle name: bundlename.

**错误描述**

命令hdc shell [-b bundlename] [command]中指定的bundlename不是已安装的可调试应用包名且已在设备启动，或应用目录不存在。

**可能原因**

1. 场景一：设备上未安装指定的应用。
2. 场景二：指定包名的应用不是可调试应用。
3. 场景三：指定包名的应用未启动。

**处理步骤**

1. 场景一：确认命令指定包名的应用已安装到设备上。

   执行hdc shell "bm dump -a | grep bundlename"查询对应包名的应用是否已安装到设备上，预期返回信息为 bundlename；

   以应用名com.example.myapplication为例，查询命令如下：

   收起

   自动换行

   深色代码主题

   复制

   ```
   1. hdc shell "bm dump -a | grep com.example.myapplication"
   ```

   如应用已安装到设备上，预期返回信息：

   收起

   自动换行

   深色代码主题

   复制

   ```
   1. com.example.myapplication
   ```
2. 场景二：确认命令指定的应用是否为可调试应用。

   * 执行hdc shell "bm dump -n bundlename | grep appProvisionType"命令进行查询，预期返回信息为"appProvisionType": "debug"。

     以包名com.example.myapplication为例，可执行如下命令查询：

     收起

     自动换行

     深色代码主题

     复制

     ```
     1. hdc shell "bm dump -n com.example.myapplication | grep appProvisionType"
     ```

     如包名对应的应用是可调试应用，预期返回的信息如下：

     收起

     自动换行

     深色代码主题

     复制

     ```
     1. "appProvisionType": "debug",
     ```
   * 要构建可调试应用，需要使用调试证书进行签名。可参考：[申请调试证书](https://developer.huawei.com/consumer/cn/doc/app/agc-help-add-debugcert-0000001914263178)。
3. 场景三：确定命令指定的应用已启动。

   * 启动应用后，系统会挂载相应的资源目录。可执行hdc shell "mount |grep bundlename"查询应用启动后的资源目录挂载情况。

     以应用名com.example.myapplication为例，可执行如下命令查询是否已挂载资源目录：

     收起

     自动换行

     深色代码主题

     复制

     ```
     1. hdc shell "mount |grep com.example.myapplication"
     ```

     如果已挂载相应的资源目录，预期将返回挂载信息（返回内容以实际挂载情况为准，此处不作展示）。

     如果未挂载相应的资源目录，预期不会返回任何信息。
   * 如果未挂载相应的资源目录，可以通过手动点击应用或使用aa相关命令启动应用。

     以应用名com.example.myapplication模块名EntryAbility为例，启动命令为：

     收起

     自动换行

     深色代码主题

     复制

     ```
     1. hdc shell aa start -b com.example.myapplication -a EntryAbility
     ```

     更多详细用法请参考[aa命令介绍](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/aa-tool)。

### E003002 命令行指定的参数不支持交互模式

**错误信息**

Unsupport interactive shell command option.

**错误描述**

命令hdc shell [-b bundlename] [command]不支持“交互模式”命令行。

**可能原因**

命令hdc shell [-b bundlename] [command]指定的command参数不可为空。

**处理步骤**

确认command参数不为空值，详细使用方法请参考[执行交互命令](/consumer/cn/doc/harmonyos-guides/hdc#执行交互命令)。

### E003003 交互命令参数不支持

**错误信息**

Unsupport shell option: XXX.

**错误描述**

命令hdc shell [-b bundlename] [command]指定了不支持的命令行参数。如-f，-B等。

**可能原因**

参数未区分大小写，或使用了不支持的参数。

**处理步骤**

参考[执行交互命令](/consumer/cn/doc/harmonyos-guides/hdc#执行交互命令)使用当前版本支持的命令行参数，如-b参数。

### E003004 设备端不支持当前使用的参数

**错误信息**

Device does not support this shell option.

**错误描述**

当前设备不支持执行hdc shell [-b bundlename] [command]命令。

**可能原因**

设备系统版本较低，不支持新增的命令行参数。

**处理步骤**

升级设备操作系统版本到最新，具体版本可参考[hdc版本配套表](/consumer/cn/doc/harmonyos-guides/hdc#hdc版本配套表)中版本配套说明。

### E003005 命令行参数有误

**错误信息**

The parameter is missing, correct your input by referring below: Usage...

**错误描述**

hdc shell xxx，设备端命令不支持。

**可能原因**

设备系统版本较低，不支持对应新增的命令行参数功能。

**处理步骤**

升级设备操作系统版本到最新，具体版本可参考[hdc版本配套表](/consumer/cn/doc/harmonyos-guides/hdc#hdc版本配套表)中版本配套说明。

### E005003 （文件传输）缺少参数

**错误信息**

The parameter is missing, correct your input by referring below: Usage...

**错误描述**

1. 命令hdc file send [-b bundlename][SOURCE][DEST]缺少必要的参数。
2. 命令hdc file recv [-b bundlename][DEST][SOURCE]缺少必要的参数。

**可能原因**

命令指定-b参数时，缺少bundlename，SOURCE，DEST参数，命令详情参考[文件传输](/consumer/cn/doc/harmonyos-guides/hdc#文件传输)。

**处理步骤**

确认命令参数bundlename，SOURCE，DEST参数均不为空。

### E005004 SDK或设备系统不支持-b参数

**错误信息**

SDK/Device ROM doesn't support -b option.

**错误描述**

hdc file send/recv 命令带-b选项时，SDK中的hdc或设备系统版本不支持该选项。

**可能原因**

1. 场景一：执行命令hdc file send [-b bundlename] [SOURCE] [DEST]时，设备系统版本不支持-b选项。
2. 场景二：执行命令hdc file recv [-b bundlename] [DEST] [SOURCE]时，SDK中的hdc不支持-b选项。

**处理步骤**

1. 场景一：升级到最新系统版本，具体版本可参考[hdc版本配套表](/consumer/cn/doc/harmonyos-guides/hdc#hdc版本配套表)中版本配套说明。
2. 场景二：升级到最新SDK版本，具体版本可参考[hdc版本配套表](/consumer/cn/doc/harmonyos-guides/hdc#hdc版本配套表)中版本配套说明。

### E005005 创建目录失败

**错误信息**

Error create directory: xxx, path: xxx.

**错误描述**

创建目录失败。

**可能原因**

执行hdc file send命令发送文件，设备端对应目录为无权限目录或只读系统目录。

**处理步骤**

修改发送文件目标目录，确保目标目录有写权限。

### E005101 （文件传输）指定的包名非法

请参考错误码[E003001 （命令行）指定的包名非法](/consumer/cn/doc/harmonyos-guides/hdc#e003001-命令行指定的包名非法)。

### E005102 非法的远端路径

**错误信息**

Remote path: xxx is invalid, no such file/directory or it's out of the application directory.

**错误描述**

1. 命令hdc file send [-b bundlename][SOURCE][DEST]指定的DEST表示的路径不存在或已超出应用数据目录。
2. 命令hdc file recv [-b bundlename][SOURCE][DEST]指定的DEST表示的路径不存在或已超出应用数据目录。

**可能原因**

1. 场景一：远端路径不存在。
2. 场景二：参数DEST包含 .. 路径跳转符号，处理跳转后，实际目录超出了应用数据根目录。

**处理步骤**

检查参数DEST指定的应用数据目录相对路径是否真实存在。

### E006001 安装包路径非法

**错误信息**

Not any installation package was found.

**错误描述**

没有找到任何安装包。

**可能原因**

命令hdc install后缺少安装包参数。

**处理步骤**

参考[应用管理](/consumer/cn/doc/harmonyos-guides/hdc#应用管理)。

### E007100 不支持的命令

**错误信息**

Operate need running under debug mode.

**错误描述**

命令仅在调试模式下支持。

**可能原因**

不支持的命令。

**处理步骤**

无需进行处理。

### E005008 不支持的文件传输操作

**错误信息**

Operation not allowed.

**错误描述**

命令操作不被允许。

**可能原因**

涉及敏感文件（如系统配置，日志文件等）不允许操作。

**处理步骤**

无需进行处理。

### E001106 -e指定的IP不正确

**错误信息**

-e content IP incorrect.

**错误描述**

-e指定的IP不正确。

**可能原因**

不是合法的IP地址格式。

**处理步骤**

检查输入是否为合法的IP格式，并确认该IP地址属于本机。

### E00C001 hdc client/server调试拦截

**错误信息**

Operation restricted by the organization.

**错误描述**

操作被组织拦截。

**可能原因**

PC/2in1形态设备的hdc client/server调试功能被组织禁用。

**处理步骤**

请联系组织设备管理员查询PC/2in1设备hdc调试策略配置。