app.vue的onlaunch卡死导致白屏，本质是vue实例未挂载；常见原因包括未await异步调用、同步阻塞操作、h5专属api误用、字段访问错误、manifest.json路径配置错误、pages.json首页路径或style非法、缓存bug及ios wkwebview兼容问题。
App.vue 的 onLaunch 卡死导致白屏
白屏根本不是“页面没画出来”，而是 Vue 实例压根没挂载——onLaunch 里一阻塞，JS 线程就停住，后续所有逻辑（包括路由初始化、组件渲染）全被拦在门外。
常见错误现象：真机调试时 console.log('onLaunch start') 这句都不输出；或者只输出了开头，后续无响应。
- 检查是否写了未
await的异步调用，比如uni.getStorage({ key: 'token' })必须写成await uni.getStorage({ key: 'token' }) - 避免同步解析大 JSON、遍历万级数组、正则匹配长文本等耗时操作；可改用
setTimeout(() => { /* logic */ }, 0)让出主线程 - 禁止在
onLaunch中直接调用 H5 专属 API，如window.location、document.cookie—— App 端静默失败，不报错也不继续 - 调用
uni.getSystemInfoSync()后，别硬取旧字段，比如res.model（iOS 16+ 已改为res.deviceModel），取不到会返回undefined，后续链式访问直接报错中断
manifest.json 路径与 splashscreen 配置错误
打包后白屏但自定义基座正常？大概率是资源路径错位。HBuilderX 开发时走内置 WebView，打包后走原生 WebView，publicPath 和启动图路径必须严格匹配产物结构。
关键配置点：
-
manifest.json中"app-plus": { "splashscreen": { "image": "/static/splash.png" } }—— 路径必须是绝对路径，且文件真实存在于unpackage/dist/build/app-plus/static/目录下 -
vue.config.js中生产环境的publicPath必须设为'./'，否则 JS/CSS 加载 404，WebView 不抛错误，只留白屏 -
"alwaysShowBeforeRender": true能防闪屏，但会延长启动页时间；若首页渲染慢，建议配合"delay": 2000手动控制关闭时机 - Android 推荐用
.9.png，iOS 必须用 Storyboard（不能只放 PNG）；两者路径、格式、适配方式完全不同，不能混用
pages.json 首页配置失效引发白屏
白屏却无任何控制台报错？很可能是 pages.json 的 "list" 第一项指向了不存在的页面路径，或 "style" 字段语法非法，导致路由系统无法初始化。
验证方法：H5 端手动访问 /pages/index/index.html，404 就说明构建没包含该页面。
- 确认
"list"第一项的"path"值存在对应目录，大小写必须完全一致，例如"pages/index/index"对应pages/index/index.vue -
"style"字段必须是合法 JSON 对象，哪怕空也要写成{"navigationBarTitleText": "首页"}，不能是空字符串或null - 删掉
unpackage和node_modules，重装依赖再打包——HBuilderX 4.66.2025051912 及之后版本有缓存 bug，仅清缓存不够
iOS 平台特有的 WKWebView 兼容问题
iOS 白屏常伴随「首屏渲染完才闪一下」或「冷启动必白、热启动正常」，多因 WKWebView 初始化延迟或脚本执行时机异常。
这不是代码写错了，而是平台机制差异带来的执行不确定性。
- 可在
App.vue的onLaunch中加兜底逻辑：if (uni.getSystemInfoSync().platform === 'ios') { setTimeout(() => location.reload(), 300) } - 禁用原生混淆：HBuilderX 4.81 曾因勾选「对 js/nvue 文件进行原生混淆」导致白屏，虽 4.86+ 已修复，但 4.87 版本仍建议打包前取消该选项
- 解压
.ipa文件，检查Payload/xxx.app/www/下是否存在index.html和static/，缺失说明构建流程异常，需回查vue.config.js或manifest.json中的h5配置是否干扰了 App 构建
最易被忽略的是：启动页关闭时机和首页渲染完成之间没有强同步信号。即使 alwaysShowBeforeRender: true，若首页 data 初始化含 undefined 字段，或异步赋值用了非响应式写法（如直接 this.newField = xxx），视图就不更新，看起来还是白屏——此时控制台安静得可怕。
