最常见原因是onLaunch中未await异步API或执行同步耗时操作导致JS主线程阻塞；需确保所有uni.xxx异步调用加await，禁用JSON.parse大字符串、正则长文本等同步操作，并检查pages.json首页路径、style合法性及manifest.json资源路径配置。
onLaunch 里没 await 就调用异步 API，页面直接卡死
白屏最常见原因不是渲染失败，而是 App.vue 的 onLaunch 函数把 JS 主线程堵死了。比如写了 uni.getStorage({ key: 'token' }) 却没加 await，这个 Promise 会立刻返回一个 pending 状态的值，后续逻辑继续往下跑，但实际数据还没回来——更糟的是，如果后面跟着同步耗时操作（如 JSON.parse 大字符串），整个挂载流程就停在那儿了。
- 所有
uni.xxx异步方法（getStorage、getSystemInfo、request等）在onLaunch中必须await，不能只写调用语句 - 避免在
onLaunch中做任何同步耗时操作：解析 MB 级 JSON、正则全局匹配长文本、遍历万级数组 - 实在要处理本地缓存大对象，改用
setTimeout(() => { /* 处理逻辑 */ }, 0)或uni.nextTick让出主线程 - 加一句
console.log('onLaunch start')在函数开头——如果这行都没输出，说明问题在更早阶段（比如main.jsimport 报错或 store 循环依赖）
pages.json 首页路径错、style 不合法，小程序端静默白屏
小程序平台对 pages.json 格式极其敏感，首页配置错一个字符就白屏，而且控制台不报错。H5 端可能还能勉强加载，但小程序真机上就是纯白。
-
"list"数组第一项的"path"必须指向真实存在的 Vue 文件，例如"pages/index/index"对应src/pages/index/index.vue -
"style"字段必须是合法 JSON 对象，哪怕空也要写成{"navigationBarTitleText": ""}，不能留空、不能是字符串""、不能拼错字段名（如写成nvaigationBarTitleText） - H5 端可手动访问
/pages/index/index.html测试该页面能否独立打开；404 就说明构建没包含它 - 检查是否误删了
"subPackages"或"preloadRule"导致分包路径未注册，首页组件内部引用的子组件因此加载失败
manifest.json 和 publicPath 配置错，打包后资源全 404
开发时走 HBuilderX 内置基座一切正常，一打包就白屏？大概率是 manifest.json 或 vue.config.js 里的路径配置和生产环境不匹配，JS/CSS 加载失败，WebView 不报错，只留白屏。
-
manifest.json中"h5":{"router":{"base":"./"}}必须设为相对路径，部署到子目录时才不会 404 -
vue.config.js中publicPath生产环境务必设为'./'，写成'/'或'https://cdn.com'但没配 CDN 就会导致资源路径错乱 -
app-plus分包资源路径必须是绝对路径，例如"splashscreen": {"image": "/static/splash.png"}，且文件必须真实存在于unpackage/dist/build/app-plus/static/ - 遇到打包白屏，先删掉
unpackage和node_modules，重装依赖再打包——HBuilderX 4.66.2025051912+ 版本有缓存 bug，仅清缓存不够
iOS 真机首次启动白屏，WKWebView 初始化延迟没兜住
iOS 的 WKWebView 启动 JS 引擎比 Android 慢得多，尤其冷启动时，Vue 实例可能已经尝试 render，但 WebView 还没 ready，结果 DOM 为空。
- 在
App.vue的onLaunch中加 iOS 兜底刷新：if (uni.getSystemInfoSync().platform === 'ios') setTimeout(() => location.reload(), 800) - 首页组件必须极简：不
import图表库、不发多个并发请求、不使用require('@/components/Heavy.vue')动态引入大型组件 - 启用原生启动页过渡：
manifest.json中配置"app-plus":{"splashscreen":{"autoclose":false,"delay":2000}}，避免用户看到白屏 - 不要在
onLaunch中调用uni.showLoading—— 此时页面树未挂载，会报Cannot read property 'showLoading' of undefined并中断流程
白屏问题的复杂点在于：它常常没有错误堆栈，也不触发 Vue 渲染钩子，甚至控制台一片空白。真正卡住的位置，往往在 Vue 实例挂载之前——所以排查必须从 App.vue 最顶上的 onLaunch 开始，一行行确认执行流有没有被同步阻塞、有没有 promise 漏 await、有没有路径或配置错位。这些地方一旦出问题，后续所有优化都无从谈起。
