大家好，我是不想掉发的鸿蒙开发工程师城中的雾。
在上一系列中，我们探讨了如何写出炫酷的 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]或报错。
- 正常：显示设备序列号（SN），如
常见问题排查
如果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 usb4. 多设备管理
当你同时连接了多台设备（比如一台真机、一台模拟器，或者一台手机、一台车机）时，执行命令必须指定目标，否则 HDC 不知道该听谁的。
指定设备执行命令：
hdc -t [设备SN或IP] [命令]- 示例：
hdc -t 192.168.1.100:5555 shell ls
- 示例：
5. 番外：一键无线连接脚本 (Windows)
每次都要手动敲三个命令（开端口、查IP、连接）是不是很累？我们可以写一个.bat脚本来自动完成这个过程。
懒人脚本 (connect_wifi.bat)
在桌面新建一个文本文件，粘贴以下代码，保存为.bat后缀。插上 USB 线，双击运行即可。
优化说明：此版本已移除所有中文字符和注释，排除编码错误，通过临时文件稳定获取 IP。
@echo off setlocal enabledelayedexpansion echo ========================================== echo HarmonyOS WiFi Connect Tool echo ========================================== echo [STEP 1] Setting TCP Mode 5555... hdc tmode port 5555 if %errorlevel% neq 0 goto ErrorUSB timeout /t 2 >nul echo. echo [STEP 2] Getting IP Address... set DEVICE_IP= hdc shell ifconfig wlan0 > ip_temp.txt for /f "tokens=2 delims=:" %%a in ('findstr "inet addr" ip_temp.txt') do ( for /f "tokens=1" %%b in ("%%a") do set DEVICE_IP=%%b ) if "!DEVICE_IP!"=="" ( for /f "tokens=2" %%a in ('findstr "inet " ip_temp.txt') do ( echo %%a | findstr /v ":" >nul && set DEVICE_IP=%%a ) ) del ip_temp.txt >nul 2>&1 if "!DEVICE_IP!"=="" goto ManualInput echo [INFO] IP Found: !DEVICE_IP! goto ConnectStep :ManualInput echo [WARN] Auto-detect failed. Check Settings-WLAN. set /p DEVICE_IP="Please Enter IP Address: " goto ConnectStep :ConnectStep echo. echo [STEP 3] Please unplug USB now. Press any key to connect... pause >nul if "!DEVICE_IP!"=="" goto ErrorIP echo Connecting to !DEVICE_IP!:5555 ... hdc tconn !DEVICE_IP!:5555 echo. echo [Result] Connected Devices: hdc list targets goto End :ErrorUSB echo [ERROR] Please connect USB first! pause goto End :ErrorIP echo [ERROR] IP is empty. pause goto End :End pause总结：HDC 连接速查表
| 场景 | 命令 | 说明 |
|---|---|---|
| 查设备 | hdc list targets | 也是检查连接状态的第一步 |
| 查版本 | hdc -v | 检查环境配置是否成功 |
| 重启服务 | hdc kill -r | 遇到莫名其妙连接问题时的万能药 |
| 开无线 | hdc tmode port 5555 | 需先插线设置 |
| 查IP | hdc shell ifconfig | 查找wlan0的inet addr |
| 连无线 | hdc tconn [IP]:5555 | 需在同一局域网 |
| 切回USB | hdc tmode usb | 恢复有线模式 |
连接设备是开发的第一步。搞定了连接，下一期我们将深入 App 的**“卸载与安装”，探讨如何通过命令行高效地安装、卸载、启动和强制停止**应用，甚至直接拉起指定的 Ability 页面进行测试。
充电时间
如果您想系统深入地学习 HarmonyOS 开发或想考取HarmonyOS认证证书，推荐学习华为官方课程：
🔗 HarmonyOS第一课：官方认证培训
)
