App启动白屏主因是onLaunch中漏await、pages.json路径或格式错误、manifest.json和publicPath配置不当、鸿蒙平台资源路径及API兼容问题。
App启动白屏时间长，本质不是“页面没出来”，而是 JS 初始化卡在 onLaunch、资源加载失败或 WebView 渲染管线被阻塞。直接优化 splash 图片或加 loading 动画治标不治本。
onLaunch 里异步调用没 await 就返回
这是最常见也最隐蔽的白屏原因：JS 线程卡住，Vue 实例压根没挂载，控制台甚至不报错。
-
uni.getStorage({ key: 'token' })必须写成await uni.getStorage({ key: 'token' })，漏掉await会导致 Promise 被丢弃，后续逻辑跳过，页面停在空白状态 - 避免在
onLaunch中调用uni.getSystemInfoSync()后立刻访问res.model—— iOS 16+ 已改用res.deviceModel，字段不存在会静默undefined，后续逻辑崩断 - 同步操作如
JSON.parse(大字符串)、正则匹配超长文本、遍历万级数组，必须拆解或移到nextTick/setTimeout(() => {}, 0)中执行
pages.json 首页路径或 style 格式错误
小程序和 App 端对 pages.json 的容错极低，错一个字符就白屏，且无控制台提示。
- 确认
"list"数组第一项的"path"值真实存在，比如"pages/index/index"对应src/pages/index/index.vue，大小写、斜杠方向、文件后缀都需严格一致 -
"style"字段必须是合法 JSON 对象，禁止写成"style": ""或"style": {}（空对象在部分平台不认），至少写"style": {"navigationBarTitleText": "首页"} - H5 端可手动访问
/pages/index/index.html测试是否 404；App 端建议在app.vue的onLaunch开头加console.log('onLaunch start')，若这句都不输出，说明问题在更早阶段（如main.jsimport 失败或 store 循环依赖）
manifest.json 和 publicPath 配置错位
开发时跑得通，打包后白屏？90% 是环境路径配置没切到生产模式。
-
manifest.json中"h5":{"router":{"base":"./"}}必须存在，尤其部署到子目录时，否则路由跳转 404 -
vue.config.js若存在，publicPath在生产环境必须设为'./'，设成'/'或'https://xxx.com'会导致app-service.js加载失败，WebView 静默白屏 -
manifest.json的"app-plus"下，启动图路径必须是绝对路径且文件真实存在于unpackage/dist/build/app-plus/static/，例如"image": "/static/splash.png"
鸿蒙平台特有的资源与 API 兼容问题
编译成鸿蒙 App 后白屏，大概率不是逻辑问题，而是运行时能力缺失或路径解析异常。
- 静态资源路径必须用相对路径，如
"icon": "./static/icon.png"，鸿蒙不支持@/别名或绝对路径别名 - 禁用所有浏览器专属 API：
document、window.location、localStorage—— 这些在鸿蒙 WebView 中未实现，调用即静默失败 - 第三方库如
vue-i18n或自定义store若存在循环依赖（如store/index.js→config/index.js→store/index.js），鸿蒙会直接卡死在初始化阶段，表现为无日志、无报错、纯白屏
真正卡住启动的，往往不是你看到的「loading 时间长」，而是某一行没 await 的 uni.getStorage、一个拼错的 pages.json 路径、或 vue.config.js 里漏掉的 publicPath: './'。这些问题在 H5 上可能侥幸跑通，但一上真机或鸿蒙就原形毕露——因为不同平台的错误容忍度天差地别。
