onLaunch卡死是白屏最常见原因：JS线程启动阶段挂起，Vue实例未挂载；典型表现为控制台仅显示“应用已启动”且无后续日志或报错，iOS尤为明显。
onLaunch卡死是白屏最常见原因
真机白屏，八成不是页面没渲染出来，而是App.vue的onLaunch根本没执行完——JS线程在启动阶段就挂了，Vue实例压根没挂载，自然什么也看不到。
典型表现：HBuilderX控制台只打印“应用已启动”，之后再无任何日志，也没报错；iOS尤其明显，连console.log('start')都出不来。
- 检查
onLaunch里是否调用了uni.getSystemInfoSync()后直接访问res.model（iOS 16+已改为res.deviceModel，取不到就undefined，后续链式调用崩） - 避免在
onLaunch中同步读uni.getStorageSync()后立刻做复杂计算或循环，改用setTimeout(() => {}, 0)或nextTick让事件循环喘口气 - 删掉
unpackage和node_modules，重装依赖再打包——HBuilderX 4.66.2025051912+有缓存bug，旧基座残留会导致白屏，光清缓存不够
publicPath配置错误导致JS/CSS加载404
开发时跑得好好的，一打包到App就白屏？大概率是vue.config.js里的publicPath写错了。生产环境必须设为'./'，否则资源路径全错，WebView静默失败，不报404也不打错，就干等白屏。
- 确认
vue.config.js中publicPath在process.env.NODE_ENV === 'production'下为'./'，不是'/'或'/static/' - 如果用了
manifest.json里的h5.router.base，也要同步设为'./'，否则H5端也会路径异常 - 真机调试时，在Safari（iOS）或Chrome（Android）远程调试器里看Network面板，检查
index.html是否加载成功，再看app.js、chunk-xxx.js是否返回404
pages.json首页路径错或分包配置失效
白屏有时只是“找不到第一页”。pages.json里第一个pages项就是App启动时默认加载的页面，路径错、组件不存在、或被分包逻辑绕过，都会导致空壳启动。
- 确保
pages数组第一项path真实存在且可访问，比如"pages/index/index"，别写成"pages/index"或大小写不符（iOS区分大小写） - 若启用了分包，必须在
manifest.json中显式开启："app-plus": { "optimization": { "subPackages": true }, "runmode": "liberate" }，缺一不可 - 分包
root路径要和实际目录严格一致，比如"root": "pages/user"对应项目下pages/user/login/login.vue，不能多一层或少一层
iOS WKWebView初始化延迟引发的白屏
iOS的WKWebView加载JS有天然延迟，尤其首次冷启动时，onLaunch执行完，DOM还没准备好，mounted或onLoad就卡住，页面不渲染。
- 在
App.vue的onLaunch末尾加一句：if (uni.getSystemInfoSync().platform === 'ios') setTimeout(() => location.reload(), 800) - 配合
manifest.json启用原生启动页："splashscreen": { "autoclose": false, "delay": 2000 }，并在onLaunch里手动关：setTimeout(() => plus.navigator.closeSplashscreen(), 3000) - 首页组件务必极简：不
import图表库、不发多个并发请求、不用require('@/components/Heavy.vue')动态引入——这些都在首屏阻塞主线程
main.js的import阶段——那里连console都还没准备好。 
