白屏主因是onLaunch中异步未await或首页资源未加载：uni.xxx方法必须await；避免同步耗时操作；pages.json路径与style格式须严格正确；manifest/vue.config.js生产路径应设为'./'；分包需三处配置对齐；iOS/WKWebView和鸿蒙别名兼容需特别处理。
白屏加载慢不是渲染卡顿，而是 js 主线程在 onlaunch 就被堵死，或首页资源压根没加载进来——真机上常静默失败，控制台不报错。
onLaunch 里异步调用没 await 就执行
这是最常见、最隐蔽的白屏原因。比如写了 uni.getStorage({ key: 'token' }) 却没加 await，Promise 立刻返回 pending，后续逻辑继续跑，但实际数据没回来；更糟的是，如果后面跟着 JSON.parse(大字符串) 这类同步操作，整个挂载流程就卡死。
- 所有
uni.xxx异步方法（getStorage、getSystemInfo、request等）在onLaunch中必须await，不能只写调用语句 - 避免同步耗时操作：解析 MB 级 JSON、正则全局匹配长文本、遍历万级数组
- 实在要处理本地缓存大对象，改用
setTimeout(() => { /* 处理逻辑 */ }, 0)或uni.nextTick让出主线程 - 在
onLaunch开头加console.log('onLaunch start')——如果这行都没输出，说明问题在更早阶段（比如main.jsimport 报错或 store 循环依赖）
pages.json 首页路径或 style 格式错误
小程序和 App 端对 pages.json 的容错极低，错一个字符就白屏，且控制台不抛异常。
-
"list"数组第一项的"path"必须指向真实存在的 Vue 文件，例如"pages/index/index"对应src/pages/index/index.vue，大小写、斜杠方向、文件后缀都需严格一致 -
"style"字段必须是合法 JSON 对象，不能留空、不能是字符串""、不能拼错字段名（如写成nvaigationBarTitleText），至少写成{"navigationBarTitleText": "首页"} - H5 端可手动访问
/pages/index/index.html测试该页面能否独立打开；404 就说明构建没包含它 - TabBar 页面必须在
pages数组中，不能只放在subPackages里，否则小程序启动失败
manifest.json 和 publicPath 生产环境配置错位
开发时走 HBuilderX 内置基座一切正常，一打包就白屏？大概率是 manifest.json 或 vue.config.js 里的路径配置和生产环境不匹配，JS/CSS 加载失败，WebView 不报错，只留白屏。
-
manifest.json中"h5":{"router":{"base":"./"}}必须设为相对路径，部署到子目录时才不会 404 -
vue.config.js中publicPath生产环境务必设为'./'，写成'/'或'https://cdn.com'但没配 CDN，会导致app-service.js加载失败 -
manifest.json的"app-plus"节点下，启动图路径必须是绝对路径且文件真实存在于unpackage/dist/build/app-plus/static/，例如"image": "/static/splash.png" - 删掉
unpackage和node_modules，重装依赖再打包——HBuilderX 4.66.2025051912 及之后版本有已知缓存 bug，旧版基座残留会导致白屏
分包预加载没生效却以为配好了
分包不是“配了就快”，preloadRule 静默失效往往是因为三处没对齐：manifest 开关、pages.json 路径、preloadRule 的 root 值。
- 必须在
manifest.json对应平台节点（如mp-weixin或app-plus）下开启"optimization": {"subPackages": true}，否则preloadRule完全不触发 -
preloadRule的key必须是pages.json中pages或subPackages里出现的**完整路径字符串**（不含开头斜杠，带后缀），例如"pages/product/detail"，不能写成"product/detail"或"pages/product" -
packages数组里的值，必须和subPackages中的root字段**完全一致**，比如{"root": "subpkg/user", "pages": []}→packages: ["subpkg/user"]，不能简写为"user" - 真机调试时，在开发者工具「网络」面板搜索
preloading或downloadSubNVue，确认是否真正发起请求
最容易被忽略的其实是 iOS WKWebView 初始化延迟和鸿蒙平台对路径别名的不支持——前者会让首页组件在 WebView 还没 ready 时就开始 render，后者会让 @/ 别名直接失效，导致资源 404 白屏。
