鸿蒙系统 hdc 环境配置详解（Windows + Linux 新手笔记）

~远在太平洋~

164人浏览 · 2026-08-11 20:17:20

~远在太平洋~ · 2026-08-11 20:17:20 发布

适用对象：刚装好鸿蒙开发环境、第一次用 hdc 的新人
文档定位：照着一步步配就能通 + 随时查的命令速查 + 踩坑记录
配套文档：wukong 测试指令详解（hdc 配好才能跑 wukong）

一、hdc 是什么（30 秒理解）

hdc（HarmonyOS Device Connector）是鸿蒙提供的设备连接/调试命令行工具，相当于 Android 的 adb。

通过 USB 或网络（TCP）连接真实设备 / 模拟器
能执行 shell 命令、传文件、装/卸应用、抓日志
wukong 测试、截图、日志分析全都建立在 hdc 能连上设备的前提上

一句话记忆法：hdc = 鸿蒙版 adb。adb 会，hdc 就会一半。

二、hdc 从哪来（工具获取）

hdc 不单独发，跟着 HarmonyOS SDK 走，放在 SDK 的 toolchains 目录里。

两种拿到方式（任选其一）：

方式	适用人群	说明
装 DevEco Studio	大多数人	IDE 自带 SDK，装完直接有 hdc
下载 Command Line Tools	只跑命令、不写代码；CI 服务器	华为官网下 `commandline-tools` 压缩包，解压即用

默认路径速查

系统	hdc 所在目录（示例）
Windows	`C:\Users\你的用户名\AppData\Local\HarmonyOS\Sdk\toolchains`
Linux	`~/HarmonyOS/Sdk/toolchains` 或 DevEco Studio 安装目录下的 `sdk/toolchains`
macOS	`~/Library/Huawei/sdk/toolchains` 或 `~/HarmonyOS/Sdk/toolchains`

找不到？在 DevEco Studio 里：File > Settings > SDK 能看到 SDK 实际安装路径，进去找 toolchains 目录即可。

三、Windows 配置步骤（一步一步来）

Step 1 找到 hdc.exe 路径

按上面的路径打开文件夹，确认里面有 hdc.exe。

Step 2 加进系统 PATH

此电脑 → 右键「属性」 → 高级系统设置 → 高级 → 环境变量
→ 在「系统变量」或「用户变量」里找 Path → 编辑 → 新建
→ 粘贴 toolchains 目录路径（如 C:\Users\xxx\AppData\Local\HarmonyOS\Sdk\toolchains）
→ 一路确定保存

Step 3 让配置生效

关掉所有命令行窗口重新打开（或用 DevEco Studio 的 Terminal）。这一步很多人忘，配完不生效多半是这个原因。

Step 4 验证

hdc -v

能打印版本号（如 Ver: 1.3.0a）即配置成功。

⚠️ Windows 驱动坑：设备管理器里若 HDC Device 出现黄色感叹号，说明驱动没装好。装 华为手机助手（HiSuite） 会自动带驱动，或手动更新驱动指向 HDC Device。

四、Linux 配置步骤（环境变量 + udev 权限）

Linux 比 Windows 多一步：USB 设备权限（udev 规则），否则非 root 下 hdc list targets 看不到设备。

Step 1 找到 hdc 路径并加执行权限

# 进入 toolchains 目录
cd ~/HarmonyOS/Sdk/toolchains

# 确认有 hdc，并赋予可执行权限（必须！）
chmod +x hdc

./hdc -v        # 能出版本号说明文件 OK

Step 2 加进 PATH（两种 shell 写法）

# Bash 用户（大多数）
echo 'export PATH=$PATH:~/HarmonyOS/Sdk/toolchains' >> ~/.bashrc
source ~/.bashrc

# Zsh 用户（macOS/部分 Linux）
echo 'export PATH=$PATH:~/HarmonyOS/Sdk/toolchains' >> ~/.zshrc
source ~/.zshrc

路径换成你实际的 toolchains 绝对路径（建议用绝对路径，不要写 ~ 展开可能出错）。

Step 3 配置 udev 规则（关键！解决非 root 看不到设备）

# 1. 先插上设备，看 USB 是否能识别到 HDC Device
lsusb
# 输出里找类似 "HDC Device" / "Phytium HDC Device" 的行，记下 Vendor ID（如 12d1）

# 2. 新建 udev 规则文件
sudo vim /etc/udev/rules.d/90-hdc.rules

文件内容（华为设备 VID 为 12d1；其它厂商先用 lsusb 查到 VID 再替换）：

# 让所有用户可读写 HDC 设备（新手最简方案）
SUBSYSTEM=="usb", ATTR{idVendor}=="12d1", MODE="0666"
# 若想用用户组方式（更规范），改为下面这行并把自己加入 plugdev 组：
# SUBSYSTEM=="usb", ATTR{idVendor}=="12d1", MODE="0666", GROUP="plugdev"

# 3. 重载规则并重新触发
sudo udevadm control --reload-rules
sudo udevadm trigger

# 4. 重新插拔 USB 线
# 5. 验证（无需 sudo）
hdc list targets

多渠道商设备 VID 不同，记不住就 lsusb 看一眼，把 12d1 换成你设备实际的 Vendor ID 即可。

Step 4 验证

hdc -v
hdc list targets

五、设备侧准备（两端都要做）

不管 Windows 还是 Linux，设备端不开调试，PC 怎么配都连不上：

