连不上真机主因是USB调试与文件传输模式未同时开启，或未配置自定义基座；调用plus.*、uni.getProvider等原生API时标准基座失效，必须制作并手动选择自定义基座，且需在manifest.json中启用"android": {"debug": true}。
连不上真机，八成不是 HBuilderX 的问题，而是 USB 调试 + 文件传输模式没同时开对，或者自定义基座根本没做——尤其用了 plus.*** 或 uni.getProvider 这类原生 API 时，标准基座直接不认。
adb devices 显示 unauthorized 或空列表
这是最常卡住的第一步。现象是 HBuilderX 列表里没设备、控制台报“找不到设备”、adb devices 输出 unauthorized 或干脆没反应。
- 手机端必须弹出“允许 USB 调试？”授权弹窗，并手动点“确定”——部分机型（如 MIUI 14、HarmonyOS 4）会默认拒绝，且不重复弹窗，得去「开发者选项」里手动关闭再重开“USB 调试”触发
- Windows 上驱动没装对：别信自动安装，直接用 HBuilderX 自带的 adb ——路径通常是
HBuilderX/plugins/launcher-tools/tools/adbs/adb.exe，在 HBuilderX 的「运行 → 运行到手机或模拟器 → ADB 路径设置」里填进去 - USB 线只充电不传数据：换原装线，或插到主板后置 USB 口（供电更稳），避开 USB 集线器
- 连接后下拉通知栏，必须选「文件传输」或「MTP」，选「仅充电」或「MIDI」
adb就完全失联
点了“运行到 Android App 基座”却安装失败或白屏
错误提示常是“解析包时出现问题”“签名冲突”“无法打开应用”，本质是基座不匹配或未启用调试能力。
- 只要项目里调用了
plus.bluetooth、uni.getLocation（非 H5 版）、uniPush等，就必须用自定义基座——标准基座里没这些模块，真机上直接静默失败 - 自定义基座制作前，必须准备好
.keystore文件：用 JDKkeytool生成，路径不能含中文或空格，别名和密码要记牢，后续云端打包全靠它 - 打包完自定义基座后，HBuilderX 不会自动切换；得手动点「运行 → 运行到手机或模拟器 → 运行到安卓 App 基座」，它才会拉取你刚打好的那个
- 如果之前装过旧版基座，先清理：执行
adb uninstall io.dcloud.HBuilder和adb uninstall io.dcloud.PandoraEntry
chrome://inspect 能看到设备但打不开调试页
界面灰掉、Network 空白、Sources 里没源码——说明 WebView 调试通道没真正打通。
- 自定义基座必须在 manifest.json 里显式开启调试：
"android": { "debug": true }，否则即使代码里写了debugger也没用 - 前端代码需主动启用调试逻辑：在
App.vue的onLaunch或main.js开头加判断，例如：if (process.env.UNI_PLATFORM === 'app-plus') { window.__VUE_DEVTOOLS_GLOBAL_HOOK__ = null; }（防某些插件干扰） - Chrome 版本太新（v128+）可能与旧版 WebView 内核不兼容，临时降级到 v126 或用 Edge（Chromium 内核）试试
- 确保手机没开“省电模式”或“后台限制”，否则 WebView 进程被杀，
chrome://inspect就断连
最容易被忽略的是：iOS 真机调试从 2022 年起已禁用标准基座，必须自己签名 IPA；而安卓端哪怕只是测个样式，只要用了原生能力，自定义基座就是硬门槛——不是“可选配置”，是运行前提。
