鸿蒙 hdc 远程连接：从环境准备到实战调试

1. 引言

在鸿蒙应用开发过程中，开发者经常需要在真机上调试应用。相比 USB 连接，hdc 远程连接可以摆脱线缆束缚，让开发调试更加灵活。本文将详细介绍鸿蒙 hdc 远程连接的环境准备、连接步骤和常见问题排查。

2. hdc 工具简介

hdc（HarmonyOS Device Connector）是鸿蒙生态提供的命令行调试工具，功能类似于 Android 开发中的 adb。它支持设备管理、应用安装、日志抓取、文件传输等常用调试能力。

hdc 远程连接的核心思路是：让开发机和目标设备处于同一网络，通过 TCP 端口建立连接，从而替代 USB 线缆完成调试。

3. 环境准备

在开始远程连接之前，需要完成以下准备工作：

• 开发机：安装 DevEco Studio，并确保 hdc 工具可用。
• 目标设备：鸿蒙手机或开发板，开启开发者模式和无线调试功能。
• 网络环境：开发机与设备连接到同一局域网，或确保网络互通。

3.1 确认 hdc 工具可用

在命令行中执行以下命令，确认 hdc 已正确安装：

hdc -v

如果输出版本号，说明 hdc 工具已就绪。若提示命令不存在，请检查 DevEco Studio 的 SDK 路径是否已加入系统环境变量。

3.2 开启设备无线调试

在鸿蒙设备上进入「设置」-「关于本机」，连续点击版本号开启开发者模式。随后进入「设置」-「开发者选项」，打开「无线调试」开关。

开启后，设备会显示一个调试端口号，例如 5555。请记录该端口，后续连接时需要用到。

3.3 或命令行开启鸿蒙设备无线调试

4. 远程连接步骤

完成环境准备后，按照以下步骤建立 hdc 远程连接。

4.1 查询设备 IP 地址

在设备上进入「设置」-「WLAN」，查看当前网络的 IP 地址，例如 192.168.1.100。也可以使用 hdc 命令查询：

hdc shell ifconfig

4.2 建立 TCP 连接

在开发机命令行中执行以下命令，将目标设备添加到 hdc 设备列表：

hdc tconn 192.168.1.100:5555

其中 192.168.1.100 是设备 IP，5555 是无线调试端口。连接成功后，执行以下命令确认设备状态：

hdc list targets

如果列表中显示目标设备，说明远程连接已建立。

4.3 断开连接

调试结束后，可以执行以下命令断开远程连接：

hdc tconn 192.168.1.100:5555 --remove

5. 远程调试常用命令

建立远程连接后，即可使用 hdc 的常用调试命令。

5.1 安装应用

hdc install /path/to/app.hap

5.2 启动应用

hdc shell aa start -a EntryAbility -b com.example.myapp

5.3 抓取日志

hdc hilog

5.4 文件传输

将开发机文件推送到设备：

hdc file send /local/file.txt /data/local/tmp/

将设备文件拉取到开发机：

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

6. 常见问题排查

远程连接过程中可能遇到一些问题，以下是常见场景及处理方法。

6.1 连接超时

如果执行 tconn 时提示超时，请依次检查：

• 设备与开发机是否在同一局域网。
• 无线调试端口是否正确。
• 设备是否处于休眠状态，可尝试点亮屏幕。

6.2 设备列表为空

执行 list targets 无输出时，可先执行 hdc kill 再重新执行 hdc tconn 建立连接。

6.3 端口被占用

如果提示端口冲突，可在开发者选项中修改无线调试端口，或重启设备后重试。

7. 总结

hdc 远程连接为鸿蒙开发提供了便捷的真机调试方式。掌握 tconn 连接、常用调试命令和问题排查方法，可以显著提升开发效率。建议在实际项目中多实践，逐步熟悉远程调试的完整流程。