白屏主因是JS执行链断裂，尤其App.vue的onLaunch卡死、环境配置错误或模块循环依赖。需检查同步阻塞、API兼容性、manifest.json/publicPath配置、iOS WKWebView延迟及store循环依赖等问题。
控制台没报错但页面白屏？先看 App.vue 的 onLaunch 是否卡死
很多白屏根本不是渲染失败，而是 js 执行在启动阶段就挂了——尤其在 onlaunch 里做同步阻塞、未 catch 的 promise、或调用了只在 h5 存在的 api（比如 window.location），app 端会静默失败，连 vue 实例都未成功挂载。
- 检查
App.vue的onLaunch中是否直接调用uni.getSystemInfoSync()后又立刻访问不存在字段（如旧版写法res.model，iOS 16+ 返回的是res.deviceModel） - 避免在
onLaunch中同步读取uni.getStorageSync后立即处理复杂逻辑；改用setTimeout(() => { ... }, 0)或nextTick让事件循环喘口气 - 真机调试时，在
onLaunch开头加一句console.log('onLaunch start')，如果这句都没输出，说明问题出在更早：比如main.js里 import 失败、store 循环依赖、或vue.config.js错误导致打包产物缺失入口 JS
打包后白屏但自定义基座正常？重点查 manifest.json 和 publicPath
这是最典型的“环境错位”：开发时走 HBuilderX 内置基座，一切 OK；但正式打包（npm run build:app-plus）后，资源路径、路由 base、甚至原生能力初始化方式全变了。
-
manifest.json中必须确认："app-plus": { "splashscreen": { "autoclose": true, "image": "/static/splash.png" } }—— 图片路径必须是绝对路径且文件真实存在于unpackage/dist/build/app-plus/static/ -
vue.config.js若存在，务必检查publicPath：生产环境应设为'./'，否则 JS/CSS 加载 404，白屏无任何控制台提示（WebView 不报 404 错误） - 删掉
unpackage和node_modules，重装依赖再打包——HBuilderX 4.66.2025051912 及之后版本有已知缓存 bug，旧版基座残留会导致白屏，仅清缓存不够，必须重装
iOS 真机首次安装白屏？WKWebView 初始化延迟是主因
iOS 的 WKWebView 加载 JS 引擎比 Android 的 X5 或系统 WebView 慢得多，尤其首次冷启动。如果首页依赖大量异步数据或字体加载，WebView 还没 ready，Vue 就开始 render，结果 DOM 空白。
- 在
App.vue的onLaunch中加兜底刷新：if (uni.getSystemInfoSync().platform === 'ios') setTimeout(() => location.reload(), 800) - 确保
pages.json第一个页面（首页）组件极简：不 import 大型图表库、不发多个并发请求、不使用require('@/components/Heavy.vue')动态引入 - 验证打包产物完整性：把
.ipa改后缀为.zip解压，进入Payload/xxx.app/www/，确认存在index.html、static/、js/三个目录；缺任何一个，就是构建流程被自定义配置打断了
Android 白屏但 Logcat 显示 “Uncaught TypeError: Cannot read property 'dispatch' of undefined”？查循环依赖
这类错误不会出现在浏览器控制台，只在 Android Studio 的 Logcat 或 adb logcat | grep -i js 里暴露。本质是模块加载顺序错乱，常见于 store 和 config 文件互相 import。
- 典型场景：
config/index.jsimportstore来读取用户语言设置，而store/index.js又 importconfig来读取 API 域名——打包时二者相互等待，最终store是空对象 - 快速验证：在
main.js最顶部加console.log('store:', require('./store'))，如果输出{}或undefined，基本锁定循环依赖 - 解法不是删代码，而是拆离共享常量：把 API 地址、默认语言等抽到
constants/config.js，让 store 和 config 都只 import 它，不再互引
