hbuilderx运行项目到浏览器，项目白屏无法打开，运行到自定义基座正常

欢迎到专业群（ uni-app 官方技术交流群 1 ） 咨询，群中有相关专业的管理员和群友。

在 uni-app 开发中，项目在 App 端（自定义基座）运行正常，但运行到 Web/H5 浏览器出现白屏，通常是因为代码中存在 App 端特有 API、原生依赖或 Web 端特有的配置问题阻断了 Vue 实例的挂载。

可以按照以下步骤进行排查与解决：

1. 查看浏览器控制台报错（最关键的一步）
   在出现白屏的浏览器页面中按下 F12（或右键点击“检查”），切换到 Console（控制台） 和 Network（网络） 面板：

   • Console 面板：查看是否有红色报错（如 ReferenceError: plus is not defined、xxx is not defined、语法错误等）。一旦生命周期或全局初始化脚本中报错未捕获，会导致整个页面渲染中断而白屏。
   • Network 面板：查看是否有 js、css 或其他静态资源请求出现 404、跨域或加载失败的情况。

2. 检查是否直接调用了 App 端专有 API 或 5+ API
   在 App 端正常运行但在 Web 端报错，最常见的原因是在 App.vue、main.js 或首屏页面中直接调用了 HTML5+ 的 plus 对象、原生的原生插件方法或 App 专有能力。

   • 排查方法：检查全局及首屏代码中是否有 plus. 或原生插件调用。
   • 解决方案：使用条件编译将平台专有代码包裹起来，避免在 Web 端执行：

     
     // #ifdef APP-PLUS  
     // 仅在 App 端执行的代码  
     plus.screen.lockOrientation('portrait-primary');  
     // #endif  

// #ifdef H5
// 仅在 H5/Web 端执行的代码
// #endif

> **本助手使用国产模型，生成代码可能不准确。专业的代码生成需要全球顶尖的AI Coding模型。推荐使用[uni-agent](https://uniapp.dcloud.net.cn/ai/)**  

3. **检查引入的第三方 SDK 或插件**  
部分第三方 SDK（如某些硬件通讯插件、原生扫码 SDK 等）仅支持 App 端，无法在 Web 端直接运行或打包。  
- **排查方法**：检查是否有在 `main.js` 或组件中直接 `import` 了仅支持 App 的原生插件或库。  
- **解决方案**：通过条件编译进行区分引入，或者对 Web 端做降级兼容处理。  

4. **检查 manifest.json 的 Web 端配置**  
在项目的 `manifest.json` -> **Web 配置（H5 配置）** 中检查：  
- **路由模式**：若配置了 `history` 模式，请确认本地开发服务器的 base 路径与访问路径是否一致；建议本地排查时先切换为 `hash` 模式测试。  
- **运行的基础路径**：确保 `publicPath` 或基础路径设置正确（默认通常为 `./` 或 `/`）。  

5. **清理编译缓存**  
有时 HBuilderX 的 Web 端临时编译缓存异常也可能导致白屏：  
- 停止当前的运行任务。  
- 删除项目根目录下的 `unpackage/dist/dev/h5`（或 cli 项目的 `dist` 目录）。  
- 重新点击 HBuilderX 菜单的“运行” -> “运行到浏览器”。