1# hdc 2 3<!--Kit: Performance Analysis Kit--> 4<!--Subsystem: HiviewDFX--> 5<!--Owner: @kunsilva--> 6<!--Designer: @weimingjin--> 7<!--Tester: @gcw_KuLfPSbe--> 8<!--Adviser: @foryourself--> 9 10hdc（HarmonyOS Device Connector）是提供给开发人员的命令行调试工具，用于与设备进行交互调试、数据传输、日志查看以及应用安装等操作。该工具支持在Windows/Linux/MacOS系统上运行，为开发者提供高效，便捷的设备调试能力。 11 12hdc包含三部分： 13 14**客户端（client）**：运行在电脑端的进程，开发者在执行hdc命令时启动该进程，命令结束后进程自动退出。 15 16**服务器（server）**：运行在电脑端的后台服务进程，用来管理客户端进程和设备端守护进程之间的数据交互，设备发现等。 17 18**守护程序（daemon）**：运行在调试设备端的进程，用来响应服务器发来的请求。 19 20如图所示： 21 22 23 24> **说明：** 25> 26> 客户端进程在启动时，默认会判断服务器进程是否正在运行。如果没有运行则会启动一个新的hdc进程作为服务器进程，运行在后台。 27> 28> 服务器运行时，默认会监听电脑端的8710端口。开发者可通过设置系统环境变量OHOS_HDC_SERVER_PORT自定义监听的端口号，范围为1~65535。 29 30## 环境准备 31 32hdc可以选择以下任意一种方式获取： 33 341.通过SDK获取hdc工具。SDK已嵌入[DevEco Studio](https://developer.huawei.com/consumer/cn/deveco-studio/)中，无需额外下载配置。hdc默认安装在DevEco Studio/sdk/default/openharmony/toolchains路径下，MacOS系统的sdk位于DevEco Studio/Contents目录下。 35 362.通过[Command Line Tools](https://developer.huawei.com/consumer/cn/download/)工具中的sdk目录获取相关工具。hdc程序默认安装在Command Line Tools/sdk/default/openharmony/toolchains路径下。 37 38hdc支持USB和无线两种连接调试方式。在设备的设置>系统>开发者选项中开启或关闭调试开关 ，无需重启设备即可生效。如果设备未启用“开发者选项”，可参考[开发者选项](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-developer-mode#section530763213432)进行启用。具体调试连接方式及操作步骤请参考[USB连接场景](#usb连接场景)和[TCP连接场景](#tcp连接场景)。 39 40### （可选）命令行直接执行hdc程序 41 42**安装目录下的调试** 43 44- 开发者可以在SDK的toolchains子目录下执行hdc命令进行设备调试。 45 46- hdc支持独立运行。将toolchains子目录下的hdc可执行文件和libusb_shared依赖文件集中存放至自定义目录中，在自定义目录下直接执行hdc命令，实现独立调试。 47 48**添加hdc到系统环境变量** 49 50- Windows环境变量设置方法： 51 1. 按下Windows键，搜索栏输入“设置”，点击进入设置窗口； 52 2. 在搜索栏中搜索“查看高级系统设置”。在环境变量>系统变量>Path>编辑中，将hdc.exe所在目录添加到 Path。环境变量配置完成后，请重启电脑，即可在命令行窗口执行hdc命令。 53 54- Linux/MacOS系统： 55 1. 打开终端工具，执行以下命令，根据输出结果分别执行不同的命令。 56 57 ```shell 58 echo $SHELL 59 ``` 60 61 1. 如果输出结果为bin/bash，执行以下命令打开.bashrc文件。 62 63 ```shell 64 vi ~/.bashrc 65 ``` 66 67 2. 如果输出结果为/bin/zsh，执行以下命令打开.zshrc文件。 68 69 ```shell 70 vi ~/.zshrc 71 ``` 72 73 2. 切换至英文输入法，按下键盘字母“i”，进入Insert模式。 74 3. 在文件末尾添加PATH信息。 75 76 ```shell 77 PATH={DevEco Studio}/sdk/default/openharmony/toolchains:$PATH 78 ``` 79 80 其中{DevEco Studio}需替换为DevEco Studio实际安装目录的绝对路径，例如/home/DevEco-Studio。 81 4. 编辑完成后，单击Esc键退出编辑模式，输入“:wq”并且单击Enter键保存。 82 5. 请执行以下命令，使配置的环境变量生效。 83 1. 如果步骤1打开的是.bashrc文件，请执行如下命令： 84 85 ```shell 86 source ~/.bashrc 87 ``` 88 89 2. 如果步骤1打开的是.zshrc文件，请执行如下命令： 90 91 ```shell 92 source ~/.zshrc 93 ``` 94 95 6. 环境变量配置完成后，重启系统。 96 97### （可选）服务器配置 98 99配置系统环境变量可修改服务器进程的监听端口、日志打印级别或特性开关等。详细介绍请查看[可选配置项](#可选配置项)章节。 100 101> **说明：** 102> 103> 环境变量配置完成后，重启命令行窗口或其他使用到HarmonyOS SDK的软件，以生效新配置的环境变量。 104 105## hdc命令列表 106 107### 全局参数 108 109全局参数是指运行hdc命令时，可以添加在hdc和具体执行命令之间的参数。例如，使用-t参数可以选择指定的设备执行命令： 110 111```shell 112hdc -t connect-key shell echo "Hello world" 113``` 114 115| 参数 | 说明 | 116| -------- | -------- | 117| [-t](#连接指定的目标设备) | 通过设备标识符连接指定的目标设备。单台设备连接时为可选参数，连接多台设备时为必选参数。 | 118| [-l](#服务器进程日志) | 可选参数，指定运行时日志等级，范围为数字0-6，默认为3（LOG_INFO）。 | 119| [-s](#远程连接场景) | 可选参数，指定客户端连接服务器时，服务进程的网络监听参数，格式为IP:port。 | 120| [-p](#快速执行命令) | 可选参数，绕过对服务进程的查询步骤，用于快速执行客户端命令。 | 121| [-m](#前台启动服务) | 可选参数，使用前台启动模式启动服务进程。 | 122| [-e](#创建正向端口转发任务) | 可选参数，指定在TCP端口转发时，本地监听的IP地址，默认是127.0.0.1。该参数必须和-m一起使用。<br/>**说明**：从API version 20开始，支持该接口。| 123 124### 命令列表 125 126| 命令 | 说明 | 127| -------- | -------- | 128| [list targets](#查询设备列表) | 查询已连接的所有目标设备。 | 129| [wait](#等待设备正常连接) | 等待设备正常连接。 | 130| [tmode usb](#usb调试和无线调试切换) | 3.1.0e版本起已废弃，不会操作设备连接通道，需在设备设置界面通过USB调试开关设置。 | 131| [tmode port](#打开设备网络连接通道) | 打开设备网络连接通道。 | 132| [tmode port close](#关闭网络连接通道) | 关闭设备网络连接通道。 | 133| [tconn](#tcp连接设备) | 指定连接设备：通过“IP:port”来指定连接的设备。 | 134| [shell](#执行交互命令) | 在设备侧执行单次命令，例如hdc shell ls。无命令参数可进入设备侧终端执行命令。 | 135| [install](#安装应用文件) | 安装指定的应用文件。 | 136| [uninstall](#卸载应用) | 卸载指定的应用包。 | 137| [file send](#本地发送文件至远端设备) | 从本地发送文件至远端设备。 | 138| [file recv](#接收远端设备文件至本地) | 接收远端设备文件至本地。 | 139| [fport ls](#查询端口转发任务列表) | 列出全部转发端口任务。 | 140| [fport](#创建正向端口转发任务) | 设置正向端口转发任务：监听“主机端口”，接收请求并转发到“设备端口”。 | 141| [rport](#创建反向端口转发任务) | 设置反向端口转发任务：监听“设备端口”，接收请求并转发到“主机端口”。 | 142| [fport rm](#删除端口转发任务) | 删除指定的端口转发任务。 | 143| [start](#启动服务) | 启动hdc服务进程。 | 144| [kill](#终止服务) | 终止hdc服务进程。 | 145| [hilog](#打印设备端日志) | 打印设备端的日志信息。 | 146| [jpid](#显示设备已打开应用的进程pid) | 显示设备上已打开应用的进程pid。 | 147| track-jpid [-a\|-p] | 实时显示设备上已打开应用的进程pid和应用包名，其中只有debug标签的应用可以被调试。不加参数时只显示已打开应用的进程pid，使用-a参数会显示debug和release应用的进程标签，使用-p参数不显示debug和release的进程标签。 | 148| [target boot](#重启目标设备) | 重启目标设备。 | 149| <!--DelRow--> [target mount](#以读写模式挂载系统分区) | 以读写模式挂载系统分区（非root的设备不可用）。 | 150| <!--DelRow--> [smode](#授予设备端hdc后台服务进程root权限) | 授予设备端hdc后台服务进程root权限，使用-r参数取消授权（非root的设备不可用）。 | 151| [keygen](#安全相关命令) | 生成一个新的密钥对。 | 152| [version](#查询hdc版本号) | 打印hdc版本信息，也可使用hdc -v打印版本信息。 | 153| [checkserver](#查询客户端和服务器进程版本) | 获取客户进程与服务进程版本信息。 | 154 155## 基本使用方法 156 157以USB调试方式为例，执行命令前请在设备上开启USB调试功能，用USB线连接设备和电脑。 158 159### 查询连接的设备 160 161```shell 162hdc list targets 163``` 164 165### 执行shell命令 166 167```shell 168hdc shell echo "Hello world" 169``` 170 171### 获取帮助 172 173显示hdc相关帮助信息，命令格式如下： 174 175```shell 176hdc -h [verbose] 177hdc help 178``` 179 180| 参数名 | 说明 | 181| -------- | -------- | 182| -h verbose | 显示hdc命令帮助信息。可选参数：verbose，显示详细的帮助信息。 | 183| help | 显示hdc命令帮助信息。 | 184 185**返回信息**： 186 187| 返回信息 | 说明 | 188| -------- | -------- | 189| OpenHarmony device connector(HDC) ...<br/>---------------------------------global commands:----------------------------------<br/>-h/help [verbose] - Print hdc help, 'verbose' for more other cmds<br/>...（此处省略详细帮助信息） | hdc命令使用帮助信息。 | 190 191> **注意：** 192> 193> 使用hdc时如出现异常，可尝试通过hdc kill -r命令终止异常进程并重启hdc服务。 194> 195> 如出现hdc list targets无法获取设备信息的情况，请参见[设备无法识别](#设备无法识别)章节。 196 197## 设备连接管理 198 199### 查询设备列表 200 201```shell 202hdc list targets [-v] 203``` 204 205**参数**： 206 207| 参数名 | 说明 | 208| -------- | -------- | 209| -v | 显示设备更多详情。 | 210 211**返回信息**： 212 213| 返回信息 | 说明 | 214| -------- | -------- | 215| 设备标识符列表 | 已连接的设备标识符列表。<br/>命令添加-v参数显示更多详情：设备标识符、连接方式（TCP/USB）、连接状态（Unknown/Ready/Connected/Offline/Unauthorized）、设备名称和hdc标识。 | 216| 设备标识符 Unauthorized | 设备处于未授权状态。 | 217| [Empty] | 没有查询到设备信息。 | 218 219**使用方法**： 220 221```shell 222$ hdc list targets 223connect-key1 224... 225 226$ hdc list targets -v 227connect-key1 USB Connected localhost hdc 228127.0.0.1:5555 TCP Offline localhost hdc 229connect-key2 USB Offline localhost hdc 230... 231``` 232 233### 连接指定的目标设备 234 235```shell 236hdc -t [connect-key] [command] 237``` 238 239**参数**： 240 241| 参数名 | 说明 | 242| -------- | -------- | 243| -t | 通过设备标识符连接指定目标设备。<br/>连接单台设备时为可选参数，连接多台设备时为必填参数。 | 244| command | hdc支持的命令。 | 245 246> **说明：** 247> 248> connect-key为每个设备唯一的标识符。通过USB连接，标识符为设备序列号；通过网络无线连接设备，标识符格式为IP:port。 249 250**返回信息**： 251 252| 返回信息 | 说明 | 253| -------- | -------- | 254| 正常执行返回信息，参考[命令列表](#命令列表)具体说明。 | - | 255| [Fail]Not match target founded, check connect-key please. | 使用-t参数匹配不存在的connect-key，请检查connect-key是否正确。 | 256| [Fail]Device not founded or connected. | 设备未找到或未连接。 | 257| [Fail]ExecuteCommand need connect-key? please confirm a device by help info. | 请确保已连接设备并打开调试开关。 | 258| Unknown operation command... | 不支持的命令。 | 259 260> **说明：** 261> 262> 命令返回的错误信息仅供开发者参考，后续可能会优化调整。请勿将此类信息用于自动化脚本或程序的逻辑判断，实际程序交互建议使用系统异常提供的标准错误码，具体详情可参考[hdc错误码](#hdc错误码)。 263 264**使用方法**： 265 266此调试方法需要与具体的操作命令搭配使用，下面以shell命令为例： 267 268```shell 269$ hdc list targets 270connect-key1 271... 272 273$ hdc -t connect-key1 shell echo "hello world!" 274hello world! 275``` 276 277### 等待设备正常连接 278 279```shell 280hdc wait # 等待设备正常连接 281hdc -t [connect-key] wait # 等待指定的设备正常连接，connect-key需要替换为指定的设备标识符 282``` 283 284**参数**： 285 286| 参数名 | 说明 | 287| -------- | -------- | 288| -t connect-key | 3.1.0a版本新增参数：<br/>连接单台设备时，为可选参数。<br/>连接多台设备时，为必填参数。 | 289 290**返回信息**： 291 292| 返回信息 | 说明 | 293| -------- | -------- | 294| 无 | hdc wait命令执行后，识别到正常连接的设备后结束。 | 295 296**使用方法**： 297 298```shell 299# 如果设备正常连接，则命令执行结束无任何打印信息 300$ hdc wait # 单台设备 301$ hdc -t connect-key1 wait # 多设备需使用-t指定连接设备 302``` 303 304### USB连接场景 305 306**环境确认** 307 308| 确认项 | 正常 | 异常处理 | 309| -------- | -------- | -------- | 310| USB调试选项 | 开启。 | 如果设备的USB调试模式未能自动开启，请尝试重启设备。 | 311| USB数据连接线 | 使用USB数据连接线连接到调试电脑的USB接口。 | 如果使用低带宽、无数据通信功能的USB连接线可能导致无法识别hdc设备，建议更换为设备原装充电线。 | 312| USB接口 | 主板直出USB接口（台式机为后面板的USB接口，笔记本为机身的USB接口）。 | 如果使用转接头/拓展坞/台式机前面板USB接口，可能存在带宽低和USB同步异常等问题，会导致频繁断连，推荐使用直连方式连接电脑和设备。 | 313| hdc环境变量 | 终端命令行输入hdc -h有回显帮助信息内容。 | 参见[环境准备](#环境准备)章节。 | 314| 驱动 | 连接hdc设备后，设备管理器通用串行总线设备存在设备“HDC Device”或“HDC Interface”。 | 参见[设备无法识别](#设备无法识别)章节。 | 315 316**连接步骤** 317 3181. 通过USB连接设备。 319 3202. 执行以下命令查看已连接设备： 321 322 ```shell 323 hdc list targets 324 ``` 325 326 返回信息中包含设备标识符，表示USB连接成功。 327 3283. 查询到设备后，运行相关命令与设备交互。如果希望不带设备标识符执行hdc命令，需要确认设备不在TCP连接模式（hdc list targets查询的设备不包含IP:port形式的连接信息），直接连接即可，例如： 329 330 ```shell 331 hdc shell 332 ``` 333 334### TCP连接场景 335 336> **注意：** 337> 338> TCP调试功能尚未稳定，建议仅在测试环境中使用。 339 340**环境确认** 341 342| 确认项 | 正常 | 异常处理 | 343| -------- | -------- | -------- | 344| 网络连接 | 电脑、设备处于同一网络。 | 连接同一WiFi。 | 345| 网络状态 | telnet IP:port正常，网速稳定。 | 请选择稳定网络。 | 346| hdc环境变量 | 终端命令行输入hdc -h有回显帮助信息内容。 | 参见[环境准备](#环境准备)章节。 | 347 348**连接步骤** 349 3501. 在设备端设置>系统>开发者选项>无线调试>打开无线调试。 351 3522. 记录设备界面显示的IP地址和端口，格式为IP:port。 353 3543. 通过tcp连接设备，执行以下命令： 355 356 ```shell 357 hdc tconn IP:port 358 ``` 359 360 命令执行返回“Connect OK”表示连接成功。 361 3624. 查看已连接设备，执行以下命令： 363 364 ```shell 365 hdc list targets 366 ``` 367 368 返回信息为IP:port格式。 369 370 > **说明：** 371 > 372 > 如果需要关闭TCP连接模式，可在设备中关闭无线调试开关或断开网络连接。 373 374### 远程连接场景 375 376远程连接场景指客户端（通常是开发者使用的本地电脑）通过网络与服务器（通常是连接了调试设备的服务器或开发机）建立连接，实现客户端对目标设备的远程调试，控制和管理。 377 378 379 380远程连接使用-s参数来指定服务器的网络参数，包括地址和端口号，该设置只在当前命令执行期间有效，命令格式如下： 381 382```shell 383hdc -s [IP:]port [command] 384``` 385 386| 命令 | 说明 | 387| -------- | -------- | 388| -s | 指定当前服务进程的网络监听参数。 | 389 390**参数**： 391 392| 参数 | 说明 | 393| -------- | -------- | 394| IP | 可选参数，指定监听的IP地址，支持IPv4和IPv6。不指定IP默认监听本机127.0.0.1。 | 395| port | 指定监听的端口，范围为1~65535。 | 396| command | hdc支持的命令，参见[hdc命令列表](#hdc命令列表)。 | 397 398**返回信息**： 399 400| 返回信息 | 说明 | 401| -------- | -------- | 402| Connect server failed. | 与服务进程建立连接失败。 | 403| -s content port incorrect. | 端口号超出可设置范围（1~65535）。 | 404 405**使用方法** 406 407```shell 408# 在已有服务进程，且服务进程的网络监听参数为127.0.0.1:8710的环境中，执行查询设备命令 409$ hdc -s 127.0.0.1:8710 list targets 410``` 411 412**连接步骤** 413 4141. 服务器配置 415 服务器通过USB连接对应hdc设备后，执行以下命令： 416 417 ```shell 418 $ hdc kill # 关闭本地hdc服务 419 $ hdc -s IP:8710 -m # 启动网络转发的hdc服务 420 # 其中IP为服务器自身的IP，windows可通过ipconfig查询，unix系统可通过ifconfig查询 421 # 8710是默认端口号，也可设置其他端口号如：18710 422 # 启动后服务器将打印日志 423 ``` 424 4252. 客户端连接 426 客户端可以连通服务器IP地址，满足条件后执行以下命令： 427 428 ```shell 429 $ hdc -s IP:8710 [command] # 其中IP为服务器IP，8710为第一步服务器进程启动时设置的端口号， 430 # 如果端口号有变化，这里也需要变更。 431 # command可以为任意hdc可用命令，例如list targets 432 ``` 433 434> **说明：** 435> 436> 当命令行中明确使用 -s 参数指定服务器进程端口时，系统将忽略OHOS_HDC_SERVER_PORT环境变量中定义的端口设置。使用 -s 参数指定服务器地址时，如果监听地址不是本地回环地址（如127.0.0.1），需注意访问安全问题。 437 438### USB调试和无线调试切换 439 440用于连接模式切换的命令如下表所示： 441 442| 命令 | 说明 | 443| -------- | -------- | 444| tmode usb | 该命令已废弃，不会操作设备连接通道，请在设备设置界面通过USB调试开关进行设置。 | 445| tmode port [port-number] | 打开设备网络连接通道：设备端守护程序会重启，已建立的连接需要重新连接。 | 446| tmode port close | 关闭设备网络连接通道：设备端守护程序会重启，已建立的连接需要重新连接。 | 447| tconn IP:port [-remove] | 连接指定设备，使用“IP:port”指定，使用-remove参数断开。 | 448 449> **说明：** 450> 451> 推荐通过设备端的USB调试开关和无线调试开关来控制连接通道。 452 453### 打开设备网络连接通道 454 455命令格式如下： 456 457```shell 458hdc tmode port [port-number] 459``` 460 461**参数**： 462 463| 参数 | 参数说明 | 464| -------- | -------- | 465| port-number | 监听连接的网络端口号，范围：1~65535。 | 466 467**返回信息**： 468 469| 返回信息 | 说明 | 470| -------- | -------- | 471| Set device run mode successful. | 设置成功。 | 472| [Fail]ExecuteCommand need connect-key. | 打开失败，设备列表为空，无法建立设备的无线调试通道。 | 473| [Fail]Incorrect port range. | 端口号超出可设置范围1~65535。 | 474 475**使用方法**： 476 477```shell 478$ hdc tmode port 65512 479Set device run mode successful. 480``` 481 482> **注意：** 483> 484> 切换前，请确保条件满足：远端设备与近端电脑处于同一网络，可通过ping命令检查： 485> 486> 1. 近端电脑在命令行中执行命令ping 远端设备的IP地址； 487> 488> 2. 如果能接收到远端设备的回应数据包，表明二者处于同一网络。 489> 490> 如不满足以上条件，切勿使用该命令进行切换。 491> 492> 执行完毕后，远端守护程序将退出并重启，需要重新连接。 493 494### 关闭网络连接通道 495 496命令格式如下： 497 498```shell 499hdc tmode port close 500``` 501 502**返回信息**： 503 504| 返回信息 | 说明 | 505| -------- | -------- | 506| [Fail]ExecuteCommand need connect-key. | 设备列表为空，无法执行命令。 | 507 508**使用方法**： 509 510```shell 511hdc tmode port close 512``` 513 514> **说明：** 515> 516> 执行完毕后，远端设备上的守护程序将退出并重启，需要重新连接。 517 518### TCP连接设备 519 520通过TCP连接指定设备，命令格式如下： 521 522```shell 523hdc tconn IP:port [-remove] 524``` 525 526**参数**： 527 528| 参数 | 参数说明 | 529| -------- | -------- | 530| IP:port | 设备的IP地址和端口号。 | 531| -remove | 可选参数，断开指定设备的连接。 | 532 533**返回信息**： 534 535| 返回信息 | 说明 | 536| -------- | -------- | 537| Connect OK. | 连接成功。 | 538| [Info]Target is connected, repeat opration. | 设备当前已连接。 | 539| [Fail]Connect failed. | 连接失败。 | 540 541**使用方法**： 542 543```shell 544$ hdc tconn 192.168.0.1:8888 545Connect OK 546 547# 断开指定网络设备连接 548$ hdc tconn 192.168.0.1:8888 -remove 549``` 550 551## 执行交互命令 552 553```shell 554hdc shell [-b bundlename] [command] 555``` 556 557**参数**： 558 559| 参数 | 说明 | 560| -------- | -------- | 561| -b bundlename | 3.1.0e版本新增参数。指定可调试应用包名，在可调试应用数据目录内，以非交互式模式执行命令。<br/>[命令行方式访问应用沙箱](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-device-file-explorer#section48216711204)。<br/>此参数当前仅支持以非交互式模式执行命令，不支持缺省command参数执行命令进入交互式shell会话。<br/>未配置此参数时，默认执行路径为系统根目录。 | 562| command | 需要在设备上执行的单次命令，不同类型或版本的系统支持的command命令有所差异，可以通过hdc shell ls /system/bin查阅支持的命令列表。当前大多数命令都是由[toybox](../tools/toybox.md)提供，可通过 hdc shell toybox --help 获取命令帮助。<br/>缺省该参数，hdc将会启动一个交互式的shell会话，开发者可以在命令提示符下输入命令，比如 ls、cd、pwd 等。 | 563 564> **说明：** 565> 566> 使用参数[-b bundlename]指定包名，该包名对应的已安装应用必须满足以下条件：使用调试证书签名，并且已在设备上启动。有关如何申请调试证书及签名可参考：[申请调试证书](https://developer.huawei.com/consumer/cn/doc/app/agc-help-add-debugcert-0000001914263178)。 567 568**返回信息**： 569 570| 返回信息 | 说明 | 571| -------- | -------- | 572| 交互命令返回内容。 | 返回内容详情请参见其他交互命令返回内容。 | 573| /bin/sh: XXX : inaccessible or not found. | 不支持的交互命令。 | 574| [Fail]具体失败信息。 | 执行失败，参见[hdc错误码](#hdc错误码)。 | 575 576**使用方法**： 577 578```shell 579# 进入交互式模式执行命令 580$ hdc shell 581$ 582 583# 以非交互式模式执行命令 584$ hdc shell "ps -ef | grep hdcd" 585shell 39491 1 1 14:40:58 ? 00:00:00 hdcd 586 587# 查询全部可用命令 588$ hdc shell help -a 589---toybox--------------------------------------------------------------------- 590 591usage: toybox [--long | --help | --version | [command] [arguments...]] 592 593With no arguments, shows available commands. First argument is 594name of a command to run, followed by any arguments to that command. 595 596--long Show path to each command 597... 598 599# 在指定包名的应用数据目录内以非交互式模式执行命令，支持touch、rm、ls、stat、cat、mkdir等命令。 600$ hdc shell -b com.example.myapplication ls data/storage/el2/base/ 601``` 602 603**常用调试工具** 604 605| 命令 | 说明 | 606| -------- | -------- | 607| [aa](../tools/aa-tool.md) | 应用调试工具 | 608| [bm](../tools/bm-tool.md) | 包管理工具 | 609| [cem](../tools/cem-tool.md) | 公共事件管理工具 | 610| [anm](../tools/anm-tool.md) | 通知管理工具 | 611| [edm](../tools/edm-tool.md) | 企业设备管理工具 | 612| [param](../tools/param-tool.md) | 操作系统参数管理工具 | 613| [power-shell](../tools/power-shell.md) | 设备电源状态转换工具 | 614| [atm](../tools/atm-tool.md) | 程序访问控制管理工具 | 615| [hilog](./hilog.md) | 日志管理工具 | 616| [hidumper](./hidumper.md) | 系统信息导出工具 | 617| [hitrace](./hitrace.md) | 系统打点及采集工具 | 618| [hiperf](./hiperf.md) | 性能分析工具 | 619| [mediatool](../tools/mediatool.md) | 媒体资源库工具 | 620| [devicedebug](../tools/devicedebug-tool.md) | 调试应用发送信号工具 | 621| [rawheap-translator](../tools/rawheap-translator.md) | rawheap文件解析工具 | 622 623## 应用管理 624 625| 命令 | 说明 | 626| -------- | -------- | 627| install src | 安装指定的应用文件。 | 628| uninstall bundlename | 卸载指定的应用package包名。 | 629 630### 安装应用文件 631 632安装应用文件，命令格式如下： 633 634```shell 635hdc install [-r|-s] src 636``` 637 638**参数**： 639 640| 参数名 | 说明 | 641| -------- | -------- | 642| src | 应用安装包的文件名。 | 643| -r | 替换已存在的应用（.hap）。 | 644| -s | 安装一个共享包（.hsp）。 | 645 646**返回信息**： 647 648| 返回信息 | 说明 | 649| -------- | -------- | 650| [Info]App install path:XXX msg:install bundle successfully.<br/>AppMod finish. | 成功情况下返回安装信息及AppMod finish完成的通知。 | 651| 具体安装失败原因。 | 失败情况下返回安装失败信息。 | 652 653**使用方法**： 654 655```shell 656# 以安装example.hap包为例： 657$ hdc install E:\example.hap 658AppMod finish 659``` 660 661### 卸载应用 662 663命令格式如下： 664 665```shell 666hdc uninstall [-k|-s] bundlename 667``` 668 669**参数**： 670 671| 参数名 | 说明 | 672| -------- | -------- | 673| bundlename | 应用安装包。 | 674| -k | 卸载应用后，系统会保留/data和/cache目录。 | 675| -s | 卸载共享包。 | 676 677**返回信息**： 678 679| 返回信息 | 说明 | 680| -------- | -------- | 681| [Info]App uninstall path: msg:uninstall bundle successfully.<br/>AppMod finish. | 成功情况下返回卸载信息和AppMod finish完成的通知。 | 682| 具体卸载失败原因。 | 失败情况下返回卸载失败信息。 | 683 684**使用方法**： 685 686```shell 687# 以卸载com.example.hello包为例： 688$ hdc uninstall com.example.hello 689AppMod finish 690``` 691 692## 文件传输 693 694| 命令 | 说明 | 695| -------- | -------- | 696| file send SOURCE DEST | 从本地发送文件至远端设备。 | 697| file recv DEST SOURCE | 从远端设备接收文件至本地。 | 698 699### 本地发送文件至远端设备 700 701命令格式如下： 702 703```shell 704hdc file send [-a|-sync|-z|-m|-b bundlename] SOURCE DEST 705``` 706 707**参数**： 708 709| 参数名 | 说明 | 710| -------- | -------- | 711| SOURCE | 本地待传输的文件路径。 | 712| DEST | 远程目标文件路径。 | 713| -a | 保留文件修改时间戳。 | 714| -sync | 只传输文件mtime有更新的文件。<br/>mtime（modified timestamp）：修改后的时间戳。 | 715| -z | 通过LZ4格式压缩传输，此功能未开放，请勿使用。 | 716| -m | 文件传输时同步文件DAC权限，uid，gid，MAC权限。<br/>DAC（Discretionary Access Control）：自主访问控制，<br/>uid（User identifier）：用户标识符（或用户ID），<br/>gid（Group identifier）：组标识符（或组ID），<br/>MAC（Mandatory Access Control）：强制访问控制（或非自主访问控制）。 | 717| -b | 3.1.0e版本新增参数（低版本使用会提示[Fail]Unknown file option: -b），用于指定可调试应用包名。<br/>使用方法可参考[通过命令往应用沙箱目录中发送文件](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-device-file-explorer#section48216711204)。 | 718| bundlename | 指定可调试应用包名。 | 719 720**返回信息**： 721 722文件发送成功时，返回传输成功的确认信息。文件发送失败时，返回传输失败的具体错误信息。 723 724**使用方法**： 725 726```shell 727$ hdc file send test /test/ 728FileTransfer finish, Size:10, File count = 1, time:0ms rate:100kB/s 729``` 730 731### 接收远端设备文件至本地 732 733命令格式如下： 734 735```shell 736hdc file recv [-a|-sync|-z|-m|-b bundlename] DEST SOURCE 737``` 738 739**参数**： 740 741| 参数名 | 说明 | 742| -------- | -------- | 743| SOURCE | 本地待接收的文件路径。 | 744| DEST | 远程待传输的文件路径。 | 745| -a | 保留文件修改时间戳。 | 746| -sync | 只传输文件mtime有更新的文件。<br/>mtime（modified timestamp）：修改后的时间戳。 | 747| -z | 通过LZ4格式压缩传输，此功能未开放，请勿使用。 | 748| -m | 文件传输时同步文件DAC权限，uid，gid，MAC权限。<br/>DAC（Discretionary Access Control）：自主访问控制，<br/>uid（User identifier）：用户标识符（或用户ID），<br/>gid（Group identifier）：组标识符（或组ID），<br/>MAC（Mandatory Access Control）：强制访问控制（或非自主访问控制）。 | 749| -b | 3.1.0e版本新增参数，用于传输指定的可调试应用进程应用数据目录下的文件。<br/>使用方法可参考[从沙箱目录中下载文件到本地计算机](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-device-file-explorer#section48216711204)。 | 750| bundlename | 可调试应用进程的包名。 | 751 752**返回信息**： 753 754文件接收成功时，返回传输成功的确认信息。文件接收失败时，返回传输失败的具体错误信息。 755 756**使用方法**： 757 758```shell 759$ hdc file recv /test/test ./ 760FileTransfer finish, Size:10, File count = 1, time:0ms rate:100kB/s 761``` 762 763> **说明：** 764> 765> 使用参数[-b bundlename]指定包名，应满足条件：指定包名的已安装应用为“使用调试证书签名的应用”且在设备上已启动， 如何申请调试证书及签名可参考：[申请调试证书](https://developer.huawei.com/consumer/cn/doc/app/agc-help-add-debugcert-0000001914263178)。 766> 767> **版本更新说明**：从3.1.0a版本开始，支持使用中文字符作为文件传输命令参数，便于多语言环境下使用。 768 769## 端口转发 770 771| 命令 | 说明 | 772| -------- | -------- | 773| fport ls | 列出全部转发端口转发任务。 | 774| fport [IP:port] [IP:port] | 设置正向端口转发任务：监听“主机端口”，接收请求并进行转发， 转发到“设备端口”。设备端口范围1~65535。 | 775| rport [IP:port] [IP:port] | 设置反向端口转发任务：监听“设备端口”，接收请求并进行转发，转发到“主机端口”。设备端口范围1024~65535。 | 776| fport rm [IP:port] [IP:port] | 删除指定的端口转发任务。 | 777 778> **说明：** 779> 780> 电脑端支持的端口转发类型：tcp。 781> 782> 设备端支持的端口转发类型：tcp，dev，localabstract，localfilesystem，jdwp，ark。 783 784### 查询端口转发任务列表 785 786命令格式如下： 787 788```shell 789hdc fport ls 790``` 791 792**返回信息**： 793 794| 返回信息 | 说明 | 795| -------- | -------- | 796| tcp:1234 tcp:1080 [Forward] | 正向端口转发任务。 | 797| tcp:2080 tcp:2345 [Reverse] | 反向端口转发任务。 | 798| [Empty] | 无端口转发任务。 | 799 800**使用方法**： 801 802```shell 803$ hdc fport ls 804[Empty] 805``` 806 807### 创建正向端口转发任务 808 809设置正向端口转发任务，系统将指定的“主机端口”转发到“设备端口”，命令格式如下： 810 811```shell 812hdc fport [IP:port] [IP:port] 813``` 814 815**返回信息**： 816 817| 返回信息 | 说明 | 818| -------- | -------- | 819| Forwardport result:OK. | 端口转发任务设置正常。 | 820| [Fail]Incorrect forward command. | 端口转发任务设置失败，端口转发参数错误。 | 821| [Fail]TCP Port listen failed at XXXX. | 端口转发任务设置失败，本地转发端口被占用。 | 822| [Fail]Forward parament failed. | 端口转发任务格式有误，或转发端口协议或端口范围有误。 | 823| [Fail]Not support forward-type. | 当前平台不支持参数中使用的转发端口协议。 | 824 825**使用方法**： 826 827```shell 828$ hdc fport tcp:1234 tcp:1080 829Forwardport result:OK 830``` 831 832> **说明：** 833> 834> 在创建正向端口转发任务时，如果本地端口为TCP协议，指定端口为port，且启动服务进程时使用了-e参数， 则本地主机会监听-e参数指定的IP地址的port端口；如果启动服务进程时未使用-e参数，则本地主机会监听127.0.0.1:port。 835 836### 创建反向端口转发任务 837 838设置反向端口转发任务，系统将指定的“设备端口”转发到“主机端口”，命令格式如下： 839 840```shell 841hdc rport [IP:port] [IP:port] 842``` 843 844**返回信息**： 845 846| 返回信息 | 说明 | 847| -------- | -------- | 848| Forwardport result:OK. | 端口转发任务设置正常。 | 849| [Fail]Incorrect forward command. | 端口转发任务设置失败，端口转发参数错误。 | 850| [Fail]TCP Port listen failed at XXXX. | 端口转发任务设置失败，本地转发端口被占用。 | 851| [Fail]Forward parament failed. | 端口转发任务格式有误，或转发端口协议或端口范围有误。 | 852 853**使用方法**： 854 855```shell 856$ hdc rport tcp:1234 tcp:1080 857Forwardport result:OK 858``` 859 860### 删除端口转发任务 861 862删除指定的转发任务，命令格式如下： 863 864```shell 865hdc fport rm [IP:port][IP:port] 866``` 867 868**参数**： 869 870| 参数 | 说明 | 871| -------- | -------- | 872| IP:port | 端口转发任务，形如 tcp:XXXX tcp:XXXX。 | 873 874**返回信息**： 875 876| 返回信息 | 说明 | 877| -------- | -------- | 878| Remove forward ruler success, ruler:tcp:XXXX tcp:XXXX. | 端口转发任务删除正常。 | 879| [Fail]Remove forward ruler failed, ruler is not exist tcp:XXXX tcp:XXXX. | 端口转发任务删除失败，指定的转发任务不存在。 | 880 881**使用方法**： 882 883```shell 884$ hdc fport rm tcp:1234 tcp:1080 885Remove forward ruler success, ruler:tcp:1234 tcp:1080 886``` 887 888## 服务进程管理 889 890| 命令 | 说明 | 891| -------- | -------- | 892| start [-r] | 启动hdc服务进程，使用-r参数触发服务进程重新启动。 | 893| kill [-r] | 终止hdc服务进程，使用-r参数触发服务进程重新启动。 | 894| -p | 绕过对服务进程的查询步骤，用于快速执行客户端命令。 | 895| -m | 使用前台启动模式启动服务进程。<br/>前台启动模式（添加-m参数）：实时打印服务日志到客户端窗口。<br/>后台启动模式（不添加-m参数）：客户端不打印服务日志，日志内容写入本地磁盘文件，具体文件存放路径可参考[服务器进程日志](#服务器进程日志)。 | 896| -e | 指定在TCP端口转发时，本地监听的IP地址，默认是127.0.0.1。该参数必须和-m一起使用。| 897 898### 启动服务 899 900启动hdc服务进程，命令格式如下： 901 902```shell 903hdc start [-r] 904``` 905 906**返回信息**： 907 908| 返回信息 | 说明 | 909| -------- | -------- | 910| 无返回信息 | 服务进程启动成功。 | 911 912**使用方法**： 913 914```shell 915hdc start -r # 服务进程启动状态下，触发服务进程重新启动。 916``` 917 918> **说明：** 919> 920> 当启动hdc服务进程且系统未检测到运行的服务进程时，日志等级的设置优先级如下：若在同一命令中指定了-l参数和配置了OHOS_HDC_LOG_LEVEL环境变量，环境变量优先级高于-l参数；如果仅指定了-l参数，则采用该参数配置的日志等级；若两者均未指定，则服务进程将以默认日志等级LOG_INFO启动。 921 922### 终止服务 923 924命令格式如下： 925 926```shell 927hdc kill [-r] 928``` 929 930**返回信息**： 931 932| 返回信息 | 说明 | 933| -------- | -------- | 934| Kill server finish. | 服务进程终止成功。 | 935| [Fail]具体失败信息。 | 服务进程终止失败。 | 936 937**使用方法**： 938 939```shell 940$ hdc kill -r # 终止并重启服务进程，实际使用可执行hdc -l 5 kill -r命令查看详细重启的log。 941Kill server finish 942 943$ hdc kill # 终止服务进程。 944Kill server finish 945``` 946 947### 快速执行命令 948 949绕过对服务进程的查询步骤，用于快速执行客户端命令。服务未启动时执行命令不会重新启动服务，使用参数前确保服务已正常启动。命令格式如下： 950 951```shell 952hdc -p [command] 953``` 954 955**参数**： 956 957| 参数 | 说明 | 958| -------- | -------- | 959| command | hdc支持的命令。 | 960 961**返回信息**： 962 963| 返回信息 | 说明 | 964| -------- | -------- | 965| Connect server failed. | 与服务器进程建立连接失败。 | 966 967**使用方法**： 968 969```shell 970$ hdc start # 启动后台服务进程。 971 972$ hdc -p list targets # 跳过检查，直接执行命令。 973connect-key1 974connect-key2 975... 976``` 977 978> **说明：** 979> 980> 在未指定 -p 参数的情况下直接执行 command 命令时，客户端将首先检查本地是否已有运行的服务进程。如果系统未检测到运行的服务进程，客户端将自动启动服务进程，并建立连接以传递命令；如果系统检测到运行的服务进程，客户端将直接与该后台服务建立连接并下发相应的命令。 981 982### 前台启动服务 983 984使用前台启动模式启动服务进程，命令格式如下： 985 986```shell 987hdc -m 988``` 989 990**返回信息**： 991 992| 返回信息 | 说明 | 993| -------- | -------- | 994| Initial failed. | 服务进程初始化失败。 | 995| [I][1970-01-01 00:00:00.000] Program running. Ver: X.X.Xx Pid:XXX.<br/>... | 正常打印对应等级的日志，显示服务器进程活动状态。 | 996 997**使用方法**： 998 999```shell 1000$ hdc -s 127.0.0.1:8710 -m # 指定当前服务进程的网络监听参数并启动服务进程 1001[I][1970-01-01 00:00:00.000] Program running. Ver: 3.1.0e Pid:8236 1002$ hdc -e 0.0.0.0 -m # 指定端口转发本地监听IP地址为0.0.0.0并启动服务进程 1003[I][1970-01-01 00:00:00.000] Program running. Ver: 3.1.0e Pid:8236 1004... 1005``` 1006 1007> **说明：** 1008> 1009> 1. 在前台启动模式下，可通过附加 -s 参数来指定服务进程的网络监听参数。如果既没有使用 -s 指定网络监听参数，也没有配置环境变量OHOS_HDC_SERVER_PORT配置监听端口，系统将采用默认网络监听参数：127.0.0.1:8710。也可以通过-e参数来指定端口转发时本地主机监听的IP地址，如果没有使用-e参数，则默认监听127.0.0.1。 1010> 1011> 2. 在服务进程前台启动模式下，系统默认的日志输出等级为 LOG_DEBUG。如果需要变更日志等级，可通过使用 -l 参数来进行相应的设置。 1012> 1013> 3. 在运行环境中，仅允许存在一个服务进程实例。如果运行环境中已存在一个活跃的后台服务进程，尝试在前台启动新的服务进程实例将无法成功。 1014 1015## 设备操作 1016 1017| 命令 | 说明 | 1018| -------- | -------- | 1019| hilog [-h] | 打印设备端的日志信息，可通过hdc hilog -h查阅支持的参数列表。 | 1020| jpid | 显示设备上已打开应用的进程pid。 | 1021| track-jpid [-a\|-p] | 实时显示设备上已打开应用的进程pid和应用名，其中只有debug标签的应用可以被调试。不加参数时只显示debug应用的进程pid，使用-a或-p参数显示debug和release应用的进程标签，使用-p参数不显示debug和release的进程标签。 | 1022| target boot [-bootloader\|-recovery] | 重启目标设备，使用-bootloader参数重启后进入fastboot模式，使用-recovery参数重启后进入recovery模式。 | 1023| target boot [MODE] | 重启目标设备，加参数重启后进入相应的模式，其中MODE为/bin/begetctl命令中reboot支持的参数，可通过hdc shell "/bin/begetctl -h \| grep reboot"查看。 | 1024| <!--DelRow--> target mount | 以读写模式挂载系统分区（设备root后支持此命令）。 | 1025| <!--DelRow--> smode [-r] | 授予设备端hdc后台服务进程root权限， 使用-r参数取消授权（设备root后支持此命令）。 | 1026 1027### 打印设备端日志 1028 1029命令格式如下： 1030 1031```shell 1032hdc hilog [-h] 1033``` 1034 1035**参数**： 1036 1037| 参数 | 说明 | 1038| -------- | -------- | 1039| -h | hilog支持的参数，可通过hdc hilog -h查阅支持的参数列表。 | 1040 1041**返回信息**： 1042 1043| 返回信息 | 说明 | 1044| -------- | -------- | 1045| 返回具体信息。 | 抓取的日志信息。 | 1046 1047**使用方法**： 1048 1049```shell 1050$ hdc hilog -h 1051Usage: 1052-h --help 1053 Show all help information. 1054 Show single help information with option: 1055... 1056``` 1057 1058### 显示设备已打开应用的进程pid 1059 1060命令格式如下： 1061 1062```shell 1063hdc jpid 1064``` 1065 1066**返回信息**： 1067 1068| 返回信息 | 说明 | 1069| -------- | -------- | 1070| 进程号列表 | 开启了JDWP调试协议的应用的PID。 | 1071| [Empty] | 无开启了JDWP调试协议的进程。 | 1072 1073**使用方法**： 1074 1075```shell 1076$ hdc jpid 10771234 10781080 1079... 1080``` 1081 1082### 实时显示设备已打开应用的进程pid和应用名 1083 1084实时显示设备上已打开应用的进程pid和应用名称，命令格式如下： 1085 1086```shell 1087hdc track-jpid [-a|-p] 1088``` 1089 1090**参数**： 1091 1092| 参数 | 说明 | 1093| -------- | -------- | 1094| 不加参数 | 只显示已打开的应用的进程pid。 | 1095| -a | 显示debug和release应用的进程pid和包名/进程名，同时显示debug和release的标签。 | 1096| -p | 显示debug和release应用的进程pid和包名/进程名，但不显示debug和release的标签。 | 1097 1098**返回信息**： 1099 1100| 返回信息 | 说明 | 1101| -------- | -------- | 1102| 进程号和包名/进程名列表。 | 不加参数时仅显示已打开应用的进程pid，使用-p参数额外显示应用包名，使用-a参数同时显示debug和release标签。 | 1103| [Empty] | 无开启JDWP调试协议的应用进程。 | 1104 1105**使用方法**： 1106 1107```shell 1108$ hdc track-jpid -a 11091234 com.example.hello release 1110... 1111 1112$ hdc track-jpid -p 11131234 com.example.hello 1114... 1115``` 1116 1117### 重启目标设备 1118 1119命令格式如下： 1120 1121```shell 1122hdc target boot [-bootloader|-recovery] 1123hdc target boot [MODE] 1124``` 1125 1126**参数**： 1127 1128| 参数名 | 说明 | 1129| -------- | -------- | 1130| 不加参数 | 重启设备。 | 1131| -bootloader | 重启后进入fastboot模式。 | 1132| -recovery | 重启后进入recovery模式。 | 1133| MODE | 重启后进入MODE模式，MODE为/bin/begetctl命令中reboot支持的参数。 | 1134 1135**使用方法**： 1136 1137```shell 1138hdc target boot -bootloader # 重启后进入fastboot模式 1139hdc target boot -recovery # 重启后进入recovery模式 1140hdc target boot shutdown # 关机 1141``` 1142<!--Del--> 1143### 以读写模式挂载系统分区 1144 1145命令格式如下： 1146 1147 ```shell 1148 hdc target mount 1149 ``` 1150 1151 **返回值：** 1152 | 返回值 | 说明 | 1153 | -------- | -------- | 1154 | Mount finish | 挂载成功 | 1155 | [Fail]Mount failed | 挂载失败 | 1156 1157 **使用方法：** 1158 1159 ```shell 1160 hdc target mount 1161 ``` 1162 1163 > **说明：** 1164 > 1165 > 设备root后才支持此命令，对系统分区的修改存在一定风险，请谨慎使用。 1166 1167### 授予设备端hdc后台服务进程root权限 1168 1169命令格式如下： 1170 1171 ```shell 1172 hdc smode [-r] 1173 ``` 1174 1175 **返回值：** 1176 | 返回值 | 说明 | 1177 | -------- | -------- | 1178 | 无返回值 | 授予权限成功 | 1179 | [Fail]具体失败信息 | 授予权限失败 | 1180 1181 **使用方法：** 1182 1183 ```shell 1184 hdc smode 1185 hdc smode -r // 取消root权限 1186 ``` 1187 1188 > **说明：** 1189 > 1190 > 设备root后才支持此命令。 1191<!--DelEnd--> 1192 1193## 安全相关命令 1194 1195| 命令 | 说明 | 1196| -------- | -------- | 1197| keygen FILE | 生成一个新的密钥对，并将私钥和公钥分别保存到FILE和FILE.pub，其中FILE为自定义的文件名。 | 1198 1199命令格式如下： 1200 1201```shell 1202hdc keygen FILE 1203``` 1204 1205**参数**： 1206 1207| 参数 | 说明 | 1208| -------- | -------- | 1209| FILE | FILE为自定义的文件名。 | 1210 1211**使用方法**： 1212 1213```shell 1214# 在当前目录下生成key和key.pub文件 1215$ hdc keygen key 1216``` 1217 1218## 查询hdc版本号 1219 1220| 命令 | 说明 | 1221| -------- | -------- | 1222| -v | 打印客户端进程版本信息。 | 1223| version | 打印服务进程版本信息。 | 1224| checkserver | 获取客户端与服务进程版本。 | 1225 1226### 查询hdc客户端进程版本 1227 1228查询hdc客户端进程的版本信息，命令格式如下： 1229 1230```shell 1231hdc -v 1232``` 1233 1234**返回信息**： 1235 1236| 返回信息 | 说明 | 1237| -------- | -------- | 1238| Ver: X.X.Xx. | hdc（SDK）客户端进程版本信息。 | 1239 1240**使用方法**： 1241 1242```shell 1243$ hdc -v 1244Ver: 3.1.0e 1245``` 1246 1247### 查询hdc服务进程版本 1248 1249查询hdc服务进程的版本信息，命令格式如下： 1250 1251```shell 1252hdc version 1253``` 1254 1255**返回信息**： 1256 1257| 返回信息 | 说明 | 1258| -------- | -------- | 1259| Ver: X.X.Xx. | hdc（SDK）服务进程版本信息。 | 1260 1261**使用方法**： 1262 1263```shell 1264$ hdc version 1265Ver: 3.1.0e 1266``` 1267 1268### 查询客户端和服务器进程版本 1269 1270命令格式如下： 1271 1272```shell 1273hdc checkserver 1274``` 1275 1276**返回信息**： 1277 1278| 返回信息 | 说明 | 1279| -------- | -------- | 1280| Client version: Ver: X.X.Xx, Server version: Ver: X.X.Xx. | client（客户端），server（服务器）版本号。 | 1281 1282**使用方法**： 1283 1284```shell 1285$ hdc checkserver 1286Client version: Ver: 3.1.0e, Server version: Ver: 3.1.0e 1287``` 1288 1289## hdc调试日志 1290 1291### 服务器进程日志 1292 1293**指定运行时日志等级** 1294 1295hdc运行时日志等级，默认为LOG_INFO，命令格式如下： 1296 1297```shell 1298hdc -l [level] [command] 1299``` 1300 1301**参数**： 1302 1303| 参数 | 说明 | 1304| -------- | -------- | 1305| [level] | 指定运行时日志等级，等级随数字递增。设置日志级别时会启用当前及以下所有等级类型。例如，设置日志等级为3，可打印1~3类型的所有日志。<br/>0：LOG_OFF<br/>1：LOG_FATAL<br/>2：LOG_WARN<br/>3：LOG_INFO<br/>4：LOG_DEBUG<br/>5：LOG_ALL<br/>6：LOG_LIBUSB | 1306| command | hdc支持的命令。 | 1307 1308> **说明：** 1309> 1310> 1. 当配置运行时日志级别为6（LOG_LIBUSB）时，将激活libusb相关的增量日志输出，增量日志级别的详细程度高、数据量大，有助于准确诊断服务进程中与USB相关的异常情况，建议开发者按需使用。USB相关操作主要由服务进程执行，因此，只有服务进程具备打印增量日志的功能。相应地，客户端侧的日志几乎不包含增量日志信息。 1311> 1312> 2. 指定运行日志等级仅适用于当前进程（包括客户端与服务进程），无法更改已存在的进程日志等级。 1313 1314**返回信息**： 1315 1316| 返回信息 | 说明 | 1317| -------- | -------- | 1318| 日志信息。 | 指定等级的日志打印信息。 | 1319 1320**使用方法**： 1321 1322```shell 1323# 客户端打印LOG_DEBUG及以下级别日志，以执行shell ls为例 1324$ hdc -l 5 shell ls 1325[D][1970-01-01 00:00:00.000][12dc][xxxx.xxx:123] Mallocchannel:1234567 1326... 1327 1328# 服务进程前台模式启动指定LOG_LIBUSB级别日志 1329$ hdc kill && hdc -l 6 -m 1330Kill server finish 1331[I][1970-01-01 00:00:00.000][4f28][xxxx.xxx:123] Program running. Ver: 3.1.0e Pid:12345 1332... 1333 1334# 服务进程后台启动模式指定LOG_LIBUSB级别日志 1335$ hdc kill && hdc -l 6 start 1336Kill server finish 1337[D][1970-01-01 00:00:00.000][12dc][xxxx.xxx:123] Mallocchannel:1234567 1338... 1339``` 1340 1341> **说明：** 1342> 1343> 使用-m参数可以以前台启动服务进程，从而直接观察前台日志输出。如果需要退出进程，可按下Ctrl+C。 1344> 1345> 以后台启动时，可以在hdc.log中观察日志输出。 1346 1347**日志获取** 1348 1349请执行以下命令开启日志获取： 1350 1351```shell 1352hdc kill 1353hdc -l 5 start 1354``` 1355 1356收集到的完整日志存放路径如下： 1357 1358| 平台 | 路径 | 备注 | 1359| -------- | -------- | -------- | 1360| Windows | %temp%\ | 实际路径参考：C:\\Users\用户名\AppData\Local\Temp<br/>（实际使用请替换用户名变量）。 | 1361| Linux | /tmp/ | | 1362| MacOS | $TMPDIR/ | 实际路径可通过echo $TMPDIR查看，执行cd $TMPDIR命令可直接跳转至相应目录。 | 1363 1364日志文件类型包括： 1365 1366| 日志类型 | 日志名称格式 | 日志用途 | 备注 | 1367| -------- | -------- | -------- | -------- | 1368| 实时日志 | hdc.log | 实时记录服务器进程日志。 | 每次重启hdc服务进程，将会重命名原有日志并记录新的hdc.log。 | 1369| 历史日志临时文件 | hdc-%Y%m%d-%H%M%S.log | 转储历史日志归档生成的中间文件。 | 以时间2024年9月19日16:18:57.921为例，对应时间格式为：20240919-161857921，生成的日志临时文件名为：hdc-20240919-161857921.log。 | 1370| 历史日志归档文件 | hdc-%Y%m%d-%H%M%S.log.tgz | 压缩存储历史日志。 | 归档文件为.tgz类型压缩文件，可使用解压工具进行解压查看。以历史日志临时文件名hdc-20240919-161857921.log为例，对应的历史日志归档文件名为：hdc-20240919-161857921.log.tgz，历史日志归档文件生成后，对应的历史日志临时文件将自动删除。 | 1371| 实时日志缓存临时文件 | .hdc.cache.log | 实时日志产生的临时缓存。 | | 1372 1373### 设备端日志 1374 1375使用hilog日志工具获取对应日志，命令如下： 1376 1377```shell 1378hdc shell hilog -w start # 开启hilog日志落盘(已开启hilog日志工具再次执行会报错) 1379hdc shell hilog -w stop # 关闭hilog日志落盘(已关闭hilog日志工具再次执行会报错) 1380hdc shell ls /data/log/hilog # 查看已落盘hilog日志 1381hdc file recv /data/log/hilog {local_path} # 获取hilog已落盘日志（包含内核日志，local_path为本地路径，不同系统有所区别，这里未列举实际示例） 1382``` 1383 1384## 可选配置项 1385 1386### OHOS_HDC_SERVER_PORT 1387 1388默认值：8710。 1389 1390用于设置服务器进程运行时监听的端口号，该端口用于客户端与服务器之间的数据通讯。 1391 1392服务器进程启动时，默认会监听电脑的8710端口，客户端使用TCP协议通过此端口连接服务器。如果电脑的8710端口已经被使用或希望使用其他端口，可以通过添加环境变量OHOS_HDC_SERVER_PORT到系统环境变量中来修改服务器进程启动时监听的端口号。可以设置的端口范围为1~65535。 1393 1394例如，添加变量名为：OHOS_HDC_SERVER_PORT，变量值可设置为任意未被占用的端口，如18710。 1395 1396### OHOS_HDC_LOG_LEVEL 1397 1398默认值：3。 1399 1400用于设置服务进程日志记录级别，日志级别详情参考：[服务器进程日志](#服务器进程日志)指定运行时日志等级章节。 1401 1402### OHOS_HDC_HEARTBEAT 1403 1404默认：心跳功能开启。 1405 1406用于设置服务器和守护程序的心跳功能开关。 1407 1408服务器和守护程序启动后，默认会互相发送心跳数据包，收到心跳数据包后会记录在hdc的日志中，方便后期查看设备的连接情况。 1409 1410服务器进程运行的电脑中配置环境变量OHOS_HDC_HEARTBEAT为“1”后，服务器会关闭心跳特性；当有设备连接这台电脑后，服务器会给守护程序发送心跳特性关闭的信息，双方不再互相发送心跳数据包。 1411 1412设置为"1"表示关闭心跳功能，设置为其它数字表示开启心跳功能。 1413 1414### OHOS_HDC_CMD_RECORD 1415 1416默认：hdc命令录制关闭。 1417 1418用于设置hdc命令录制功能的开关。此功能仅记录执行的hdc命令，不记录命令的执行结果。 1419 1420设置为"1"表示开启命令录制功能；不设置或者设置为其它数字表示关闭命令录制功能。 1421 1422从API version 20开始，支持该参数。 1423 1424录制日志的存放路径如下： 1425 1426| 平台 | 路径 | 备注 | 1427| -------- | -------- | -------- | 1428| Windows | %temp%\hdc_cmd\ | 实际路径参考：C:\\Users\用户名\AppData\Local\Temp\hdc_cmd\<br/>（实际使用请替换用户名变量）。 | 1429| Linux | /tmp/hdc_cmd/ | | 1430| MacOS | $TMPDIR/hdc_cmd/ | | 1431 1432### OHOS_HDC_ENCRYPT_CHANNEL 1433 1434默认：通道加密功能关闭。 1435 1436用于设置服务器和守护程序之间的TCP连接通道加密功能开关。 1437 1438设置为"1"表示开启TCP连接的通道加密功能；不设置或者设置为其它数字表示关闭通道加密功能。 1439 1440从API version 20开始，支持该参数。 1441 1442> **说明：** 1443> 1444> 服务器进程运行时默认监听电脑端的8710端口，可通过设置系统环境变量OHOS_HDC_SERVER_PORT自定义监听的端口号。 1445 1446### 环境变量配置方法 1447 1448以配置OHOS_HDC_LOG_LEVEL值为5举例，介绍环境变量配置方法，更详细的步骤可参考[环境准备](#环境准备)。 1449 1450| 操作系统 | 配置方法 | 1451| -------- | -------- | 1452| Windows | 在电脑设置中搜索“查看高级系统设置”，在环境变量 > 系统变量 > Path > 编辑中，添加环境变量名称为OHOS_HDC_LOG_LEVEL，变量值为5。配置完毕后点击确认。环境变量配置完成后，关闭并重启命令行或其他使用到HarmonyOS SDK的软件，以生效新配置的环境变量。 | 1453| Linux | 在~/.bash_profile文件末尾追加内容export OHOS_HDC_LOG_LEVEL=5并保存后，执行source ~/.bash_profile生效当前环境变量。 | 1454| MacOS | 在~/.zshrc文件末尾追加内容export OHOS_HDC_LOG_LEVEL=5并保存后，执行source ~/.zshrc生效当前环境变量。环境变量配置完成后，关闭并重启命令行或其他使用到HarmonyOS SDK的软件，以生效新配置的环境变量。 | 1455 1456## hdc版本配套表 1457 1458| hdc版本 | API版本 | 新增特性 | 1459| -------- | -------- | -------- | 1460| 3.1.0a | 12 | wait命令支持-t参数：详细说明参见[等待设备正常连接](#等待设备正常连接)。 | 1461| 3.1.0e | 15 | - file send命令支持-b参数：详细说明参见[文件传输](#文件传输)。<br/>- file recv命令支持-b参数：详细说明参见[文件传输](#文件传输)。<br/>- shell命令支持-b参数：详细说明参见[执行交互命令](#执行交互命令)。 | 1462| 3.2.0b | 20 | - 端口转发任务支持监听远端主机IP：详细说明参见[创建正向端口转发任务](#创建正向端口转发任务)。 | 1463 1464> **注意：** 1465> 1466> 如果开发者当前运行的hdc版本较低，某些功能存在兼容性问题，需要根据功能特性提升版本时，可参考对应API版本说明下载最新版本。 1467 1468## 常见问题 1469 1470### 设备无法识别 1471 1472**现象描述** 1473 1474命令行执行hdc list targets命令后，返回结果为[Empty]。 1475 1476**可能原因&解决方法** 1477 1478**情况一**： 1479 1480查看设备管理器是否显示hdc设备。 1481 1482Windows环境： 1483 1484在设备管理器>通用串行总线设备中是否显示HDC Device（单一端口设备）或HDC Interface（复合端口设备）。 1485 1486Linux环境： 1487 1488在命令行执行lsusb，在返回的内容中检查是否有HDC Device（单一端口设备）或HDC Interface（复合端口设备）。 1489 1490MacOS环境： 1491 1492查看USB设备的系统信息或系统概述，步骤如下： 1493 14941. 按住键盘上的Option键，点按菜单（通常位于屏幕左上角）； 1495 14962. 选取系统信息或系统概述选项； 1497 14983. 在随后出现的窗口中，选择左边的USB选项； 1499 15004. 在随后显示的设备树中，查看是否有HDC Device（单一端口设备）或HDC Interface（复合端口设备）。 1501 1502**可采取的解决方法** 1503 1504如果上述环境中未显示hdc设备，说明设备未能被正确识别，开发者可以尝试以下方法解决： 1505 15061. 请尝试使用其他USB物理接口。 1507 15082. 更换USB数据线。 1509 15103. 使用其他计算机进行调试。 1511 15124. 启用设备的USB调试模式。 1513 15145. 当设备出现授权信任弹窗，请点击“信任”或“永久信任”。 1515 15166. 设备执行恢复出厂设置操作。 1517 1518**情况二**： 1519 1520存在USB设备，但是驱动损坏，显示"HDC Device"⚠警告图标。 1521 1522现象描述：该问题常见于Windows环境，表现在设备管理器>通用串行总线设备中，HDC Device显示为黄标警告，且描述信息为该设备无法正常工作。可尝试重新安装驱动解决，如重新安装驱动无法解决，可以尝试更换USB连接数据线/拓展坞/USB接口。 1523 1524**重新安装驱动的方法** 1525 15261. 打开设备管理器，右键点击存在警告图标的HDC Device； 1527 15282. 出现的菜单中点击更新驱动程序； 1529 15303. 出现的提示窗口（第1/3个）中，点击浏览我的电脑以查找驱动程序； 1531 15324. 出现的提示窗口（第2/3个）中，点击让我从计算机上的可用驱动程序列表中选取； 1533 15345. 出现的提示窗口（第3/3个）中，点击取消勾选显示兼容硬件，选择厂商：WinUSB设备，选择型号：WinUSB设备，选择完成后点击下一步按钮。 1535 1536**情况三**： 1537 1538连接设备时出现[Fail]Failed to communicate with daemon。 1539 1540现象描述：命令行执行hdc相关命令，返回[Fail]Failed to communicate with daemon。 1541 1542可能存在以下原因，可参考排查： 1543 15441. hdc或SDK版本与设备不匹配：如果设备更新到最新版本，可更新hdc或SDK工具至最新版本。 1545 15462. 端口被占用： 1547 1548当hdc和hdc_std使用同一端口同时运行时，OHOS_HDC_SERVER_PORT设置的端口互相冲突（未设置则使用默认端口8710，仍然会冲突）。只运行其中一个实例，其他软件占用hdc默认端口也会导致该问题发生。 1549 1550**情况四**： 1551 1552连接设备时出现Connect server failed。 1553 1554出现该现象，可能存在以下原因： 1555 1556**端口抢占** 1557 1558解决方法如下： 1559 15601. 排查具有自带hdc功能的软件进程。 1561 如果存在自带hdc的软件（DevEco Studio、DevEco Testing），请关闭这些软件后再执行hdc相关命令。 1562 15632. 查询hdc端口情况。 1564 以设置OHOS_HDC_SERVER_PORT为8710端口为例，不同平台的查询命令如下： 1565 1566 Unix： 1567 1568 ```shell 1569 netstat -an |grep 8710 1570 ``` 1571 1572 Windows： 1573 1574 ```shell 1575 netstat -an |findstr 8710 1576 ``` 1577 1578 如存在抢占的软件，请关闭该软件进程或更换OHOS_HDC_SERVER_PORT环境变量为其他端口号。 1579 15803. 排查未关闭的其他版本服务器进程。 1581 1582 Windows： 1583 1584 使用任务管理器>详细信息查询hdc.exe进程，右键打开文件所在位置，核对位置是否为配置的环境变量中的hdc文件位置，如果不一致，可尝试结束hdc.exe进程（执行hdc kill命令或者在任务管理器直接结束进程）并重新执行hdc命令。（关闭服务器进程后执行hdc命令会重启服务器）。 1585 1586 Unix： 1587 1588 使用ps -ef |grep hdc查询hdc后台服务器进程，核对进程启动位置是否为配置的环境变量中的hdc文件位置，如果不一致，可尝试结束hdc进程（hdc kill或者kill -9 hdc进程的pid）并重新执行hdc命令。（关闭服务器进程后执行hdc命令会重启服务器）。 1589 1590**注册表异常** 1591 1592解决方法：清理注册表，步骤如下： 1593 15941. 同时按下Win+R键，启动运行工具，输入栏输入regedit打开注册表； 1595 15962. 在注册表地址栏中输入以下内容并按回车键，即可进入USB类设备驱动程序的注册表； 1597 1598 ```shell 1599 计算机\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Class\{88bae032-5a81-49f0-bc3d-a4ff138216d6} 1600 ``` 1601 16023. 找到UpperFilters，右键点击”修改”，**备份**并清空其中的数值数据内容（如果清空后无法解决问题，可以依照备份恢复）； 1603 16044. 刷新设备管理器，插拔USB接口，或重启计算机。 1605 1606### Linux系统非管理员权限运行hdc提示无法找到设备 1607 1608**现象描述** 1609 1610Linux非管理员角色运行hdc后，使用USB方式连接设备后执行hdc list targets命令无法找到设备。 1611 1612**可能原因&解决方法** 1613 1614非管理员角色默认无USB设备操作权限，如果需要开启该权限，可按以下方法操作： 1615 1616- （临时权限）设置USB设备操作权限最大化： 1617 1618```shell 1619sudo chmod -R 777 /dev/bus/usb/ 1620``` 1621 1622- （永久权限）永久修改USB设备权限： 1623 1. 使用lsusb命令查找USB设备的vendorID和productID； 1624 2. 创建一个新的udev规则； 1625 编辑udev加载规则，用设备的“idVendor”和“idProduct”来替换默认值。 1626 1627 MODE="0666"来表示USB设备的权限GROUP；GROUP代表用户组，要确保此时登录的系统用户在该用户组中： 1628 1629 ```shell 1630 $ sudo vim /etc/udev/rules.d/90-myusb.rules 1631 SUBSYSTEMS=="usb", ATTRS{idVendor}=="067b", ATTRS{idProduct}=="2303", GROUP="users", MODE="0666" 1632 ``` 1633 1634 3. 重启电脑或重新加载udev规则： 1635 1636 ```shell 1637 sudo udevadm control --reload 1638 ``` 1639 1640> **注意：** 1641> 1642> 开启非管理员角色的USB设备操作权限可以解决在Linux环境在非管理员权限下使用hdc因权限不足无法找到设备的情况。但权限最大化可能存在潜在安全问题，请开发者根据使用场景自行评估是否开启此权限。 1643 1644### hdc无法运行 1645 1646**现象描述** 1647 1648使用命令行执行hdc命令无法运行。 1649 1650**可能原因&解决方法** 1651 16521. 运行环境异常。 1653 Linux运行环境：建议使用Ubuntu18.04及以上64位版本。如出现libc++.so引用错误，请使用ldd或readelf命令检查库引用。 1654 1655 MacOS运行环境：建议使用MacOS 11及以上版本。 1656 1657 Windows运行环境：建议使用Windows10或Windows11 64位版本，如低版本缺失WinUSB库或驱动，请使用Zadig工具进行更新。对于需要安装驱动的设备，请使用Zadig工具安装libusb-win32驱动。详情请见：[Zadig链接](https://github.com/pbatard/libwdi/releases)。 1658 16592. 运行方式不当：请使用命令行依照正确命令运行hdc工具，而非鼠标双击文件。 1660 1661### 使用hdc file send/recv传输中文文件出现乱码 1662 1663**现象描述** 1664 1665hdc文件传输命令执行出现乱码，如使用file recv从设备侧发送带有中文名称的文件到本地，报错提示[Fail]Error opening file: no such file or directory, path:XXXXX，其中path显示中文乱码。 1666 1667 1668 1669**可能原因&解决方法** 1670 16713.1.0a版本开始，文件传输命令支持参数路径中包含中文，版本过低需要更新至最新版本。 1672 1673执行hdc checkserver命令检查当前版本。如果低于3.1.0a版本，需将SDK升级到API12或更高版本。 1674 1675### 执行hdc list targets显示"Unauthorized" 1676 1677**现象描述** 1678 1679使用hdc list targets命令查询已连接设备，连接设备标识后显示Unauthorized。 1680 1681 1682 1683**可能原因&解决方法** 1684 1685- 首次连接未授权：连接设备后解锁设备，屏幕显示“是否信任此设备？”窗口，点击“始终信任”或“信任”完成授权。 1686 1687- 授权窗口关闭或拒绝授权：设备侧授权窗口会在超时后关闭，或开发者在授权窗口点击“不信任”拒绝授权。需要再次授权可在设备侧 设置 > 系统 > 开发者选项 > USB调试/无线调试 中，关闭已开启的调试开关后再开启，或执行hdc kill -r重启服务进程。屏幕会再次显示“是否信任此设备？”窗口，点击“始终信任”或“信任”完成授权。 1688 1689### 执行任意hdc命令报错：CryptAcquireContext second failed 1690 1691**现象描述** 1692 1693执行hdc相关命令报错：CryptAcquireContext second failed XXX。 1694 1695**可能原因&解决方法** 1696 1697修改电脑环境注册表信息： 1698 16991. 同时按下Win+R键，启动运行工具，在输入栏中输入regedit以打开注册表； 1700 17012. 注册表地址栏输入以下内容并按下回车 1702 计算机\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Protect\Providers\df9d8cd0-1501-11d1-8c7a-00c04fc297eb； 1703 17043. 右键新建DWORD(32位)值(D)，新增值名称为ProtectionPolicy 值为 1 （16进制），然后点击确定； 1705 17064. 重启电脑后问题解决。 1707 1708### Windows设备管理器出现 未知USB设备（设备描述符请求失败） 1709 1710**现象描述** 1711 1712使用USB方式连接调试设备，电脑端设备管理器通用串行总线控制器出现未知USB设备（设备描述符请求失败） 1713 1714**可能原因&解决方法** 1715 17161. 进入Windows服务管理（services.msc），禁止后重启Plug and Play服务； 1717 17182. 卸载设备管理器中出现故障的USB设备，并拔出USB线； 1719 17203. 重启计算机。 1721 1722尝试后，如果仍然无法识别，或者将设备连接到其他计算机上也无法识别，可能是USB设备的驱动出现故障，可以尝试更换USB连接线。 1723 1724### hdc命令执行异常 1725 1726**现象描述** 1727 1728hdc命令执行后未输出预期内容，可能涉及以下场景。 1729 1730- 场景一：执行hdc命令提示：Connect server failed。 1731 1732- 场景二：执行hdc命令提示：connect failed status:-4078。 1733 1734- 场景三：执行hdc命令无任何输出。 1735 1736**可能原因&解决方法** 1737 1738端口异常问题的解决方法如下： 1739 17401. 排查自带hdc的软件进程。包括自带hdc的软件（如DevEco Studio、DevEco Testing），如果存在这些软件，请关闭后再执行hdc相关命令。 1741 17422. 查询hdc端口情况。以设置的OHOS_HDC_SERVER_PORT为8710端口为例，在不同平台查询命令如下： 1743 Unix： 1744 1745 ```shell 1746 netstat -an |grep 8710 1747 ``` 1748 1749 Windows： 1750 1751 ```shell 1752 netstat -an |findstr 8710 1753 ``` 1754 1755 如存在抢占的软件，可以终止该软件进程，或者修改OHOS_HDC_SERVER_PORT环境变量为其他端口号。 1756 17573. 排查未关闭的其他版本服务器进程。 1758 1759 Windows：使用任务管理器>详细信息查询hdc.exe进程，右键打开文件所在位置，核对位置是否为配置的环境变量中的hdc文件位置，如果不一致，可尝试结束hdc.exe进程（命令行工具中执行hdc kill或者任务管理器直接结束进程）并重新执行hdc命令。（关闭服务器进程后执行hdc命令会重新启动服务器）。 1760 1761 Unix：使用ps -ef | grep hdc查询hdc后台服务器进程，核对进程启动位置是否为配置的环境变量中的hdc文件位置，如果不一致，可尝试结束hdc进程（hdc kill或者kill -9 hdc进程的pid）并重新执行hdc命令。（关闭服务器进程后执行hdc命令会重新启动服务器）。 1762 1763### 其他问题排查常用步骤 1764 17651. 命令行执行hdc list targets查看返回信息。 1766 17672. 检查设备管理是否有HDC Device。 1768 17693. 执行hdc kill关闭服务器进程后，执行hdc -l5 start收集日志（hdc.log位于执行端TEMP目录下，不同平台目录位置存在差异，可参考[服务器进程日志](#服务器进程日志)）。 1770 17714. 通过hdc.log日志定位相关问题。 1772 1773> **说明：** 1774> 1775> 更多常见问题处理可见[FAQ](https://developer.huawei.com/consumer/cn/doc/harmonyos-faqs/faqs-performance-analysis-kit)。 1776 1777## hdc错误码 1778 1779### E000001 hdc版本太低 1780 1781**错误信息** 1782 1783The sdk hdc.exe version is too low, please upgrade to the latest version. 1784 1785**错误描述** 1786 1787hdc版本太低，需更新至最新版本。 1788 1789**可能原因** 1790 1791客户端版本低于3.0.0b时，不支持授权，无法接入系统。 1792 1793**处理步骤** 1794 1795可参考[hdc版本配套表](#hdc版本配套表)升级到最新版本。 1796 1797### E000002 设备未授权 1798 1799**错误信息** 1800 1801The device unauthorized. 1802 1803This server's public key is not set. 1804 1805Please check for a confirmation dialog on your device. 1806 1807Otherwise try 'hdc kill' if that seems wrong. 1808 1809**错误描述** 1810 1811设备未授权。请检查是否在设备授权弹窗“信任”授权，如果已经授权，请尝试执行"hdc kill"命令后重新执行调试命令。 1812 1813**可能原因** 1814 1815- 场景一：首次连接设备未在设备侧授权调试计算机。 1816 1817- 场景二：授权窗口弹出，如果开发者点击了“信任”而非“始终信任”，在断开设备后重新连接时需要再次授权。 1818 1819**处理步骤** 1820 1821- 场景一：设备侧弹出授权窗口，点击授权。具体操作为：连接设备后，系统会自动弹出授权弹窗。 1822 1823- 场景二：进入设备侧 设置 > 系统 > 开发者选项，关闭调试开关后重新打开，重新连接设备进行授权；或者执行命令hdc kill -r后重新启动hdc，再次触发授权弹窗，点击“始终信任”。 1824 1825### E000003 设备侧用户未授权 1826 1827**错误信息** 1828 1829The device unauthorized. 1830 1831The user denied the access for the device. 1832 1833Please execute 'hdc kill' and redo your command, 1834 1835then check for a confirmation dialog on your device. 1836 1837**错误描述** 1838 1839设备未授权。设备侧拒绝授权调试，请执行"hdc kill"命令后重新执行调试命令，并且检查设备侧授权窗口提醒。 1840 1841**可能原因** 1842 18431. 设备侧授权窗口超时自动关闭，未确认授权。 1844 18452. 开发者点击“不信任”，拒绝授权。 1846 1847**处理步骤** 1848 1849进入设备侧 设置 > 系统 > 开发者选项，关闭调试开关后重新打开，重新连接设备进行授权；或执行命令hdc kill -r后重新启动hdc，再次触发授权弹窗，点击“始终信任”。 1850 1851### E000004 通信连接不稳定 1852 1853**错误信息** 1854 1855The communication channel is being established. 1856 1857Please wait for several seconds and try again. 1858 1859**错误描述** 1860 1861通信通道未建立，请等待几秒后重试。 1862 1863**可能原因** 1864 1865网络或USB连接未建立或连接不稳定。 1866 1867**处理步骤** 1868 1869连接设备后等待大约10秒，待连接建立后进行调试。 1870 1871### E001000 tmode不支持设置USB调试 1872 1873**错误信息** 1874 1875For USB debugging, please set it on the device's Settings UI. 1876 1877**错误描述** 1878 1879执行hdc tmode命令不支持设置USB调试。 1880 1881**可能原因** 1882 1883hdc tmode usb命令已废弃，参见[USB调试和无线调试切换](#usb调试和无线调试切换)。 1884 1885**处理步骤** 1886 1887参见[USB调试和无线调试切换](#usb调试和无线调试切换) tmode usb命令说明。 1888 1889### E001001 命令未知 1890 1891**错误信息** 1892 1893Unknown command. 1894 1895**错误描述** 1896 1897hdc tmode 命令有误。 1898 1899**可能原因** 1900 1901hdc tmode命令缺少参数或参数有误。 1902 1903**处理步骤** 1904 1905参考[USB调试和无线调试切换](#usb调试和无线调试切换)，完善执行命令。 1906 1907### E001003 USB连接异常 1908 1909**错误信息** 1910 1911USB communication abnormal, please check the USB communication link. 1912 1913**错误描述** 1914 1915USB通信异常，请检查USB通信链路。 1916 1917**可能原因** 1918 1919- USB连接线松动或断开。 1920 1921- 执行hdc shell reboot后，设备重启，连接正常断开，无需处理。 1922 1923- 执行hdc tmode port XXX，设备由USB调试方式转换为无线调试方式，连接正常断开，无需处理。 1924 1925**处理步骤** 1926 1927- 确认设备与电脑的USB线连接牢固。正常连接仍有异常，可尝试更换USB线或其他USB端口。 1928 1929- 参考[hdc版本配套表](#hdc版本配套表)章节，将版本升级到最新。 1930 1931### E001104 tconn命令IP地址非法 1932 1933**错误信息** 1934 1935IP address incorrect. 1936 1937**错误描述** 1938 1939IP地址格式不正确。 1940 1941**可能原因** 1942 1943使用tconn命令无线调试连接时，输入IP地址不符合IPv4格式。 1944 1945**处理步骤** 1946 1947检查输入IP地址是否合法，正确IP格式参照127.0.0.1:8888保证无异常非法字符，修正后重新连接。 1948 1949### E001005 设备未知或断连 1950 1951**错误信息** 1952 1953Device not found or connected. 1954 1955**错误描述** 1956 1957找不到连接设备或为非连接状态。 1958 1959**可能原因** 1960 1961设备断连。 1962 1963**处理步骤** 1964 1965参考[设备无法识别](#设备无法识别)中描述的实际场景对应的解决方式进行操作。 1966 1967### E001300 模拟器不支持tmode命令 1968 1969**错误信息** 1970 1971Not support tmode for Emulator. 1972 1973**错误描述** 1974 1975模拟器场景不支持hdc tmode命令。 1976 1977**可能原因** 1978 1979DevEco Studio中模拟器调试不支持hdc tmode命令。 1980 1981**处理步骤** 1982 1983如需调试tmode相关命令，请连接实体设备后进行调试。 1984 1985### E002101 服务器进程无法结束 1986 1987**错误信息** 1988 1989Terminal hdc process failed, please terminal the hdc process in the task manager first. 1990 1991**错误描述** 1992 1993服务器进程无法结束。 1994 1995**可能原因** 1996 1997当删除.hdcserver.pid文件后执行hdc kill时，由于无法获取服务器的进程pid，导致无法结束进程。 1998 1999**处理步骤** 2000 2001在任务管理器中手动结束hdc进程。 2002 2003### E002105 命令不支持 2004 2005**错误信息** 2006 2007Unsupport command. 2008 2009**错误描述** 2010 2011命令不支持。 2012 2013**可能原因** 2014 2015设备侧版本过低，不支持执行调试命令。 2016 2017**处理步骤** 2018 2019尝试升级设备版本，或参考[hdc命令列表](#hdc命令列表)检查命令是否准确。 2020 2021### E002106 设备通信异常 2022 2023**错误信息** 2024 2025Failed to communicate with daemon. 2026 2027**错误描述** 2028 2029服务器与设备侧守护程序通信异常。 2030 2031**可能原因** 2032 2033- USB调试连接断开。 2034 2035- TCP无线调试方式网络不稳定。 2036 2037**处理步骤** 2038 2039检查并确保设备已正常连接。 2040 2041检查网络状态，网络稳定后重新尝试连接。 2042 2043### E003001 （命令行）指定的包名非法 2044 2045**错误信息** 2046 2047Invalid bundle name: bundlename. 2048 2049**错误描述** 2050 2051命令hdc shell [-b bundlename] [command]中指定的 bundlename 不是已安装的可调试应用包名且已在设备启动，或应用目录不存在。 2052 2053**可能原因** 2054 20551. 场景一：设备上未安装指定的应用。 2056 20572. 场景二：指定包名的应用不是可调试应用。 2058 20593. 场景三：指定包名的应用未启动。 2060 2061**处理步骤** 2062 2063- 场景一：确认命令指定包名的应用已安装到设备上。 2064 执行hdc shell "bm dump -a | grep bundlename"查询对应包名的应用是否已安装到设备上，预期返回信息为 bundlename； 2065 2066 以应用名com.example.myapplication为例，查询命令如下： 2067 2068 ```shell 2069 hdc shell "bm dump -a | grep com.example.myapplication" 2070 ``` 2071 2072 如应用已安装到设备上，预期返回信息： 2073 2074 ```shell 2075 com.example.myapplication 2076 ``` 2077 2078- 场景二：确认命令指定的应用是否为可调试应用。 2079 1. 执行hdc shell "bm dump -n bundlename | grep appProvisionType"命令进行查询，预期返回信息为"appProvisionType": "debug"。 2080 以包名com.example.myapplication为例，可执行如下命令查询： 2081 2082 ```shell 2083 hdc shell "bm dump -n com.example.myapplication | grep appProvisionType" 2084 ``` 2085 2086 如包名对应的应用是可调试应用，预期返回的信息如下： 2087 2088 ```shell 2089 "appProvisionType": "debug", 2090 ``` 2091 2092 2. 要构建可调试应用，需要使用调试证书进行签名。可参考：[申请调试证书](https://developer.huawei.com/consumer/cn/doc/app/agc-help-add-debugcert-0000001914263178)。 2093 2094- 场景三：确定命令指定的应用已启动。 2095 1. 启动应用后，系统会挂载相应的资源目录。可执行hdc shell "mount |grep bundlename"查询应用启动后的资源目录挂载情况。 2096 以应用名com.example.myapplication为例，可执行如下命令查询是否已挂载资源目录： 2097 2098 ```shell 2099 hdc shell "mount |grep com.example.myapplication" 2100 ``` 2101 2102 如果已挂载相应的资源目录，预期将返回挂载信息（返回内容以实际挂载情况为准，此处不作展示）。 2103 2104 如果未挂载相应的资源目录，预期不会返回任何信息。 2105 2. 如果未挂载相应的资源目录，可以通过手动点击应用或使用aa相关命令启动应用。 2106 以应用名com.example.myapplication模块名EntryAbility为例，启动命令为： 2107 2108 ```shell 2109 hdc shell aa start -b com.example.myapplication -a EntryAbility 2110 ``` 2111 2112 更多详细用法请参考[aa命令介绍](../tools/aa-tool.md)。 2113 2114### E003002 命令行指定的参数不支持交互模式 2115 2116**错误信息** 2117 2118Unsupport interactive shell command option. 2119 2120**错误描述** 2121 2122命令hdc shell [-b bundlename] [command]不支持“交互模式”命令行。 2123 2124**可能原因** 2125 2126命令hdc shell [-b bundlename] [command]指定的 command 参数不可为空。 2127 2128**处理步骤** 2129 2130确认 command 参数不为空值，详细使用方法请参考[执行交互命令](#执行交互命令)。 2131 2132### E003003 交互命令参数不支持 2133 2134**错误信息** 2135 2136Unsupport shell option: XXX. 2137 2138**错误描述** 2139 2140命令hdc shell [-b bundlename] [command]指定了不支持的命令行参数。如-f，-B等。 2141 2142**可能原因** 2143 2144参数未区分大小写，或使用了不支持的参数。 2145 2146**处理步骤** 2147 2148参考[执行交互命令](#执行交互命令)使用当前版本支持的命令行参数，如-b参数。 2149 2150### E003004 设备侧不支持当前使用的参数 2151 2152**错误信息** 2153 2154Device does not support this shell option. 2155 2156**错误描述** 2157 2158当前设备不支持执行hdc shell [-b bundlename] [command]命令。 2159 2160**可能原因** 2161 2162设备系统版本较低，不支持新增的命令行参数。 2163 2164**处理步骤** 2165 2166升级设备操作系统版本到最新，具体版本可参考[hdc版本配套表](#hdc版本配套表)中版本配套说明。 2167 2168### E003005 命令行参数有误 2169 2170**错误信息** 2171 2172The parameter is missing, correct your input by referring below: Usage... 2173 2174**错误描述** 2175 2176hdc shell xxx，设备侧命令不支持。 2177 2178**可能原因** 2179 2180设备系统版本较低，不支持对应新增的命令行参数功能。 2181 2182**处理步骤** 2183 2184升级设备操作系统版本到最新，具体版本可参考[hdc版本配套表](#hdc版本配套表)中版本配套说明。 2185 2186### E005003 （文件传输）缺少参数 2187 2188**错误信息** 2189 2190The parameter is missing, correct your input by referring below: Usage... 2191 2192**错误描述** 2193 2194- 命令hdc file send [-b bundlename][SOURCE][DEST]缺少必要的参数。 2195 2196- 命令hdc file recv [-b bundlename][DEST][SOURCE]缺少必要的参数。 2197 2198**可能原因** 2199 2200命令指定-b参数时，缺少bundlename，SOURCE，DEST参数，命令详情参考[文件传输](#文件传输)。 2201 2202**处理步骤** 2203 2204确认命令参数bundlename，SOURCE，DEST参数均不为空。 2205 2206### E005004 SDK或设备系统不支持-b参数 2207 2208**错误信息** 2209 2210SDK/Device ROM doesn't support -b option. 2211 2212**错误描述** 2213 2214hdc file send/recv 命令带-b选项时，SDK中的hdc或设备系统版本不支持该选项。 2215 2216**可能原因** 2217 2218- 场景一：执行命令hdc file send [-b bundlename] [SOURCE] [DEST]时，设备系统版本不支持-b选项。 2219 2220- 场景二：执行命令hdc file recv [-b bundlename] [DEST] [SOURCE]时，SDK中的hdc不支持-b选项。 2221 2222**处理步骤** 2223 2224- 场景一：升级到最新系统版本，具体版本可参考[hdc版本配套表](#hdc版本配套表)中版本配套说明。 2225 2226- 场景二：升级到最新SDK版本，具体版本可参考[hdc版本配套表](#hdc版本配套表)中版本配套说明。 2227 2228### E005005 创建目录失败 2229 2230**错误信息** 2231 2232Error create directory: xxx, path: xxx. 2233 2234**错误描述** 2235 2236创建目录失败。 2237 2238**可能原因** 2239 2240执行hdc file send命令发送文件，设备侧对应目录为无权限目录或只读系统目录。 2241 2242**处理步骤** 2243 2244修改发送文件目标目录，确保目标目录有写权限。 2245 2246### E005101 （文件传输）指定的包名非法 2247 2248同错误码[E003001 （命令行）指定的包名非法](#e003001-命令行指定的包名非法)。 2249 2250### E005102 非法的远端路径 2251 2252**错误信息** 2253 2254Remote path: xxx is invalid, no such file/directory or it's out of the application directory. 2255 2256**错误描述** 2257 2258- 命令hdc file send [-b bundlename][SOURCE][DEST]指定的DEST表示的路径不存在或已超出应用数据目录。 2259 2260- 命令hdc file recv [-b bundlename][SOURCE][DEST]指定的DEST表示的路径不存在或已超出应用数据目录。 2261 2262**可能原因** 2263 2264- 场景一：远端路径不存在。 2265 2266- 场景二：参数DEST包含 .. 路径跳转符号，处理跳转后，实际目录超出了应用数据根目录。 2267 2268**处理步骤** 2269 2270检查参数DEST指定的应用数据目录相对路径是否真实存在。 2271 2272### E006001 安装包路径非法 2273 2274**错误信息** 2275 2276Not any installation package was found. 2277 2278**错误描述** 2279 2280没有找到任何安装包。 2281 2282**可能原因** 2283 2284命令hdc install后缺少安装包参数。 2285 2286**处理步骤** 2287 2288参考[应用管理](#应用管理)。 2289 2290### E007100 不支持的命令 2291 2292**错误信息** 2293 2294Operate need running under debug mode. 2295 2296**错误描述** 2297 2298命令仅在调试模式下支持。 2299 2300**可能原因** 2301 2302不支持的命令。 2303 2304**处理步骤** 2305 2306无需进行处理。 2307 2308### E005008 不支持的文件传输操作 2309 2310**错误信息** 2311 2312Operation not allowed. 2313 2314**错误描述** 2315 2316命令操作不被允许。 2317 2318**可能原因** 2319 2320涉及敏感文件（如系统配置，日志文件等）不允许操作。 2321 2322**处理步骤** 2323 2324无需进行处理。 2325 2326### E001106 -e指定的IP不正确 2327 2328**错误信息** 2329 2330-e content IP incorrect. 2331 2332**错误描述** 2333 2334-e指定的IP不正确。 2335 2336**可能原因** 2337 2338不是合法的IP地址格式。 2339 2340**处理步骤** 2341 2342检查输入是否为合法的IP格式，并确认该IP地址属于本机。 2343