打开「设置 → 关于本机 → 连续点版本号 7 次开启开发者模式
「设置 → 系统 → 开发者选项 → 开启 USB 调试」
用数据线连电脑，在设备弹窗里点「允许 USB 调试」（勾选"一律允许"更省事）
确认 USB 连接模式是「传输文件(MTP)」而非仅充电

六、连接设备 & 验证

# 查询已连接设备（返回 [empty] 就是没连上）
hdc list targets

# 打印详细信息（含 connect-key，多设备时用它区分）
hdc list targets -v

# 查看客户端与服务端版本是否匹配
hdc checkserver

连不上的通用救法：hdc kill -r 杀掉异常进程并重启服务，再 hdc list targets。

七、无线/网络调试（不用 USB 线）

适合设备 USB 口坏了、或要做长时间稳定性测试时不想被线绊住。

# 方式 A：设备已在「开发者选项 → 无线调试」里开了，直接连
hdc tconn 192.168.1.100:5555

# 方式 B：先通过 USB 打开设备网络通道，再拔线连
hdc tmode port 5555      # 设备端开启 TCP 监听（此命令后 USB 会断）
hdc tconn 192.168.1.100:5555

# 断开网络设备或恢复 USB
hdc tconn 192.168.1.100:5555 -remove
hdc tmode usb            # 恢复 USB 模式

网络调试要求 PC 与设备同一网段。hdc tconn 的端口默认和 OHOS_HDC_SERVER_PORT 不是一回事，别混。

八、常用命令速查表（配好就能干活）

类别	命令	说明
版本/连接	`hdc -v`	查看 hdc 版本
	`hdc list targets`	列出已连接设备
	`hdc list targets -v`	列出设备详情（含 connect-key）
	`hdc checkserver`	校验 client/server 版本
Shell	`hdc shell`	进入设备 shell（前面 wukong 就在这敲）
	`hdc shell <命令>`	单次执行，如 `hdc shell ps -ef`
文件	`hdc file send 本地远程`	本地→设备，如 `hdc file send ./a.txt /data/local/tmp/a.txt`
	`hdc file recv 远程本地`	设备→本地，如 `hdc file recv /data/local/tmp/a.txt ./a.txt`
应用	`hdc install xxx.hap`	安装应用（`-r` 覆盖，`-s` 替换）
	`hdc uninstall 包名`	卸载应用
日志	`hdc hilog`	实时打印设备日志（配合 `grep` 用）
服务	`hdc start -r`	启动/重启 hdc 服务
	`hdc kill -r`	终止/重启服务（连不上先试这个）
设备	`hdc target boot`	重启设备
多设备	`hdc -t <connect-key> shell`	指定某台设备执行命令

多设备场景一定加 -t connect-key，否则 hdc 不知道往哪台发命令。

九、关键环境变量（进阶但常用）

变量名	作用	默认值	怎么用
`OHOS_HDC_SERVER_PORT`	修改 hdc server 监听端口	`8710`	8710 被占用时改掉，如设 `18710`
`OHOS_HDC_LOG_LEVEL`	调整日志打印级别（排查用）	默认	设 `5` 开详细日志

Windows 设置：此电脑 → 属性 → 高级 → 环境变量 → 新建系统变量。
Linux/macOS 设置：

echo 'export OHOS_HDC_SERVER_PORT=18710' >> ~/.bashrc
echo 'export OHOS_HDC_LOG_LEVEL=5' >> ~/.bashrc
source ~/.bashrc

⚠️ 改完环境变量要重启命令行/DevEco Studio 才生效。命令行里用 -s ip:port 指定服务端口时会忽略这个环境变量。

十、⚠️ 新手必踩的 6 个坑

配完 PATH 不生效 → 八成是没重开命令行窗口。关掉重开。
Linux 非 root 看不到设备 → 没配 udev 规则或没 chmod +x hdc。按第四节 Step 1、3 走。
Windows 设备管理器 HDC Device 黄标 → 驱动没装。装 HiSuite 或手动更新驱动。
设备连上但 list targets 是 [empty] → 设备没开 USB 调试，或弹窗没点"允许"，或 USB 模式是"仅充电"。
多个 hdc 版本打架 → DevEco Studio 自带一个、自己又下了一个，PATH 指向混乱。确保 PATH 里只留一个 toolchains。
8710 端口被占 → 设 OHOS_HDC_SERVER_PORT 换个端口，重启命令行再试。

记忆口诀：连不上先 hdc kill -r，再看设备开没开调试，再看驱动/权限。

十一、标准作业流（SOP）

# 1. 设备开开发者模式 + USB 调试，连电脑，点允许
# 2. Windows / Linux 按上面配好 PATH（Linux 还要 chmod +x 和 udev）
# 3. 验证
hdc -v
hdc list targets          # 能看到设备序列号 = 成功

# 4. 进 shell 跑 wukong（接上一篇笔记）
hdc shell
wukong -v

十二、一句话速记卡（贴显示器上）

hdc = 鸿蒙版 adb
路径：SDK 的 toolchains 目录
Windows: 加 Path → 重开终端 → hdc -v
Linux:   chmod +x + 加 Path + udev(VID 12d1) + 重插拔
设备:    开发者模式 + USB调试 + 点允许 + 传输文件模式

hdc list targets        查设备
hdc shell               进设备
hdc tconn IP:端口       无线连
hdc kill -r             连不上先重启服务
OHOS_HDC_SERVER_PORT    默认 8710，冲突就改