🌌 原生鸿蒙 5+ · hdc 调试

原生鸿蒙（HarmonyOS 5+） · 连接中心

本板块只讲原生鸿蒙（HarmonyOS 5.0 / NEXT 及以上）：插线后弹「USB 连接方式」、查设备用 hdc list targets（无设备输出 [Empty]）。

HarmonyOS 4 及以下、EMUI、荣耀 MagicOS 均为安卓体系——请走 安卓 · adb 板块，不要使用本板块的 hdc 流程。

刚刚开始操作

从开启开发者模式到 hdc list targets 看到设备序列号，7 步走完（含无线连接与多设备），每步附意外情况处理。

开始分步引导 →

我碰到问题

hdc 显示 [Empty]、端口 8710 被占用、驱动异常（HDC Device 黄标）、无法传文件装 HAP、纯净模式拦截……按症状逐项排查。

进入问题排查 →
⚠️ 先确认系统归属：设置 → 关于本机 看到「HarmonyOS 5 / NEXT」才属于本板块。荣耀 MagicOS、华为 HarmonyOS 4 及以下、EMUI 都是安卓体系，调试用 adb（安卓板块）；所谓「荣耀/老机型刷鸿蒙」均为无官方支持的第三方刷机。
💡 原生鸿蒙与安卓的关键差异：① 查设备用 hdc list targets 而非 adb；② 不需要 Google USB 驱动——Windows 下设备管理器「通用串行总线设备」中应出现 HDC Device（单一端口）或 HDC Interface（复合端口）；③ USB 必须处于「传输文件 / 传输图片」模式（实机弹窗「USB 连接方式」），仅充电模式下无法开启 USB 调试。

常用命令速查

连接验证与问题定位的必备命令，点击「复制」即可粘贴使用。

📋 列出已连接设备

$ hdc list targets

正常输出设备序列号；无设备时输出 [Empty]。加 -v 可看连接类型与状态。

🌐 无线连接设备

$ hdc tconn 192.168.1.100:10123

需手机与电脑同网，且手机「无线调试」已打开（界面会显示 IP:端口）。断开加 -remove。

🎯 多设备时指定目标

$ hdc -t <connect-key> list targets

USB 设备 connect-key=序列号，无线=IP:端口；单设备可省略 -t。

♻️ 重启 hdc 服务端

$ hdc kill -r

排查掉线、状态异常时的“重启大法”，等效 kill 后自动 start。

📦 安装 HAP 应用包

$ hdc install -r your.hap

-r 覆盖安装；纯净模式开启时会报「安装被禁止」。

📂 推送 / 拉取文件

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

拉取用 hdc file recv 远端 本地。中文文件名乱码时先把 SDK 升级到 3.1.0a 以上。

🖥️ 进入设备 shell

$ hdc shell

进入后即可执行设备侧命令，exit 退出。

常见问题直达

也可进入完整问题清单查看全部。

手机没反应、不充电

插上数据线后手机毫无动静：不充电、不弹窗、通知栏也没有 USB 通知，资源管理器看不到设备。

链路物理层 · 最常见

开发者选项没出现 / USB 调试开关打不开

连点「软件版本号」没反应；或开发者选项已出现但「USB 调试」灰色、点了没反应。

手机端设置

提示「hdc 不是内部或外部命令」

终端里执行 hdc 报错：'hdc' 不是内部或外部命令 / command not found。

电脑端环境

hdc list targets 显示 [Empty]

命令能执行，但输出 [Empty]，电脑识别不到鸿蒙设备；或设备管理器里没有 HDC Device。

识别链路 · 核心排查

报错 hdc server port 8710 has been used

执行任何 hdc 命令都提示端口被占用 / server 起不来。

hdc 服务端

无法浏览 / 传输照片和文件

hdc 正常，但资源管理器看不到手机存储，或打开后目录为空、复制报错。

MTP / GUI 传输