manifest.json 中 SDK 版本不匹配、uni-app 编译插件失效、Vue 版本跃迁及真机调试授权未完成是 HBuilderX 升级后四大典型问题，需分别更新 sdkVersion、重装插件、配置 vueVersion 和确认 USB 调试授权。
manifest.json 中的 SDK 版本不匹配导致启动失败
新版 HBuilderX 默认使用更高版本的 5+ Runtime，但旧项目 manifest.json 里写的仍是低版本 SDK，运行时会拒绝加载，表现为你点击「运行」后控制台静默、模拟器无反应、真机白屏。
检查 manifest.json 里的 "sdkVersion" 字段，对比当前 HBuilderX 的内置 SDK 版本（可在「帮助 → 关于」里看到，如 4.87 对应 sdkVersion: "4.8.7"）。若字段缺失或数值明显偏低（比如写的是 "3.2.0"），必须手动更新。
- 不要直接填 HBuilderX 版本号，要填其对应的 SDK 版本号（查 DCloud 官网或 release note）
- 若项目依赖了旧版原生插件（如自定义地图、扫码模块），升级 SDK 后可能报
"找不到模块"，需同步更新插件源码或联系插件作者 - 修改后务必清理缓存：菜单 → 运行 → 清理缓存，再删掉
unpackage/目录
uni-app 编译插件失效引发 cannot find module 'open'
这个错误不是项目代码问题，而是 HBuilderX 更新后，内置的 uni-app 编译插件未自动适配新环境，尤其常见于微信小程序模拟器启动阶段。它和 node_modules 无关，重装依赖没用。
解决路径非常明确：打开「工具 → 插件安装」，找到 uni-app 编译 插件，先卸载，再重新安装。部分用户反馈仅「修复」按钮无效，必须走完整卸载+重装流程。
HBuilderX 是由 DCloud 推出的一款轻量级前端开发工具，在 Linux 系统上主要用于 Web 开发与跨平台应用开发，尤其适合 Vue 和 uni-app 相关项目。
- 如果插件列表里看不到
uni-app 编译，说明插件市场索引异常，可尝试重启 HBuilderX 或切换网络环境后再进插件管理 - 该插件在 HBuilderX 4.8+ 中已拆分为多个子模块（如
uni-app-debugger），若同时报uniapp-debugger 不兼容，需一并重装 - Windows 用户注意：若之前手动设置过 adb 路径（设置 → 运行设置 → adb路径），建议临时清空该字段再试
vue 版本跃迁引发生命周期钩子失效或样式错乱
HBuilderX 4.0+ 默认启用 Vue 3 组合式 API 编译模式，而老项目多基于 Vue 2 选项式 API。此时即使代码没改，也会出现 onLoad 不触发、rpx 计算异常、flex 布局塌陷等现象。
关键判断依据是 vue.config.js 或 manifest.json 中是否声明了 "vueVersion": "3"。若没声明，HBuilderX 会按自身默认策略处理，但旧项目往往没做兼容兜底。
- 最稳妥做法：在
manifest.json根级加字段"vueVersion": "2"，强制降级编译 - 若项目已用 Composition API，需确认
@dcloudio/uni-app依赖版本 ≥3.0.0，否则setup()会被忽略 - 注意
node_modules中的vue包版本必须与vueVersion设置一致，否则构建时 webpack 报module not found
真机调试卡在 Waiting For Debugger
这不是代码问题，而是 HBuilderX 和手机端调试桥接失败。新版（尤其是 4.87+）对 Android 14 及 vivo/华为等厂商定制系统适配尚不完善，表现为手机弹不出授权框、IDE 端一直显示等待状态。
优先检查手机端操作：进入「开发者选项」→ 打开「USB调试」→ 确保「USB调试（安全设置）」也开启 → 首次连接电脑时，务必点允许「HBuilderX 调试授权」弹窗。很多问题其实卡在这一步。
- 授权弹窗只在首次连接或更换 USB 线时出现，若跳过则后续始终卡住
- 若已连上但没弹窗，拔掉 USB 线，关闭 HBuilderX，再重连并重启 IDE
- 无线调试失败时，不要依赖自动发现，手动输入手机 IP + 端口（默认 30002）更可靠
plus.device.getInfo is not a function 又卡调试，大概率是 SDK 版本 mismatch + 真机授权未完成双重叠加。别急着回退版本，先逐项验证这些具体环节——多数时候，问题就藏在 manifest 配置、插件状态或手机那一下没点的授权里。 
