uni-app启动白屏主因是onlaunch/onshow同步阻塞、pages.json配置错误、响应式失效或分包加载失败；需检查异步调用是否await、首页路径是否存在、data初始化是否规范、主包大小及分包路径是否正确。
uni-app 启动时页面白屏，大概率是 onLaunch 或 onShow 里做了同步阻塞操作
白屏不是渲染失败，而是 Vue 实例还没挂载、或挂载前就被卡住了。uni-app 的 App.vue 生命周期中，onLaunch 和 onShow 是在原生层触发的，如果在里面写 JSON.parse 大字符串、同步读文件、或直接调用未 await 的 Promise（比如忘记加 await 就调用 uni.getStorage），JS 线程就会卡住，页面完全不渲染。
- 检查
App.vue的onLaunch是否有没 await 的异步调用，例如：uni.getStorage({ key: 'token' })必须写成await uni.getStorage({ key: 'token' }) - 避免在
onLaunch中执行耗时同步逻辑，比如解析 MB 级 JSON、遍历大数组、正则全局匹配长文本 - 真机调试时打开「调试器 → Network」，看首屏资源（尤其是
app-service.js和app-wxss.js）是否加载超时或 404 —— 这类问题也会表现为白屏，但本质是构建产物缺失
pages.json 配置错误导致首页不加载，白屏却无报错
uni-app 的路由入口由 pages.json 的 "list" 数组第一项决定。如果误删了首页路径、拼错了 "path"、或把 "style" 写成无效 JSON，H5 端可能静默失败，小程序端则直接白屏且控制台不抛异常。
- 确认
pages.json中"list"第一项的"path"值存在对应目录，例如"path": "pages/index/index"对应src/pages/index/index.vue -
"style"字段必须是合法 JSON 对象，哪怕只写{"navigationBarTitleText": "首页"}，不能留空或写成"style": "" - H5 端可临时在浏览器地址栏手动访问
/pages/index/index.html，验证该页面能否独立打开 —— 如果 404，说明构建未包含该页面
Vue 组件内 data 初始化引发响应式失效，页面卡在 loading 状态
uni-app 使用 Vue 2（默认）或 Vue 3（需配置），但不管哪种，如果 data 返回的对象含未定义字段、或字段值为 undefined，后续赋值可能不触发视图更新，尤其配合 v-if 切换时，容易看起来像白屏（实际是 DOM 没插入）。
- 不要写
data() { return { list: undefined } }，改用list: []或null - 异步获取数据后，确保赋值给已声明的响应式字段，而不是新增属性：✅
this.list = res.data；❌this.$set(this, 'list', res.data)（多余）或this.newField = xxx（非响应式） - 在
onLoad中调用接口前，先设this.loading = true，并在.finally(() => { this.loading = false })关闭 —— 白屏常因 loading 状态没关，UI 停在骨架屏
分包加载失败或主包过大，导致 iOS 微信环境白屏
iOS 微信 WebView 对 JS 执行时长敏感，主包超过 2MB 或分包路径配置错误时，requireAsync 加载失败不会报错，而是静默终止，首页组件无法实例化。
- 运行
npm run build:mp-weixin后，检查dist/build/mp-weixin/common/下文件总大小，主包（不含subNute/目录）建议压到 1.8MB 以内 - 分包路径必须以
subNute/开头，且pages.json中对应页面的"path"要和物理路径一致，例如分包目录为src/subNute/user/，则页面路径应为"subNute/user/profile" - 在
manifest.json中确认"name"和"appid"正确，否则微信调试基础库会拒绝加载 script
