微信开发者工具未启用调试模式是白屏主因，需手动打开“调试器”面板并确认服务端口开启；同时检查app.json pages路径、@别名配置及cli.bat路径是否正确。
控制台报错没显示？先确认微信开发者工具是否真在调试模式
白屏时控制台一片空白，不等于没错误——很可能是微信开发者工具根本没启用调试通道。HBuilderX 启动后，必须手动在微信开发者工具里打开“调试器”面板（不是“模拟器”或“编辑器”），否则 console.log 和 JS 错误都不会输出。
常见错觉：看到“编译成功”就以为没问题，其实 JS 解析失败发生在页面加载前，连 App.onLaunch 都没执行，自然不会触发任何日志。此时控制台干净得像没写过代码。
- 打开微信开发者工具 → 顶部菜单栏“调试器” → 切换到
Console标签页 - 刷新页面（
Ctrl+R或点击模拟器右上角刷新按钮），再看是否有Uncaught SyntaxError、ReferenceError或Cannot read property 'xxx' of undefined - 如果仍为空，检查微信开发者工具右上角“设置”→“安全”→确认已勾选“开启服务端口”，否则 HBuilderX 无法注入调试脚本
pages 字段路径错误导致首页不加载
白屏最常卡在 app.json 的 pages 数组第一项。微信小程序启动时会按顺序加载该数组首个路径对应的页面，如果路径不存在、拼写错误或大小写不符，就直接渲染空容器。
uni-app 项目中尤其容易出问题：HBuilderX 默认生成的页面路径是 pages/index/index，但如果你手动改过文件夹名（比如把 index 改成 home），却忘了同步更新 app.json，就会白屏。
- 检查
app.json中pages第一项是否真实存在，路径末尾不带.vue或.js，只写目录名 - 确认路径分隔符是
/（不是\），且所有字母大小写与磁盘文件完全一致（macOS/Linux 下Pages≠pages） - 如果用了分包，主包的
pages必须包含至少一个页面，不能全为空数组或只写分包路径
@/ 别名失效引发组件加载失败
白屏伴随 Module not found: Can't resolve '@/components/xxx' 报错，说明 import 语句根本没解析成功。uni-app 的 @ 别名依赖 jsconfig.json 或 tsconfig.json 配置，HBuilderX 不会自动补全或提示配置缺失。
HBuilderX 是由 DCloud 推出的一款轻量级前端开发工具，在 Linux 系统上主要用于 Web 开发与跨平台应用开发，尤其适合 Vue 和 uni-app 相关项目。
这个错误不会中断编译，但会导致页面 export default 为 undefined，最终渲染空节点。
- 根目录下必须有
jsconfig.json，内容至少包含：{ "compilerOptions": { "baseUrl": ".", "paths": { "@/*": ["src/*"] } } } - 确保
src目录真实存在，且@/components/xxx对应的文件路径在磁盘中准确匹配（例如src/components/Button.vue） - 修改配置后需重启 HBuilderX，否则缓存的别名映射不会更新
cli.bat 路径填错导致启动假成功
HBuilderX 显示“正在启动微信开发者工具”，但模拟器窗口空白、控制台无响应——大概率是路径指向了安装目录而非可执行入口。Windows 下新版微信开发者工具启动逻辑已从 wechatdevtools.exe 切换到 cli.bat，填错路径会让 HBuilderX 认为启动成功，实则什么都没干。
路径错误不会报错，只会静默失败，这是最隐蔽的白屏诱因之一。
- Windows 正确路径示例：
C:\Program Files (x86)\Tencent\微信开发者工具\cli.bat - macOS 正确路径示例：
/Applications/wechatwebdevtools.app（注意是 .app 包路径，不是内部可执行文件） - 路径中不能含中文、空格或括号，建议重装到
D:\WeChatDevTools这类纯英文路径
白屏问题往往不是单点故障，而是路径、配置、语法、调试通道四者中任意一环断裂。最容易被跳过的动作是：没开调试器就看控制台、没查 app.json 就重装工具、没验证 @ 别名就改组件引入方式。动手前，先盯住那行红色报错——它比任何经验都准。
