uni-app白屏因js线程在onlaunch挂起，需依次排查：onlaunch卡死、publicpath配置错误（生产环境必须为'./'）、pages.json路径大小写及分包配置、android远程调试与包名一致性、ios wkwebview初始化延迟。
HBuilderX调试uni-app项目时白屏，控制台只显示“应用已启动”却无后续日志、无页面渲染、无错误提示，说明JS线程在onLaunch阶段已挂起，Vue实例根本未挂载。
检查App.vue的onLaunch是否卡死
第一步：在App.vue的onLaunch函数第一行插入console.log('onLaunch start')，保存后真机运行。
若该日志未输出，问题发生在更早环节——可能是main.js中import失败、store循环依赖，或vue.config.js语法错误导致打包产物缺失入口JS。
第二步：逐行注释onLaunch内代码，重点排查uni.getSystemInfoSync()调用后是否直接访问res.model（iOS 16+已改为res.deviceModel，取不到则undefined，后续链式调用崩溃）。
第三步：检查是否存在未await的异步调用，例如uni.getStorage({ key: 'token' })必须写成await uni.getStorage({ key: 'token' }），否则Promise未完成就继续执行，JS线程被阻塞。
第四步：避免在onLaunch中同步读取uni.getStorageSync()后立刻做复杂计算或遍历大数组，改用setTimeout(() => { /* 逻辑 */ }, 0)让事件循环释放控制权。
确认publicPath和资源路径配置
打开vue.config.js，检查publicPath字段：
开发环境可设为'/'，但【生产环境必须设为'./'】，否则打包后JS/CSS加载404，WebView静默失败，不报错也不渲染，只留白屏。
若项目同时配置了manifest.json中的h5.router.base，也必须同步设为'./'，否则H5端同样路径异常。
这一步操作起来很简单，直接把vue.config.js里publicPath: '/'改成publicPath: './'即可。
验证pages.json首页路径与分包配置
方法一：打开pages.json，确认"pages"数组第一个对象的"path"值真实存在且大小写完全匹配，例如"pages/index/index"对应src/pages/index/index.vue；iOS区分大小写，写成"pages/Index/index"就会白屏。
方法二：若启用分包，必须在manifest.json中显式开启：
"app-plus": { "optimization": { "subPackages": true }, "runmode": "liberate" }，缺一不可。
分包root路径要和实际目录严格一致，比如"root": "pages/user"对应项目下pages/user/login/login.vue，多一层或少一层都会导致首页无法加载。
注意：pages.json中"style"字段必须是合法JSON对象，哪怕只写{"navigationBarTitleText": "首页"}，不能留空或写成"style": ""。
启用Android远程调试与校验包名
进入manifest.json → App常用设置 → Android设置 → Webview，必须勾选“启用远程调试”，否则Chrome DevTools无法注入，JS错误日志不上报。
同时确认manifest.json中"package"字段（如"com.example.uniapptest"）与手机已安装APP包名【严格一致，区分大小写】，否则系统拒绝复用进程，直接白屏且无logcat输出。
这一步漏掉，真机调试基本等于盲调。
处理iOS WKWebView初始化延迟
iOS真机首次冷启动时，WKWebView加载JS引擎有天然延迟，onLaunch执行完DOM却未准备好，mounted卡住，页面不渲染。
在App.vue的onLaunch末尾添加兜底刷新逻辑：
if (uni.getSystemInfoSync().platform === 'ios') setTimeout(() => location.reload(), 800)
不要写成location.reload(true)，iOS下该参数无效且可能触发异常。
