1# hdc 2 3hdc（OpenHarmony Device Connector）是为开发人员提供的用于调试的命令行工具，通过该工具可以在windows/linux/mac系统上与设备进行交互。 4 5hdc分为三部分： 6 7**client**：运行在电脑端的进程，开发者在执行hdc命令时启动该进程，命令结束后进程退出。 8 9**server**：运行在电脑端的后台服务进程，用来管理client进程和设备端的daemon进程之间的数据交互，以及设备发现等。 10 11**daemon**：作为守护进程运行在设备端，用来响应电脑端server发来的请求。 12 13关系如下图所示： 14 15 16> **说明：** 17> 18> hdc client在启动时，默认会判断server是否正在运行，如果没有运行则会启动一个新的hdc程序作为server，运行在后台。 19> 20> hdc server运行时，默认会监听PC的8710端口，开发者可通过设置系统环境变量OHOS_HDC_SERVER_PORT自定义监听的端口号。 21 22## 环境准备 23 24hdc工具通过OpenHarmony SDK获取，存放于SDK的toolchains目录下。 25 26### （可选）命令行直接执行hdc程序 27 28开发者可通过命令行进入SDK的toolchains目录，在目录中执行hdc相关命令进行调试。 29为了方便在命令行中直接执行hdc程序，开发者也可以将hdc程序文件路径添加到操作系统命令搜索路径的环境变量中。 30例如，Windows系统可以添加到系统环境变量Path中。 31 32### （可选）server监听端口配置 33 34hdc server启动时，默认会监听PC的8710端口，hdc client使用tcp协议通过此端口连接server。如果PC的8710端口已经被使用或者希望使用其他端口，可以通过添加环境变量OHOS_HDC_SERVER_PORT到系统环境变量中来修改server启动时监听的端口号。 35例如，添加变量名为：OHOS_HDC_SERVER_PORT，变量值可设置为任意未被占用的端口，如18710。 36 37> **说明：** 38> 39> 环境变量配置完成后，关闭并重启命令行或其他使用到OpenHarmony SDK的软件。 40 41## hdc命令列表 42 43### 全局参数 44 45全局参数是指运行部分hdc命令时，可以跟随在hdc后面的参数，例如： 46选择指定的设备执行命令，使用-t参数： 47 48 ```shell 49 hdc -t connect-key shell echo "Hello world" 50 ``` 51 52| 参数 | 说明 | 53| -------- | -------- | 54| -t | 连接指定的目标设备，连接一台设备时为可选参数，连接多台设备时为必选参数。 | 55| -l | 可选参数，指定运行时日志等级，范围为数字0-6，默认为3（LOG_INFO）。 | 56| -s | 可选参数，指定客户端连接服务端时，服务进程的网络监听参数，格式为ip:port。 | 57| -p | 可选参数，绕过对服务进程的查询步骤，用于快速执行客户端命令。 | 58| -m | 可选参数，使用前台启动模式启动服务进程。 | 59 60### 命令列表 61| 命令 | 说明 | 62| -------- | -------- | 63| list targets | 查询已连接的所有目标设备。 | 64| wait | 等待设备正常连接。 | 65| tmode usb | 该命令已经废弃，不会实际操作设备连接通道，需要在设备设置界面通过USB调试开关进行设置。 | 66| tmode port | 打开设备网络连接通道。 | 67| tmode port close | 关闭设备网络连接通道。 | 68| tconn | 指定连接设备：通过“IP地址：端口号”来指定连接的设备。 | 69| shell | 在设备侧执行单次命令。 | 70| install | 安装指定的应用文件。 | 71| uninstall | 卸载指定的应用包。 | 72| file send | 从本地发送文件至远端设备。 | 73| file recv | 从远端设备发送文件至本地。 | 74| fport ls | 列出全部转发端口转发任务。 | 75| fport | 设置正向端口转发任务：监听“主机端口”，接收请求并进行转发， 转发到“设备端口”。 | 76| rport | 设置反向端口转发任务：监听“设备端口”，接收请求并进行转发，转发到“主机端口”。 | 77| fport rm | 删除指定的端口转发任务。 | 78| start | 启动hdc服务进程。 | 79| kill | 终止hdc服务进程。 | 80| hilog | 打印设备端的日志信息。 | 81| jpid | 显示设备上所有开启了JDWP调试协议的应用的PID。 | 82| track-jpid | 实时显示设备上开启了JDWP调试协议的应用的PID和应用名。 | 83| target boot| 重启目标设备。 | 84| <!--DelRow--> target mount | 以读写模式挂载系统分区（非root的设备不可用）。 | 85| <!--DelRow--> smode | 授予设备端hdc后台服务进程root权限， 使用-r参数取消授权（非root的设备不可用）。 | 86| keygen | 生成一个新的秘钥对。 | 87| version | 打印hdc版本信息，也可使用hdc -v打印版本信息。 | 88| checkserver | 获取客户进程与服务进程版本信息。 | 89 90> **说明：** 91> 92> 全局参数在使用时需要放在命令之前。 93 94## 基本使用方法 95 96在使用hdc前，请在设备上开启usb调试功能，用usb线连接设备和PC。 97 98### 查询连接的设备 99 100 ```shell 101 hdc list targets 102 ``` 103 104### 执行shell命令 105 106 ```shell 107 hdc shell echo "Hello world" 108 ``` 109 110### 获取帮助 111 112| 命令 | 说明 | 113| -------- | -------- | 114| -h [verbose] | 显示hdc相关的帮助信息。可选参数：verbose，显示详细的帮助信息。 | 115| help | 显示hdc相关的帮助信息。 | 116 117显示hdc相关的帮助信息，命令格式如下： 118 119 ```shell 120 hdc -h [verbose] 121 hdc help 122 ``` 123 124**返回值：** 125| 返回值 | 说明 | 126| -------- | -------- | 127| OpenHarmony device connector(HDC) ...<br/>---------------------------------global commands:----------------------------------<br/>-h/help [verbose] - Print hdc help, 'verbose' for more other cmds<br/>..._（此处省略详细帮助信息）_ | hdc命令使用帮助信息 | 128 129**使用方法：** 130 131```shell 132hdc -h 133hdc help 134 135// 显示详细帮助信息 136hdc -h verbose 137``` 138 139### 使用注意事项 140 141- 使用hdc时如出现异常，可尝试通过hdc kill -r命令杀掉异常进程并重启hdc服务。 142 143- 如出现hdc list targets获取不到设备信息的情况，参见[设备无法识别](#设备无法识别)章节。 144 145## 设备连接管理 146 147### 查询设备列表 148 149通过命令list targets，查询已连接的所有目标设备。 150添加-v参数，则会打印设备详细信息。 151命令格式如下： 152 153```shell 154hdc list targets [-v] 155``` 156 157**返回值：** 158| 返回值 | 说明 | 159| -------- | -------- | 160| 设备标识符列表 | 已连接的设备标识符列表，-t参数使用的connect-key即为此信息。 | 161| [Empty] | 没有查询到设备信息。 | 162 163**使用方法：** 164 165```shell 166hdc list targets 167hdc list targets -v 168``` 169 170### 连接指定的目标设备 171 172连接单台设备时，执行命令无需指定设备标识符； 173连接了多台设备时，每次执行命令时需要使用-t参数指定目标设备的标识符，命令格式如下： 174 175 ```shell 176 hdc -t [connect-key] [command] 177 ``` 178 179 **参数：** 180 | 参数名 | 说明 | 181 | -------- | -------- | 182 | connect-key| 设备标识符，即为hdc list targets返回的信息。 | 183 | command | hdc支持的命令。 | 184 185 > **说明：** 186 > 187 > connect-key为每个设备唯一的标识符。如果通过usb连接，标识符为序列号；如果通过网络连接设备，标识符为“IP地址:端口号”。 188 189 **返回值：** 190 | 返回值 | 说明 | 191 | -------- | -------- | 192 | 命令执行返回内容 | 请参考对应命令的返回值。 | 193 | [Fail]Not match target founded, check connect-key please | 没有找到与connect-key匹配的设备。 | 194 | [Fail]Device not founded or connected | 设备未找到或尚未连接。 | 195 | [Fail]ExecuteCommand need connect-key? please confirm a device by help info | 多设备连接时需要指定一个设备。 | 196 | Unknown operation command... | 不支持的命令。 | 197 198 > **说明：** 199 > 200 > 返回的错误提示信息后续会调整优化，请勿用于自动化脚本或程序的结果判断。 201 202 **使用方法：** 203 204 该方法需要与具体的操作命令搭配使用，下面以shell命令举例： 205 206 ```shell 207 hdc list targets // 查询已连接的所有目标设备的connect-key 208 hdc -t [connect-key] shell // -t 后面添加的connect-key需要替换为指定的设备标识符 209 ``` 210 211### 等待设备正常连接 212 213命令格式如下： 214 215 ```shell 216 hdc wait // 等待设备正常连接 217 hdc -t connect-key wait // 等待指定的设备正常连接，connect-key需要替换为指定的设备标识符 218 ``` 219 220 **返回值：** 221 | 返回值 | 说明 | 222 | -------- | -------- | 223 | 无 | hdc wait命令执行后，识别到正常连接的设备后结束。 | 224 225 **使用方法：** 226 227 ```shell 228 hdc wait 229 hdc -t connect-key wait 230 ``` 231 232### 常见连接场景 233 234#### USB连接场景 235 236- 环境确认 237 238| 确认项 | 正常 | 异常处理 | 239| -------- | -------- | -------- | 240| USB调试选项 | 开启 | 设备的USB调试模式如无法自动开启，请尝试重启设备。 | 241| USB数据连接线 | 使用USB数据连接线连接到调试PC的USB接口 | 如使用低带宽、无数据通信功能的USB连接线可能导致无法识别HDC设备，建议更换官方USB数据连接线。 | 242| USB接口 | 主板直出USB接口（台式机为后面板的USB接口，笔记本为机身的USB接口） | 如使用转接头/拓展坞/台式机前面板USB接口，存在带宽低和USB同步异常等问题，会导致频繁断连，推荐使用直连方式连接PC和设备。 | 243| hdc环境变量 | 终端命令行输入hdc -h有回显帮助信息内容 | 参见[环境准备章节](#环境准备)。 | 244| 驱动 | 连接HDC设备后，设备管理器通用串行总线设备存在设备"HDC Device"或"HDC Interface" | 参见[设备无法识别章节](#设备无法识别)。 | 245 246- 连接步骤 247 2481. PC通过USB连接设备。 249 2502. 查看已连接设备，执行以下命令： 251 252 ```shell 253 hdc list targets 254 ``` 255 256 返回值中存在对应设备的标识符，即为usb连接成功。 257 2583. 可以查询到设备后，即可运行设备相关命令和设备进行交互。如果希望不带设备标识符进行USB命令操作，需要确认设备不在tcp连接模式（hdc list targets查询的设备不包含IP:port形式的连接信息），直接连接即可，例如： 259 260 ```shell 261 hdc shell 262 ``` 263 264#### TCP连接场景 265 266 > **注意：** 267 > 268 > TCP调试功能尚未稳定，请谨慎用于生产环境。 269 270- 环境确认 271 272| 确认项 | 正常 | 异常处理 | 273| -------- | -------- | -------- | 274| 网络连接 | PC、手机设备处于同一网络。 | 连接同一WiFi或手机开启热点。 | 275| 网络状态 | telnet IP:port正常，网速稳定。 | 请选择稳定的网络连接方式。 | 276| hdc环境变量 | 终端命令行输入hdc -h有回显帮助信息内容 | 参见[环境准备章节](#环境准备)。 | 277 278- 连接步骤 279 2801. 在设备设置界面打开无线调试开关。 281 2822. 记录设备界面显示的监听端口号，记为PORT，用于后面的tcp连接。 283 2843. 通过tcp连接设备（需要事先知道设备IP和打开的PORT），执行以下命令： 285 286 ```shell 287 hdc tconn IP:PORT 288 ``` 289 IP地址可在设备侧的设置里面查看到，端口号为上一步设备无线调试界面显示的端口号。 290 2914. 查看已连接设备，执行以下命令： 292 293 ```shell 294 hdc list targets 295 ``` 296 297 返回值为IP:PORT形式即为连接成功。 298 2995. 如果需要关闭TCP连接模式，可以在设备中关闭无线调试开关。 300 301#### 远程连接场景 302 303远程连接场景是指客户端通过网络远程连接服务端，客户端和服务端在不同的PC运行，服务端连接设备。 304远程连接如图所示: 305 306 307 308hdc client（客户端）在PC1中运行，hdc server（服务端）在PC2中运行，PC2中的hdc server连接设备。 309 310- 连接命令 311 312 | 命令 | 说明 | 313 | -------- | -------- | 314 | -s | 指定当前服务进程的网络监听参数。 | 315 316 远程连接使用-s参数来指定服务端的网络参数，包括地址和端口号，该设置只在当前命令执行期间有效，命令格式如下： 317 318 ```shell 319 hdc -s [ip]:[port] [command] 320 ``` 321 322 **参数：** 323 | 参数 | 说明 | 324 | -------- | -------- | 325 | ip | 指定监听的IP地址，支持IPv4和IPv6。 | 326 | port | 指定监听的端口，范围：1~65535。 | 327 | command | hdc支持的命令。 | 328 329 **返回值：** 330 | 返回值 | 说明 | 331 | -------- | -------- | 332 | Connect server failed | 与服务进程建立连接失败。 | 333 | -s content port incorrect. | 端口号超出可设置范围（1~65535）。 | 334 335 **使用方法：** 336 337 ```shell 338 # 在已有服务进程，且服务进程的网络监听参数为127.0.0.1:8710的环境中，执行查询设备命令 339 hdc -s 127.0.0.1:8710 list targets 340 ``` 341 342 > **说明：** 343 > 344 > 当命令行中明确使用 -s 参数指定服务端口时，系统将忽略OHOS_HDC_SERVER_PORT环境变量中定义的端口设置。 345 346- 连接步骤 347 348 1. 服务端配置 349 350 服务端通过USB连接到对应的HDC设备后执行以下命令： 351 352 ```shell 353 hdc kill // 关闭本地hdc服务 354 hdc -s IP:8710 -m // 启动网络转发的hdc服务 355 // 其中IP为服务端自身的IP，windows可通过ipconfig查询，unix系统可通过ifconfig查询 356 // 8710为默认端口号，也可设置为其他端口号如：18710 357 // 启动后服务端将打印日志 358 ``` 359 360 2. 客户端连接 361 362 客户端连接需要确保可以连通服务端IP地址，满足前述条件后执行以下命令： 363 364 ```shell 365 hdc -s IP:8710 [command] // 其中IP为服务端IP，8710为第一步服务端启动时设置的端口号， 366 // 如果端口号有变化，这里也需要变更。 367 // command可以为任意hdc可用命令，例如list targets 368 ``` 369 370### usb调试和无线调试切换 371 372用于连接模式切换的命令如下表所示： 373 374当前推荐通过设备端的usb调试开关和无线调试开关来控制连接通道的开启和关闭。 375 376| 命令 | 说明 | 377| -------- | -------- | 378| tmode usb | 该命令已经废弃，不会实际操作设备连接通道，需要在设备设置界面通过USB调试开关进行设置。 | 379| tmode port [port-number] | 打开设备网络连接通道：设备端daemon进程会重启，已建立的USB连接会中断，需要重新连接。 | 380| tmode port close | 关闭设备网络连接通道：设备端daemon进程会重启，已建立的USB连接会中断，需要重新连接。 | 381| tconn [IP]:[port] [-remove] | 连接指定的设备，通过“IP地址：端口号”来指定连接的设备，使用-remove参数断开连接。 | 382 3831. 打开设备网络连接通道，命令格式如下： 384 385 ```shell 386 hdc tmode port [port-number] 387 ``` 388 389 **参数：** 390 | 参数 | 参数说明 | 391 | -------- | -------- | 392 | port-number | 监听连接的网络端口号，范围:1~65535。 | 393 394 **返回值：** 395 | 返回值 | 说明 | 396 | -------- | -------- | 397 | Set device run mode successful. | 打开成功。 | 398 | [Fail]ExecuteCommand need connect-key | 打开失败，设备列表无设备，无法打开设备无线调试通道。 | 399 | [Fail]Incorrect port range | 端口号超出可设置范围（1~65535）。 | 400 401 **使用方法：** 402 403 ```shell 404 hdc tmode port 1234 405 ``` 406 407 > **注意：** 408 > 409 > 切换前，请确保条件满足：远端设备与近端PC处于同一网络，且PC可ping通远端设备IP。 410 > 411 > 如不满足以上条件请勿使用该命令进行切换。 412 413 > **说明：** 414 > 415 > 执行完毕后，远端daemon进程将会退出并重启，USB连接将会断开，需要重新连接。 416 4172. 关闭设备网络连接通道，命令格式如下： 418 419 ```shell 420 hdc tmode port close 421 ``` 422 423 **返回值：** 424 | 返回值 | 说明 | 425 | -------- | -------- | 426 | [Fail]ExecuteCommand need connect-key | 设备列表无设备，无法执行命令。 | 427 428 **使用方法：** 429 430 ```shell 431 hdc tmode port close 432 ``` 433 > **说明：** 434 > 执行完毕后，远端daemon进程将会退出并重启，USB连接将会断开，需要重新连接。 435 4363. 通过TCP连接指定的设备，命令格式如下： 437 438 ```shell 439 hdc tconn [IP]:[port] [-remove] 440 ``` 441 442 **参数：** 443 | 参数 | 参数说明 | 444 | -------- | -------- | 445 | [IP]:[port] | 设备的IP地址与端口号。 | 446 | -remove | 可选参数，断开指定设备的连接。 | 447 448 **返回值：** 449 | 返回值 | 说明 | 450 | -------- | -------- | 451 | Connect OK | 连接成功 | 452 | [Info]Target is connected, repeat opration | 设备当前已连接 | 453 | [Fail]Connect failed | 连接失败 | 454 455 **使用方法：** 456 457 ```shell 458 hdc tconn 192.168.0.1:8888 459 hdc tconn 192.168.0.1:8888 -remove // 断开指定网络设备连接 460 ``` 461 462## 执行交互命令 463 464命令格式如下： 465 466 ```shell 467 hdc shell [-b bundlename] [command] 468 ``` 469 470 **参数：** 471 | 参数 | 说明 | 472 | -------- | -------- | 473 | [-b _bundlename_] | 指定可调试应用包名，在可调试应用数据目录内，以非交互式模式执行命令。<br>此参数当前仅支持以非交互式模式执行命令，不支持缺省command参数执行命令进入交互式shell会话，<br>未配置此参数默认执行路径为系统根目录。 | 474 | [command] | 需要在设备侧执行的单次命令，不同类型或版本的系统支持的command命令有所差异，可以通过hdc shell ls /system/bin查阅支持的命令列表。当前许多命令都是由[toybox](../tools/toybox.md)提供，可通过 hdc shell toybox --help 获取命令帮助。<br>缺省该参数，hdc将会启动一个交互式的shell会话，开发者可以在命令提示符下输入命令，比如 ls、cd、pwd 等。 | 475 476 **返回值：** 477 | 返回值 | 说明 | 478 | -------- | -------- | 479 | 交互命令返回内容 | 返回内容详情请参见其他交互命令返回内容。 | 480 | /bin/sh: XXX : inaccessible or not found | 不支持的交互命令。 | 481 | [Fail]具体失败信息 | 执行失败，参见[hdc错误码章节](#hdc错误码)。 | 482 483 **使用方法：** 484 485 ```shell 486 # 进入交互式模式执行命令 487 hdc shell 488 489 # 以非交互式模式执行命令 490 hdc shell ps -ef 491 492 # 查询全部可用命令 493 hdc shell help -a 494 495 # 在指定包名的应用数据目录内以非交互式模式执行命令，支持touch、rm、ls、stat、cat、mkdir命令。 496 hdc shell -b com.example.myapplication ls data/storage/el2/base/ 497 ``` 498 499 > **说明：** 500 > 501 > 使用参数[-b _bundlename_]指定包名，应满足条件：指定包名的已安装应用为“以debug模式构建的可调试应用”， 以debug模式构建应用可参考：[以debug模式构建HAR](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/ide-hvigor-build-har-V5#section197792874110)。 502 503## 应用管理 504 505| 命令 | 说明 | 506| -------- | -------- | 507| install _src_ | 安装指定的应用文件。 | 508| uninstall _packageName_ | 卸载指定的应用包package包名。 | 509 5101. 安装APP package，命令格式如下： 511 512 ```shell 513 hdc install [-r|-s] src 514 ``` 515 516 **参数：** 517 | 参数名 | 说明 | 518 | -------- | -------- | 519 | src| 应用安装包的文件名 | 520 | -r | 替换已存在应用（.hap） | 521 | -s | 安装一个共享包（.hsp） | 522 523 **返回值：** 524 | 返回值 | 说明 | 525 | -------- | -------- | 526 | AppMod finish | 成功情况下返回安装信息和AppMod finish。 | 527 | 具体安装失败原因 | 失败情况下返回具体安装失败信息。 | 528 529 **使用方法：** 530 531 以安装example.hap包为例： 532 533 ```shell 534 hdc install E:\example.hap 535 ``` 536 5372. 卸载应用，命令格式如下： 538 539 ```shell 540 hdc uninstall [-k|-s] packageName 541 ``` 542 543 **参数：** 544 | 参数名 | 说明 | 545 | -------- | -------- | 546 | packageName | 应用安装包。 | 547 | -k | 保留/data和/cache目录。 | 548 | -s | 卸载共享包。 | 549 550 **返回值：** 551 | 返回值 | 说明 | 552 | -------- | -------- | 553 | AppMod finish | 成功情况下返回卸载信息和AppMod finish。 | 554 | 具体卸载失败原因 | 失败情况下返回具体卸载失败信息。 | 555 556 **使用方法：** 557 558 以卸载com.example.hello包为例： 559 560 ```shell 561 hdc uninstall com.example.hello 562 ``` 563 564## 文件传输 565 566| 命令 | 说明 | 567| -------- | -------- | 568| file send _localpath remotepath_ | 从本地发送文件至远端设备。 | 569| file recv _remotepath localpath_ | 从远端设备发送文件至本地。 | 570 5711. 从本地发送文件至远端设备，命令格式如下： 572 573 ```shell 574 hdc file send [-a|-sync|-z|-m|-b bundlename] localpath remotepath 575 ``` 576 577 **参数：** 578 | 参数名 | 说明 | 579 | -------- | -------- | 580 | _localpath_ | 本地待发送的文件路径。 | 581 | _remotepath_ | 远程待接收的文件路径。 | 582 | -a | 保留文件时间戳。 | 583 | -sync | 只传输文件mtime有更新的文件。 | 584 | -z | 通过LZ4格式压缩传输，此功能未开放，请勿使用。 | 585 | -m | 文件传输时同步文件DAC权限，uid，gid，MAC权限。 | 586 | -b | 传输指定的可调试应用进程应用数据目录下的文件。 | 587 | _bundlename_ | 可调试应用进程的包名。 | 588 589 **返回值：** 590 591 文件发送成功，返回传输成功的结果信息。文件发送失败，返回传输失败的具体信息。 592 593 **使用方法：** 594 595 ```shell 596 hdc file send E:\example.txt /data/local/tmp/example.txt 597 hdc file send -b com.example.myapplication a.txt data/storage/el2/base/b.txt 598 ``` 599 600 > **说明：** 601 > 602 > 使用方法中，`hdc file send -b com.example.myapplication a.txt data/storage/el2/base/b.txt`指定了-b参数，将传输本地当前目录下的文件a.txt到包名为com.example.myapplication应用数据目录，传输到相对路径data/storage/el2/base/下，并重命名为b.txt。 603 > 604 > 使用参数[-b _bundlename_]指定包名，应满足条件：指定包名的已安装应用为“以debug模式构建的可调试应用”， 以debug模式构建应用可参考：[以debug模式构建HAR](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/ide-hvigor-build-har-V5#section197792874110)。 605 6062. 从远端设备发送文件至本地，命令格式如下： 607 608 ```shell 609 hdc file recv [-a|-sync|-z|-m|-b bundlename] remotepath localpath 610 ``` 611 612 **参数：** 613 | 参数名 | 说明 | 614 | -------- | -------- | 615 | _localpath_ | 本地待接收的文件路径。 | 616 | _remotepath_ | 远程待发送的文件路径。 | 617 | -a | 保留文件时间戳。 | 618 | -sync | 只传输文件mtime有更新的文件。 | 619 | -z | 通过LZ4格式压缩传输，此功能未开放，请勿使用。 | 620 | -m | 文件传输时同步文件DAC权限，uid，gid，MAC权限。 | 621 | -b | 传输指定的可调试应用进程应用数据目录下的文件。 | 622 | _bundlename_ | 可调试应用进程的包名。 | 623 624 **返回值：** 625 626 文件接收成功，返回传输成功的结果信息。文件接收失败，返回传输失败的具体信息。 627 628 **使用方法：** 629 630 ```shell 631 hdc file recv /data/local/tmp/a.txt ./a.txt 632 hdc file recv -b com.example.myapplication data/storage/el2/base/b.txt a.txt 633 ``` 634 635 > **说明：** 636 > 637 > 使用方法中，`hdc file recv -b com.example.myapplication data/storage/el2/base/b.txt a.txt`指定了-b参数，将传输名为com.example.myapplication可调试应用进程的应用数据相对路径data/storage/el2/base/下的文件b.txt到本地当前目录下，并重命名为a.txt。 638 > 639 > 使用参数[-b _bundlename_]指定包名，应满足条件：指定包名的已安装应用为“以debug模式构建的可调试应用”， 以debug模式构建应用可参考：[以debug模式构建HAR](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/ide-hvigor-build-har-V5#section197792874110)。 640 641## 端口转发 642 643| 命令 | 说明 | 644| -------- | -------- | 645| fport ls | 列出全部转发端口转发任务。 | 646| fport _localnode remotenode_ | 设置正向端口转发任务：监听“主机端口”，接收请求并进行转发， 转发到“设备端口”。 | 647| rport _remotenode localnode_ | 设置反向端口转发任务：监听“设备端口”，接收请求并进行转发，转发到“主机端口”。 | 648| fport rm _taskstr_ | 删除指定的端口转发任务。 | 649 650PC端支持的端口转发类型：tcp。 651 652设备端支持的端口转发类型：tcp，dev，localabstract，localfilesystem，jdwp，ark。 653 6541. 列出全部转发端口转发任务，命令格式如下： 655 656 ```shell 657 hdc fport ls 658 ``` 659 660 **返回值：** 661 | 返回值 | 说明 | 662 | -------- | -------- | 663 | tcp:1234 tcp:1080 [Forward] | 正向端口转发任务 | 664 | tcp:2080 tcp:2345 [Reverse] | 反向端口转发任务 | 665 | [empty] | 无端口转发任务 | 666 667 **使用方法：** 668 669 ```shell 670 hdc fport ls 671 ``` 672 6732. 设置正向端口转发任务，执行后将设置指定的“主机端口”转发数据到“设备端口”转发任务，命令格式如下： 674 675 ```shell 676 hdc fport localnode remotenode 677 ``` 678 679 **返回值：** 680 | 返回值 | 说明 | 681 | -------- | -------- | 682 | Forwardport result:OK | 端口转发任务设置正常。 | 683 | [Fail]Incorrect forward command | 端口转发任务设置失败，端口转发参数错误。 | 684 | [Fail]TCP Port listen failed at XXXX | 端口转发任务设置失败，本地转发端口被占用。 | 685 686 **使用方法：** 687 688 ```shell 689 hdc fport tcp:1234 tcp:1080 690 ``` 691 6923. 设置反向端口转发任务，执行后将设置指定的“设备端口”转发数据到“主机端口”转发任务，命令格式如下： 693 694 ```shell 695 hdc rport remotenode localnode 696 ``` 697 698 **返回值：** 699 | 返回值 | 说明 | 700 | -------- | -------- | 701 | Forwardport result:OK | 端口转发任务设置正常。 | 702 | [Fail]Incorrect forward command | 端口转发任务设置失败，端口转发参数错误。 | 703 | [Fail]TCP Port listen failed at XXXX | 端口转发任务设置失败，本地转发端口被占用。 | 704 705 **使用方法：** 706 707 ```shell 708 hdc rport tcp:1234 tcp:1080 709 ``` 7104. 删除端口转发任务，执行后将指定的转发任务删除，命令格式如下： 711 712 ```shell 713 hdc fport rm taskstr 714 ``` 715 716 **参数：** 717 | 参数 | 说明 | 718 | -------- | -------- | 719 | _taskstr_ | 端口转发任务，形如 tcp:XXXX tcp:XXXX。 | 720 721 **返回值：** 722 | 返回值 | 说明 | 723 | -------- | -------- | 724 | Remove forward ruler success, ruler:tcp:XXXX tcp:XXXX | 端口转发任务删除正常。 | 725 | [Fail]Remove forward ruler failed, ruler is not exist tcp:XXXX tcp:XXXX | 端口转发任务删除失败，不存在指定的转发任务。 | 726 727 **使用方法：** 728 729 ```shell 730 hdc fport rm tcp:1234 tcp:1080 731 ``` 732 733## 服务进程管理 734 735| 命令 | 说明 | 736| -------- | -------- | 737| start [-r] | 启动hdc服务进程，使用-r参数触发服务进程重新启动。 | 738| kill [-r] | 终止hdc服务进程，使用-r参数触发服务进程重新启动。 | 739| -p | 绕过对服务进程的查询步骤，用于快速执行客户端命令。 | 740| -m | 使用前台启动模式启动服务进程。 | 741 742 7431. 启动hdc服务进程，命令格式如下： 744 745 ```shell 746 hdc start [-r] 747 ``` 748 749 **返回值：** 750 | 返回值 | 说明 | 751 | -------- | -------- | 752 | 无返回值 | 服务进程启动成功 | 753 754 **使用方法：** 755 756 ```shell 757 hdc start 758 hdc start -r // 服务进程启动状态下，触发服务进程重新启动 759 ``` 760 761 > **说明：** 762 > 763 > 当启动hdc服务进程且系统未检测到运行的服务进程时，日志等级的设置优先级如下：若同时指定了-l参数和配置了OHOS_HDC_LOG_LEVEL环境变量，则使用环境变量配置的日志等级；如果仅指定了-l参数，则采用该参数配置的日志等级；若两者均未指定，则服务进程将以默认的LOG_INFO等级启动。 764 7652. 终止hdc服务进程，命令格式如下： 766 767 ```shell 768 hdc kill [-r] 769 ``` 770 771 **返回值：** 772 | 返回值 | 说明 | 773 | -------- | -------- | 774 | Kill server finish | 服务进程终止成功 | 775 | [Fail]具体失败信息 | 服务进程终止失败 | 776 777 **使用方法：** 778 779 ```shell 780 hdc kill 781 hdc kill -r // 重启并终止服务进程 782 ``` 783 7843. 绕过对服务进程的查询步骤，用于快速执行客户端命令，命令格式如下： 785 786 ```shell 787 hdc -p [command] 788 ``` 789 790 **参数：** 791 | 参数 | 说明 | 792 | -------- | -------- | 793 | command | hdc支持的命令 | 794 795 **返回值：** 796 | 返回值 | 说明 | 797 | -------- | -------- | 798 | Connect server failed | 与服务进程建立连接失败 | 799 800 **使用方法：** 801 802 ```shell 803 # 启动后台服务进程 804 hdc start 805 # 跳过进程查询，直接执行命令 806 hdc -p list targets 807 ``` 808 809 > **说明：** 810 > 811 > 在未指定 -p 参数的情况下直接执行 command 命令时，客户端将首先检查本地是否已有运行的服务进程。若系统未检测到运行的服务进程，客户端将自动启动服务进程，并建立连接以传递命令；若系统检测到运行的服务进程，客户端将直接与该后台服务建立连接并下发相应的命令。 812 8134. 使用前台启动模式启动服务进程，命令格式如下： 814 815 ```shell 816 hdc -m 817 ``` 818 819 **返回值：** 820 | 返回值 | 说明 | 821 | -------- | -------- | 822 | Initial failed | 服务进程初始化失败。 | 823 | [I][_1970-01-01 00:00:00.000_][_abcd_][_session.cpp:25_] _Program running. Ver: X.X.Xa Pid:12345_ | 正常打印对应等级的日志，显示服务端活动状态。 | 824 825 **使用方法：** 826 827 ```shell 828 # 指定当前服务进程的网络监听参数并启动服务进程 829 hdc -s 127.0.0.1:8710 -m 830 ``` 831 832 > **说明：** 833 > 834 > 1. 使用前台启动参数时，可通过附加 -s 参数来指定服务进程的网络监听参数。如果既没有使用 -s 指定网络监听参数，也没有配置环境变量OHOS_HDC_SERVER_PORT配置监听端口，系统将采用默认网络监听参数:127.0.0.1:8710。 835 > 2. 在服务进程前台启动模式下，系统默认的日志输出等级设置为 LOG_DEBUG。如需变更日志等级，可通过结合使用 -l 参数来进行相应的调整。 836 > 3. 在运行环境中，仅允许单一的服务进程实例存在。若运行环境中已存在一个活跃的后台服务进程，那么尝试在前台启动新的服务进程实例将不会成功。 837 838## 设备操作 839 840| 命令 | 说明 | 841| -------- | -------- | 842| hilog [-h] | 打印设备端的日志信息，可通过hdc hilog -h查阅支持的参数列表。 | 843| jpid | 显示设备上所有开启了JDWP调试协议的应用的PID。 | 844| track-jpid [-a\|-p] | 实时显示设备上开启了JDWP调试协议的应用的PID和应用名，不加参数只显示debug的应用的进程，使用-a参数显示debug和release应用的进程，使用-p参数不显示debug和release的标签。 | 845| target boot [-bootloader\|-recovery] | 重启目标设备，使用-bootloader参数重启后进入fastboot模式，使用-recovery参数重启后进入recovery模式。 | 846| target boot [MODE] | 重启目标设备，加参数重启后进入相应的模式，其中MODE为/bin/begetctl命令中reboot支持的参数。 | 847| <!--DelRow--> target mount | 以读写模式挂载系统分区（设备root后支持此命令）。 | 848| <!--DelRow--> smode [-r] | 授予设备端hdc后台服务进程root权限， 使用-r参数取消授权（设备root后支持此命令）。 | 849 8501. 打印设备端的日志信息，命令格式如下： 851 852 ```shell 853 hdc hilog [-h] 854 ``` 855 856 **参数：** 857 | 参数 | 说明 | 858 | -------- | -------- | 859 | [-h] | hilog支持的参数，可通过hdc hilog -h查阅支持的参数列表。 | 860 861 **返回值：** 862 | 返回值 | 说明 | 863 | -------- | -------- | 864 | 返回具体信息 | 抓取的日志信息。 | 865 866 **使用方法：** 867 868 ```shell 869 hdc hilog 870 ``` 871 8722. 显示设备上所有开启了JDWP调试协议的进程的PID，命令格式如下： 873 874 ```shell 875 hdc jpid 876 ``` 877 878 **返回值：** 879 | 返回值 | 说明 | 880 | -------- | -------- | 881 | 进程号列表 | 开启了JDWP调试协议的应用的PID。 | 882 | [empty] | 无开启了JDWP调试协议的进程。 | 883 884 **使用方法：** 885 886 ```shell 887 hdc jpid 888 ``` 889 8903. 实时显示设备上开启了JDWP调试协议的进程的PID和应用名，命令格式如下： 891 892 ```shell 893 track-jpid [-a|-p] 894 ``` 895 896 **参数：** 897 | 参数 | 说明 | 898 | -------- | -------- | 899 | 不加参数 | 只显示debug的应用的进程号和包名/进程名。 | 900 | -a | 显示debug和release应用的进程号和包名/进程名。 | 901 | -p | 显示debug和release应用的进程号和包名/进程名，但不显示debug和release的标签。 | 902 903 **返回值：** 904 | 返回值 | 说明 | 905 | -------- | -------- | 906 | 进程号和包名/进程名列表 | - | 907 | [empty] | 不加参数时表示无开启了JDWP调试协议的debug应用的进程，使用-a或-p参数时表示无开启了JDWP调试协议的进程。 | 908 909 **使用方法：** 910 911 ```shell 912 hdc track-jpid 913 ``` 914 9154. 重启目标设备，命令格式如下： 916 917 ```shell 918 target boot [-bootloader|-recovery] 919 target boot [MODE] 920 ``` 921 922 **参数：** 923 | 参数名 | 说明 | 924 | -------- | -------- | 925 | 不加参数| 重启设备 | 926 | -bootloader| 重启后进入fastboot模式。 | 927 | -recovery | 重启后进入recovery模式。 | 928 | MODE | 重启后进入MODE模式，MODE为/bin/begetctl命令中reboot支持的参数。<br> 可通过hdc shell "/bin/begetctl -h \| grep reboot"查看。 | 929 930 **使用方法：** 931 932 ```shell 933 hdc target boot -bootloader // 重启后进入fastboot模式 934 hdc target boot -recovery // 重启后进入recovery模式 935 hdc target boot shutdown // 关机 936 ``` 937 938<!--Del--> 9395. 以读写模式挂载系统分区，命令格式如下： 940 941 ```shell 942 hdc target mount 943 ``` 944 945 **返回值：** 946 | 返回值 | 说明 | 947 | -------- | -------- | 948 | Mount finish | 挂载成功 | 949 | [Fail]Mount failed | 挂载失败 | 950 951 **使用方法：** 952 953 ```shell 954 hdc target mount 955 ``` 956 957 > **说明：** 958 > 959 > 设备root后才支持此命令，对系统分区的修改存在一定的风险，请谨慎使用。 960 9616. 授予设备端hdc后台服务进程root权限，命令格式如下： 962 963 ```shell 964 hdc smode [-r] 965 ``` 966 967 **返回值：** 968 | 返回值 | 说明 | 969 | -------- | -------- | 970 | 无返回值 | 授予权限成功 | 971 | [Fail]具体失败信息 | 授予权限失败 | 972 973 **使用方法：** 974 975 ```shell 976 hdc smode 977 hdc smode -r // 取消root权限 978 ``` 979 980 > **说明：** 981 > 982 > 设备root后才支持此命令。 983 984<!--DelEnd--> 985 986## 安全相关命令 987 988| 命令 | 说明 | 989| -------- | -------- | 990| keygen FILE | 生成一个新的秘钥对，并将私钥和公钥分别保存到FILE和FILE.pub，其中文件名FILE可自定义。 | 991 9921. 生成一个新的秘钥对，命令格式如下： 993 994 ```shell 995 hdc keygen FILE 996 ``` 997 998 **参数：** 999 | 参数 | 说明 | 1000 | -------- | -------- | 1001 | FILE | FILE为自定义的文件名 | 1002 1003 **使用方法：** 1004 1005 ```shell 1006 hdc keygen key // 在当前目录下生成key和key.pub文件 1007 ``` 1008 1009## 查询版本号 1010 1011| 命令 | 说明 | 1012| -------- | -------- | 1013| -v/version | 打印hdc版本信息。 | 1014| checkserver | 获取客户端与服务进程版本。 | 1015 10161. 显示hdc的版本信息，命令格式如下： 1017 1018 ```shell 1019 hdc -v/version 1020 ``` 1021 1022 **返回值：** 1023 | 返回值 | 说明 | 1024 | -------- | -------- | 1025 | Ver: X.X.Xa | hdc（SDK）的版本信息。 | 1026 1027 **使用方法：** 1028 1029 ```shell 1030 hdc -v 或 hdc version 1031 ``` 1032 10332. 获取客户端与服务进程版本，命令格式如下： 1034 1035 ```shell 1036 hdc checkserver 1037 ``` 1038 1039 **返回值：** 1040 | 返回值 | 说明 | 1041 | -------- | -------- | 1042 | Client version: Ver: X.X.Xa, Server version: Ver: X.X.Xa | client（客户端），server（服务进程）版本号。 | 1043 1044 **使用方法：** 1045 1046 ```shell 1047 hdc checkserver 1048 ``` 1049 1050## hdc调试日志 1051 1052### server端日志 1053 1054#### 指定运行时日志等级 1055 1056hdc运行时日志等级，默认为LOG_INFO，命令格式如下： 1057 1058 ```shell 1059 hdc -l [level] [command] 1060 ``` 1061 1062 **参数：** 1063 | 参数 | 说明 | 1064 | -------- | -------- | 1065 | [level] | 指定运行时日志等级<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。 | 1066 | command | hdc支持的命令。 | 1067 1068 > **说明：** 1069 > 1070 > 1. 当配置运行时日志级别为6（LOG_LIBUSB）时，将激活libusb相关的增量日志输出，增量日志级别的详细程度高、数据量大，有助于精确诊断服务进程中与USB相关的异常情况。USB相关操作主要由服务进程执行，因此，只有服务进程具备打印增量日志的功能。相应地，客户端侧的日志几乎不包含增量日志信息。 1071 > 2. 指定运行时日志等级仅适用于当前进程（包括客户端与服务进程），无法更改已存在的进程日志等级。 1072 1073 **返回值：** 1074 | 返回值 | 说明 | 1075 | -------- | -------- | 1076 | 命令执行返回内容 | 请参考对应命令的返回值。 | 1077 | 日志信息 | 对应指定的运行时等级日志打印。 | 1078 1079 **使用方法：** 1080 1081 客户端打印LOG_DEBUG级别日志，以执行shell ls为例，命令示例如下: 1082 1083 ```shell 1084 hdc -l 5 shell ls 1085 ``` 1086 1087 服务进程前台模式启动指定LOG_LIBUSB级别日志，命令示例如下: 1088 1089 ```shell 1090 hdc kill && hdc -l 6 -m 1091 ``` 1092 1093 > **说明：** 1094 > `-m`参数指定以前台模式启动服务进程，可以直接观察前台日志输出，按下Ctrl+C退出进程。 1095 1096 服务进程后台启动模式指定LOG_LIBUSB级别日志，命令示例如下: 1097 1098 ```shell 1099 hdc kill && hdc -l 6 start 1100 ``` 1101 1102 > **说明：** 1103 > 以后台模式启动，可以在hdc.log中观察日志输出，日志路径可以查看**日志获取**章节的描述。 1104 1105#### 日志获取 1106 1107执行以下命令开启日志获取： 1108 1109```shell 1110hdc kill 1111hdc -l5 start 1112``` 1113 1114收集到的完整日志存放路径： 1115 1116| 平台 | 路径 | 备注 | 1117| -------- | -------- | -------- | 1118| Windows | %temp%\hdc.log | 实际路径参考，实际使用请替换用户名变量<br/>C:\Users\用户名\AppData\Local\Temp\hdc.log。 | 1119| Linux | /tmp/hdc.log | - | 1120| MacOS | $TMPDIR/hdc.log | - | 1121 1122日志相关环境变量： 1123 1124| 环境变量名称 | 默认值 | 说明 | 1125|--------------------|-----|--------------------------------| 1126| OHOS_HDC_LOG_LEVEL | 5 | 用于配置服务进程日志记录级别，日志级别详情参考：<br>[server端日志](#server端日志)指定运行时日志等级章节。 | 1127 1128环境变量配置方法： 1129 1130以下通过配置OHOS_HDC_LOG_LEVEL环境变量为例，配置环境变量值为：5，介绍环境变量配置方法。 1131 1132| 操作系统 | 配置方法 | 1133|---|---| 1134| Windows | 在**此电脑 > 属性 > 高级系统设置 > 高级 > 环境变量**中，添加环境变量名称为OHOS_HDC_LOG_LEVEL，变量值为5。配置完毕后点击确认。环境变量配置完成后，关闭并重启命令行或其他使用到OpenHarmony SDK的软件，以生效新配置的环境变量。 | 1135| Linux | 在~/.bash_profile文件末尾追加内容export OHOS_HDC_LOG_LEVEL=5并保存后，执行`source ~/.bash_profile`生效当前环境变量。 | 1136| MacOS | 在~/.zshrc文件末尾追加内容export OHOS_HDC_LOG_LEVEL=5并保存后，执行`source ~/.zshrc`生效当前环境变量。环境变量配置完成后，关闭并重启命令行或其他使用到OpenHarmony SDK的软件，以生效新配置的环境变量。 | 1137 1138### 设备端日志 1139 1140开启hilog日志工具，获取对应日志，命令如下： 1141 1142```shell 1143hdc shell hilog -w start // 开启hilog日志落盘 1144hdc shell ls /data/log/hilog // 查看已落盘hilog日志 1145hdc file recv /data/log/hilog // 获取hilog已落盘日志（包含内核日志） 1146``` 1147 1148## 常见问题 1149 1150### 设备无法识别 1151 1152**现象描述** 1153 1154命令行执行`hdc list targets`命令后，返回结果为`[empty]`。 1155 1156**可能原因&解决方法** 1157 1158可通过以下方式排查。 1159 1160- 情况一：查看设备管理是否显示HDC设备。 1161 1162 Windows环境： 1163 1164 在`设备管理器`>`通用串行总线设备`中是否显示`HDC Device`（单一端口设备）或`HDC Interface`（复合端口设备）。 1165 1166 Linux环境： 1167 1168 在命令行执行`lsusb`,在返回的内容中查看是否有`HDC Device`（单一端口设备）或`HDC Interface`（复合端口设备）。 1169 1170 MacOS环境： 1171 1172 使用`系统信息`或`系统概述`来查看USB设备，步骤如下： 1173 1174 1. 按住键盘上的Option键，点按菜单。 1175 1176 2. 选取`系统信息`或`系统概述`。 1177 1178 3. 在随后出现的窗口中，选择左边的`USB`。 1179 1180 4. 在随后显示的设备树查看是否有`HDC Device`（单一端口设备）或`HDC Interface`（复合端口设备）。 1181 1182 **可采取的解决方法** 1183 1184 以上环境如没有显示HDC设备，则说明无法识别设备，可以根据实际场景尝试以下方法： 1185 1186 - 使用其他USB物理接口。 1187 - 更换USB数据连接线。 1188 - 使用其他计算机调试。 1189 - 设备开启USB调试模式。 1190 - 设备出现弹窗点击允许调试。 1191 - 如可通过TCP模式连接，可执行`hdc tmode usb`命令恢复USB连接。 1192 - 设备恢复出厂设置。 1193 1194- 情况二：存在USB设备，但是驱动损坏，显示"HDC Device"⚠警告图标。 1195 1196 现象描述：该问题常见于Windows环境，现象为`设备管理器`>`通用串行总线设备`中，`HDC Device`显示为黄标警告，且描述信息为该设备无法正常工作。可尝试重新安装驱动解决，如重新安装驱动无法解决，可以尝试更换USB连接数据线/拓展坞/USB接口。 1197 1198 **重新安装驱动的方法** 1199 1200 1. 打开`设备管理器`，右键点击存在警告图标的`HDC Device`； 1201 1202 2. 出现的菜单中点击`更新驱动程序`； 1203 1204 3. 出现的提示窗口（第1/3个）中，选取`浏览我的电脑以查找驱动程序`； 1205 1206 4. 出现的提示窗口（第2/3个）中，选取`让我从计算机上的可用驱动程序列表中选取`； 1207 1208 5. 出现的提示窗口（第3/3个）中，取消勾选`显示兼容硬件`，选择厂商：`WinUSB设备`，选择型号：`WinUSB设备`，选择完成后点击`下一步`按钮。 1209 1210- 情况三：连接设备时出现`[Fail]Failed to communicate with daemon`。 1211 1212 现象描述：命令行执行hdc相关命令，执行失败返回`[Fail]Failed to communicate with daemon`。 1213 1214 可能存在以下原因，可参考排查： 1215 1216 - hdc或SDK版本与设备不匹配: 如果设备更新到最新版本，可更新hdc或SDK工具至最新版本。 1217 - 端口被占用： 1218 1219 常见于hdc和hdc_std使用同一端口，同时运行时OHOS_HDC_SERVER_PORT设置的端口互相冲突（未设置则使用默认端口8710，仍然会冲突），注意只运行其中一个。其他软件占用hdc默认端口也会导致该问题发生。 1220 1221- 情况四：连接设备时出现`Connect server failed`。 1222 1223 出现该现象，可能有如下原因： 1224 1225 - **端口抢占** 1226 1227 解决方法如下： 1228 1. 排查自带hdc的软件进程。 1229 1230 包括自带hdc的软件（DevEco Studio、DevEco Testing），如存在请关闭这些软件后再执行hdc相关命令。 1231 1232 2. 查询HDC端口情况。 1233 1234 以设置的OHOS_HDC_SERVER_PORT为8710端口为例，在不同平台查询命令如下： 1235 1236 Unix： 1237 1238 ```shell 1239 netstat -an |grep 8710 1240 ``` 1241 1242 Windows: 1243 1244 ```shell 1245 netstat -an |findstr 8710 1246 ``` 1247 1248 如存在抢占的软件，可以关闭该软件进程或者更换OHOS_HDC_SERVER_PORT环境变量为其他端口号。 1249 1250 3. 排查未关闭的其他版本hdc server。 1251 1252 Windows： 1253 1254 使用`任务管理器`>`详细信息`查询hdc.exe进程,右键打开文件所在位置，核对位置是否为配置的环境变量中的hdc文件位置，如果不一致，可尝试结束hdc.exe进程(hdc kill或者任务管理器直接结束进程)并重新执行hdc命令。（关闭hdc server后执行hdc命令会重新启动hdc server） 1255 1256 Unix： 1257 1258 使用`ps -ef |grep hdc`查询hdc后台server进程，核对进程启动位置是否为配置的环境变量中的hdc文件位置，如果不一致，可尝试结束hdc进程(hdc kill或者kill -9 hdc进程的PID)并重新执行hdc命令。（关闭hdc server后执行hdc命令会重新启动hdc server） 1259 1260 - **注册表异常** 1261 1262 解决方法：清理注册表，步骤如下： 1263 1264 1. 同时按下`Win`+`R`键，启动运行工具，输入栏输入`regedit`打开注册表。 1265 2. 注册表地址栏输入以下内容并按下`回车`，即可进入USB类设备驱动程序的注册表。 1266 1267 ```shell 1268 计算机\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Class\{88bae032-5a81-49f0-bc3d-a4ff138216d6} 1269 ``` 1270 1271 3. 找到`UpperFilters`键，右键`修改`编辑，**备份**并清空其中数值数据内容（如清空后无法解决问题可依照备份恢复）。 1272 4. 刷新设备管理器/插拔USB接口/重启计算机。 1273 1274<!--Del--> 1275 1276**linux系统非root权限运行hdc无法找到设备** 1277 1278linux环境可以选择开启非root用户USB设备操作权限，方法如下： 1279 1280- （临时权限）设置USB设备操作权限最大化: 1281 1282 ```shell 1283 sudo chmod -R 777 /dev/bus/usb/ 1284 ``` 1285 1286- （永久权限）永久修改USB设备权限: 1287 1288 1. 使用lsusb找出USB设备的vendorID和productID。 1289 1290 2. 创建一个新的udev规则。 1291 1292 编辑udev加载规则，用设备的“idVendor”和“idProduct”来替换默认值。 1293 1294 MODE="0666"来表示USB设备的权限GROUP；GROUP代表用户组，要确保此时登录的系统用户在该用户组中： 1295 1296 ```shell 1297 sudo vim /etc/udev/rules.d/90-myusb.rules 1298 SUBSYSTEMS=="usb", ATTRS{idVendor}=="067b", ATTRS{idProduct}=="2303", GROUP="users", MODE="0666" 1299 ``` 1300 1301 3. 重启电脑或重新加载udev规则： 1302 1303 ```shell 1304 sudo udevadm control --reload 1305 ``` 1306 1307> **注意：** 1308> **开启非root用户USB设备操作权限**可以解决Linux环境在非root权限下使用hdc无法找到设备的情况，但权限最大化**可能存在潜在安全问题**，请开发者根据使用场景自行评估是否开启。 1309 1310<!--DelEnd--> 1311 1312### hdc无法运行 1313 1314**现象描述** 1315 1316使用命令行执行hdc.exe/hdc 二进制文件无法运行。 1317 1318**可能原因&解决方法** 1319 1320- 运行环境异常 1321 1322 Linux运行环境：建议使用Ubuntu18.04及以上64版本，如出现libc++.so引用错误，请使用ldd/readelf等命令检查库引用。 1323 1324 MacOS运行环境：建议使用MacOS 11及以上版本。 1325 1326 Windows运行环境：建议使用Windows10/Windows11 64位版本，如低版本缺失WinUSB库/驱动，请使用Zadig工具更新。对于符合设备，需要使用Zadig工具安装libusb-win32驱动。详情请见：[Zadig链接](https://github.com/pbatard/libwdi/releases)。 1327 1328- 运行方式不当：请使用命令行依照正确命令运行hdc工具，而非鼠标双击文件。 1329 1330### 其他问题排查常用步骤 1331 13321. 命令行执行`hdc list targets`查看返回值。 13332. 查看`设备管理`是否有`HDC Device`。 13343. 执行`hdc kill`关闭server后，执行`hdc -l5 start`收集日志（hdc.log位于执行端TEMP目录，不同平台目录位置存在差异，可参考[server端日志](#server端日志)）。 13354. 通过hdc.log日志定位相关问题。 1336 1337## hdc错误码 1338 1339### E003001 （命令行）指定的包名非法 1340 1341**错误信息** 1342 1343Invalid bundle name: _bundlename_ 1344 1345**错误描述** 1346 1347命令`hdc shell [-b bundlename] [command]`指定的 _bundlename_ 不是已安装的可调试应用包名，或应用目录不存在。 1348 1349**可能原因** 1350 1351* 场景一：指定的应用未安装到设备上。 1352 1353* 场景二：指定包名的应用，不是以debug模式构建的应用。 1354 1355* 场景三：指定包名的应用没有启动。 1356 1357**处理步骤** 1358 1359* 场景一：确认命令指定包名的应用已安装到设备上。 1360 1361 a.可执行`hdc shell "bm dump -a | grep bundlename"`查询对应包名的应用是否已安装到设备上，预期返回信息为 _bundlename_； 1362 1363 以应用名`com.example.myapplication`为例，查询命令如下： 1364 1365 ```shell 1366 hdc shell "bm dump -a | grep com.example.myapplication" 1367 ``` 1368 1369 如应用已安装到设备上，预期返回信息： 1370 1371 ```shell 1372 com.example.myapplication 1373 ``` 1374 1375 b.如应用为可调试应用，但未安装到设备上，可执行`hdc install [app_path]`安装应用； 1376 1377 c.如应用不是可调试应用，而是release类型的应用，将不支持指定 _bundlename_ 执行命令相关功能。 1378 1379* 场景二：确认命令指定的应用是以debug模式构建的可调试应用，可执行`hdc shell "bm dump -n bundlename | grep debug"`查询，预期返回信息为`"appProvisionType": "debug", "debug": true`。 1380 1381 以包名`com.example.myapplication`为例，可执行如下命令查询： 1382 1383 ```shell 1384 hdc shell "bm dump -n com.example.myapplication | grep debug" 1385 ``` 1386 1387 如包名对应的应用是以debug模式构建的可调试应用，预期返回信息： 1388 1389 ```shell 1390 "appProvisionType": "debug", 1391 "debug": true, 1392 ``` 1393 1394 如何以debug模式构建应用请参考：[以debug模式构建HAR](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/ide-hvigor-build-har-V5#section197792874110) 1395 1396* 场景三：确定命令指定的应用已启动。 1397 1398 a.启动应用后，系统会挂载相应的资源目录，可执行`hdc shell "mount |grep bundlename"`查询应用启动后的资源目录挂载情况。 1399 1400 以应用名`com.example.myapplication`为例，可执行如下命令查询是否已挂载资源目录： 1401 1402 ```shell 1403 hdc shell "mount |grep com.example.myapplication" 1404 ``` 1405 1406 如已挂载相应的资源目录，预期返回挂载信息（返回内容以实际挂载情况为准，此处不作展示）。 1407 1408 如未挂载相应的资源目录，预期无返回信息。 1409 1410 b.如未挂载相应的资源目录，可以通过手动点击应用或通过`aa`相关命令启动应用。 1411 1412 以应用名`com.example.myapplication`模块名`EntryAbility`为例，启动命令为： 1413 1414 ```shell 1415 hdc shell aa start -b com.example.myapplication -a EntryAbility 1416 ``` 1417 1418 更多详细用法请参考[aa命令介绍](../tools/aa-tool.md)。 1419 1420### E003002 命令行指定的参数不支持交互模式 1421 1422**错误信息** 1423 1424Unsupport interactive shell command option 1425 1426**错误描述** 1427 1428命令`hdc shell [-b bundlename] [command]`不支持“交互模式”命令行。 1429 1430**可能原因** 1431 1432命令`hdc shell [-b bundlename] [command]`指定的 _command_ 参数为空值。 1433 1434**处理步骤** 1435 1436确认命令的 _command_ 参数不为空值，详细使用方法参考[执行交互命令介绍](#执行交互命令)。 1437 1438### E003003 不支持的命令行参数 1439 1440**错误信息** 1441 1442Unsupported shell option: _option_ 1443 1444**错误描述** 1445 1446命令`hdc shell [-b bundlename] [command]`存在不支持的命令行参数 _option_ 。 1447 1448**可能原因** 1449 1450命令`hdc shell [-b bundlename] [command]`指定了如`-f`、`-B`等不支持的命令行参数（参数区分大小写）。 1451 1452**处理步骤** 1453 1454请使用当前版本支持的命令行参数，如`-b`参数。 1455 1456### E003004 存在设备不支持的命令行参数 1457 1458**错误信息** 1459 1460Device does not supported this shell command 1461 1462**错误描述** 1463 1464命令`hdc shell [-b bundlename] [command]`存在设备不支持的命令行参数。 1465 1466**可能原因** 1467 1468设备系统版本较低，不支持对应新增的命令行参数功能。 1469 1470**处理步骤** 1471 1472升级设备系统版本到最新。 1473 1474### E003005 （命令行）缺少参数 1475 1476**错误信息** 1477 1478The parameter is missing, correct your input by referring below: _Usage_ 1479 1480**错误描述** 1481 1482`hdc shell [-b bundlename] [command]`命令指定选项时，缺少必要的参数。 1483 1484**可能原因** 1485 1486命令指定-b选项时，缺少 _bundlename_、 _command_ 参数，参数详细释义参考[执行交互命令介绍](#执行交互命令)。 1487 1488**处理步骤** 1489 1490确认命令的 _bundlename_ 、 _command_ 参数均不为空。 1491 1492### E005101 （文件传输）指定的包名非法 1493 1494**错误信息** 1495 1496Invalid bundle name: _bundlename_ 1497 1498**错误描述** 1499 1500命令`hdc file send/recv [-b bundlename] [localpath] [remotepath]`指定的 _bundlename_ 不是已安装的可调试应用包名，或应用目录不存在。 1501 1502**可能原因** 1503 1504同错误码[E003001](#e003001-命令行指定的包名非法) 1505 1506**处理步骤** 1507 1508同错误码[E003001](#e003001-命令行指定的包名非法) 1509 1510### E005102 非法的远程路径 1511 1512**错误信息** 1513 1514Remote path: _remotepath_ is invalid, it is out of the application directory. 1515 1516**错误描述** 1517 1518命令`hdc file send [-b bundlename] [localpath] [remotepath]`指定的 _remotepath_ 表示的路径不存在或者已超出应用数据目录。 1519 1520命令`hdc file recv [-b bundlename] [remotepath] [localpath]`指定的 _remotepath_ 表示的路径不存在或者已超出应用数据目录。 1521 1522**可能原因** 1523 1524* 场景一：路径不存在。 1525 1526* 场景二：参数 _remotepath_ 包含`..`跳转符号，处理跳转后，实际目录超出了应用数据根目录。 1527 1528**处理步骤** 1529 1530检查参数 _remotepath_ 指定的应用数据目录相对路径是否真实存在。 1531 1532### E005003 （文件传输）缺少参数 1533 1534**错误信息** 1535 1536The parameter is missing, correct your input by referring below: _Usage_ 1537 1538**错误描述** 1539 1540命令`hdc file send [-b bundlename] [localpath] [remotepath]`缺少必要的参数。 1541 1542命令`hdc file recv [-b bundlename] [remotepath] [localpath]`缺少必要的参数。 1543 1544**可能原因** 1545 1546命令指定-b选项时，缺少 _bundlename_、 _localpath_、 _remotepath_ 参数，参数详细释义参考[文件传输命令介绍](#文件传输)。 1547 1548**处理步骤** 1549 1550确认命令的 _bundlename_、_localpath_、_remotepath_ 参数均不为空。 1551 1552### E005004 SDK或者设备系统版本不支持-b选项 1553 1554**错误信息** 1555 1556SDK/Device ROM doesn't support -b option. 1557 1558**错误描述** 1559 1560hdc file send/recv 命令带-b选项时，SDK中的hdc或设备系统版本不支持该选项。 1561 1562**可能原因** 1563 1564* 场景一：执行命令`hdc file send [-b bundlename] [localpath] [remotepath]`时，设备系统版本不支持-b选项。 1565 1566* 场景二：执行命令`hdc file recv [-b bundlename] [remotepath] [localpath]`时，SDK中的hdc不支持-b选项。 1567 1568**处理步骤** 1569 1570* 场景一：升级到最新系统版本。 1571 1572* 场景二：升级到最新SDK版本。
