HBuilderX真机运行前必须确保adb devices能识别设备，否则后续操作均无效；需检查USB模式、驱动、ADB版本及iOS证书等关键环节。
adb devices 不显示设备，说明底层连接已断
真机运行第一步不是点 HBuilderX 的“运行”，而是确认电脑能否通过 ADB 识别手机——这是所有后续操作的前提。如果 adb devices 命令回车后只显示空列表或 * daemon not running. starting it now on port 5037 *，那 HBuilderX 必然找不到设备。
- 先执行
adb kill-server && adb start-server，再跑adb devices；若仍无设备，说明 USB 通路没通 - 换原装数据线（很多“快充线”只通电不通数据），插主板后置 USB 口（避开 USB 扩展坞/键盘上的接口）
- 华为/荣耀/小米等国产机，插线后下拉通知栏，必须手动选“文件传输”或“MTP”，不能是“仅充电”或“USB 以太网”——哪怕你开了 USB 调试，选错模式照样不识别
- Windows 用户注意：部分新机型（如华为 Mate 60 系列、荣耀 Magic6）需安装官方手机助手（如“华为手机助手”），它会连带装好带签名的私有驱动；仅靠 Google USB Driver 无效
开发者选项里这几个开关漏一个，HBuilderX 就当没连
安卓 12+ 系统把关键配置藏得更深，光开“USB调试”远远不够。尤其荣耀、华为 EMUI/Magic UI、小米 HyperOS 等定制系统，常默认关闭 ADB 安装权限和调试授权弹窗。
- 必须开启：
USB调试、USB调试（安全设置）（部分华为机型叫“仅充电时允许ADB调试”） - 必须允许：
安装未知应用（路径通常是 设置 > 安全 > 更多安全设置 > 允许安装来自外部来源的应用） - 进阶检查：
默认USB配置设为MIDI或文件传输；某些荣耀机型需设为RNDIS（USB以太网）才能被 HBuilderX 的 adbs 工具识别 - 首次连接手机后，务必在弹出的“允许 USB 调试吗？”对话框中点“确定”，并勾选“始终允许”——否则拔插一次就得重点一遍
HBuilderX 自带的 adbs 工具太老，碰上新机型直接失灵
HBuilderX 4.71+ 版本虽支持无线调试，但其内置的 adbs 工具包（位于 HBuilderX\plugins\launcher-tools\tools\adbs\）长期未更新，对 Android 14/15 和麒麟 9010、天玑 9300 等新 SoC 兼容性差，表现为设备能被 adb devices 列出，但在 HBuilderX 运行菜单里始终灰色。
- 去官网下载最新版
platform-tools（地址：https://developer.android.com/tools/releases/platform-tools），解压后找到adb.exe、adbwinapi.dll、adbwinusbapi.dll - 备份原目录
HBuilderX\plugins\launcher-tools\tools\adbs\下这三个文件，再用新版替换 - 重启 HBuilderX（不是刷新，是彻底退出再打开），再点“运行到 Android App 基座”
- 若仍无效，可临时在项目根目录下建
adbs文件夹，把新版adb.exe放进去，HBuilderX 有时会优先读取项目级 adbs
iOS 设备连不上，大概率卡在证书或信任链上
自 2022 年 9 月起，uni-app 官方标准基座已停用企业证书，iOS 真机调试必须走个人/公司开发者账号签名流程。此时“检测不到设备”往往不是连接问题，而是 Xcode 没认出设备或证书没配对成功。
- 先确认 iTunes（Windows）或 Finder（macOS）能识别设备；若不能，重装 iTunes / 重启 Apple Mobile Device Service
- Mac 上打开 Xcode → Preferences → Accounts，添加你的 Apple ID，并下载所有 Provisioning Profiles
- 连接 iPhone 后，在 Xcode 的 Window → Devices and Simulators 中查看设备是否显示为“Ready”；若显示“Processing”，说明证书正在同步，需等待
- 确保
manifest.json中已写入"deviceType": "ios"，且 HBuilderX 运行时选择的是“运行到 iOS 设备”而非“运行到模拟器” - 每次重装调试基座前，手机需在“设置 > 通用 > 设备管理”里信任对应开发者证书——这个步骤容易被跳过，但缺了就装不上包
真正卡住人的，从来不是“没开开发者选项”这种基础项，而是 USB 配置模式选错、adbs 工具版本滞后、iOS 证书没在 Xcode 里激活这三类隐性断点。修完这些，设备名才会稳稳出现在 HBuilderX 的运行菜单里。
