HarmonyOS 5 高效使用命令：HDC 使用指南

大家好，我是不想掉发的鸿蒙开发工程师城中的雾。

在上一系列中，我们探讨了如何写出炫酷的 UI。但对于开发者来说，写代码只是工作的一半，另一半是调试。

IDE（DevEco Studio）虽然功能强大，但在面对真机连接不稳定、应用安装失败、日志筛选困难等底层问题时，往往显得力不从心。这时候，我们需要一把"手术刀"------HDC (HarmonyOS Device Connector)。

HDC 是鸿蒙开发的命令行工具（类似于 Android 的 ADB）。本系列文章将带大家跳出 IDE 的图形界面，直接用命令行解决开发中那些让人头秃的疑难杂症。

第一期，我们先解决最基础也最容易出问题的一步：如何稳定地连上设备。

1. 环境配置：让终端认识 HDC

很多新手在终端输入 hdc 时，会收到 command not found 或 不是内部或外部命令 的报错。这是因为系统不知道去哪里找这个工具。

获取 HDC 工具

首先，你得找到 HDC 在哪。通常有以下两种方式：

通过 SDK 获取（最常用）：

DevEco Studio 已经内置了 SDK，无需额外下载。
- 默认路径 ：DevEco Studio安装目录/sdk/default/openharmony/toolchains
- MacOS ：位于 DevEco Studio.app/Contents/sdk/default/openharmony/toolchains
通过 Command Line Tools：

如果你使用的是独立的命令行工具，hdc 位于 Command Line Tools/sdk/default/openharmony/toolchains 路径下。

HDC 其实支持独立运行。你可以直接把 toolchains 目录下的 hdc 可执行文件和 libusb_shared 依赖文件拷贝到任意自定义目录，在那里面直接打开终端也能跑，适合不想配环境的"临时作战"。

但为了长久之计，我们还是推荐配置系统环境变量 ，这样你在任何路径下都能直接呼唤 hdc。

配置步骤 (Windows)

进入设置 ：按下 Windows 键，搜索并进入"设置"窗口；或者直接搜索"查看高级系统设置"。
编辑变量 ：
- 在"系统属性"窗口中，点击**"环境变量"**。
- 在**"系统变量"区域找到 Path，选中并点击"编辑"**。
添加路径 ：
- 点击**"新建"**，将 hdc.exe 所在的目录路径（即上面的 toolchains 路径）粘贴进去。
- 一路点击"确定"保存。
生效验证 ：
- 配置完成后，建议重启电脑（或重启所有终端窗口）以确保变量生效。
- 打开 CMD 或 PowerShell，输入 hdc -v，显示版本号即为成功。

配置步骤 (Linux/MacOS)

类 Unix 系统的配置需要通过终端修改 Shell 配置文件。

确认 Shell 类型：

打开终端，输入以下命令：
复制代码
```
echo $SHELL
```
编辑配置文件：
- 如果输出 /bin/bash，执行：vi ~/.bashrc
- 如果输出 /bin/zsh（MacOS 默认），执行：vi ~/.zshrc
添加 PATH 信息：
- 进入编辑器后，按 i 键进入 Insert 模式。
- 在文件末尾添加以下内容（注意替换 {DevEco Studio} 为你的实际安装路径）：
  
  export PATH={DevEco Studio实际路径}/sdk/default/openharmony/toolchains:$PATH
- MacOS 示例 ：export PATH=/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains:$PATH
保存并生效：
- 按 Esc 键退出编辑模式，输入 :wq 并回车保存。
- 执行以下命令立即使配置生效：
  
  source ~/.bashrc # 或者 source ~/.zshrc
重启：建议重启系统或重新登录，确保所有环境完全加载。

2. 基础连接：USB 调试

这是最常用的连接方式。

常用命令

查看连接设备：
复制代码
```
hdc list targets
```
- 正常：显示设备序列号（SN），如 1234567890ABCDEF。
- 异常：显示 [Empty] 或报错。

常见问题排查

如果 hdc list targets 为空，请按以下顺序检查：

开发者模式：确保手机已开启"开发者模式"和"USB 调试"。
授权弹窗：连接电脑后，留意手机上是否弹出了"是否允许 USB 调试"的弹窗，必须点击"始终允许"。
驱动/端口占用：这是 Windows 常见问题。有时候端口被占用导致 HDC 服务起不来。
- 绝招：强制重启 HDC 服务。
  复制代码
```
hdc kill -r
hdc start
```
  (注：-r 表示递归停止服务进程)

3. 进阶玩法：无线调试 (WiFi)

总是插着数据线开发很不方便，特别是需要连接外设（如键盘、鼠标）测试时。HDC 支持通过 TCP/IP 进行无线调试。

连接步骤

前提：手机和电脑必须连接在**同一个局域网（WiFi）**下。

初始化：先用 USB 线连接手机和电脑（第一次必须插线，否则无法授权）。
开启端口：设置手机监听 5555 端口。
复制代码
```
hdc tmode port 5555
```
- 成功提示 ：Set device run mode successful.
查看手机 IP：
- 方式 A：手机设置 -> 关于手机 -> 状态信息 -> IP 地址。
- 方式 B：直接用命令查（netcfg 命令在部分新机型已废弃，推荐使用 ifconfig）。
  复制代码
```
hdc shell ifconfig wlan0
```
  输出示例 ：找到 inet addr 后的数字，例如 172.16.130.221。
  复制代码
```
wlan0     Link encap:Ethernet  HWaddr ...
          inet addr:172.16.130.221  Bcast:...
```
建立连接 ：拔掉 USB 线，在电脑终端输入：
复制代码
```
hdc tconn 172.16.130.221:5555
```
(请替换为您实际查到的 IP)
- 成功提示 ：Connect OK
验证：再次输入 hdc list targets，如果看到 172.16.130.221:5555，说明连接成功。

恢复 USB 模式

如果想切回 USB 模式，或者无线连接出现异常，可以重置：

复制代码

hdc tmode usb

4. 多设备管理

当你同时连接了多台设备（比如一台真机、一台模拟器，或者一台手机、一台车机）时，执行命令必须指定目标，否则 HDC 不知道该听谁的。

指定设备执行命令：
复制代码
```
hdc -t [设备SN或IP] [命令]
```
- 示例：hdc -t 192.168.1.100:5555 shell ls

5. 番外：一键无线连接脚本 (Windows)

每次都要手动敲三个命令（开端口、查IP、连接）是不是很累？我们可以写一个 .bat 脚本来自动完成这个过程。

懒人脚本 (`connect_wifi.bat`)

在桌面新建一个文本文件，粘贴以下代码，保存为 .bat 后缀。插上 USB 线，双击运行即可。

优化说明：此版本已移除所有中文字符和注释，排除编码错误，通过临时文件稳定获取 IP。