uni-app引导页需手动实现，首次启动用uni.getStorageSync('launchFlag') === true判断并设true；禁用splash等待渲染、首帧图与splash一致、视频加muted/ playsinline/ x5-video-player-type属性且用绝对MP4路径；swiper禁autoplay、duration设320ms、circular为false、外层设height。

uni-app 的引导页不是配个配置就能跑起来的，必须用 Vue 页面手动实现——原生 splash 是静态图，不执行 JS、不能跳转、没法播视频或轮播。

怎么判断首次启动并跳过引导页

核心是用 uni.getStorageSync 同步读取标记，且必须显式比对 === true，否则字符串 "true" 或数字 1 会误判：

• uni.getStorageSync('launchFlag') === true → 安全跳首页（推荐）
• uni.getStorageSync('launchFlag') → 若存的是 "false" 或 0，也会被当成 false，逻辑错乱
• 千万别用 uni.getStorage（异步），onLoad 里等回调会导致白屏或闪退
• 跳转后必须立刻调用 uni.setStorageSync('launchFlag', true)，否则每次重启都进引导页

为什么引导页一打开就闪白屏

根本原因是原生 splash 关闭和 Vue 页面 mount 之间存在渲染空档，尤其在低端安卓机上可达 300ms+。单纯调大 splashscreen.delay 没用，反而延长启动时间：

• pages.json 中必须设 "alwaysShowBeforeRender": false，禁用 splash 等待首页渲染
• 把引导页路径（如 "path": "pages/guide/guide"）设为 pages.json 的第一个页面
• 引导页的 onLoad 里立即执行 videoContext?.play() 或 swiper.current = 0，加 setTimeout(() => {}, 0) 确保 DOM 就绪
• 首帧画面要和原生 splash 图（splashscreen.image）完全一致，视觉上“无缝”

视频引导页必须加的三个 video 属性

App 端 标签不加特定属性，90% 情况下会黑屏、跳原生播放器、或点一下才播：

uni-app

uni-app 是基于 Vue 的跨端开发框架，适合开发 H5、App、小程序、鸿蒙和多端业务应用。

下载

• muted：iOS/Android WebView 默认禁止有声自动播放，静音是硬性前提
• playsinline：iOS 必须，否则强制全屏、页面中断、返回后白屏
• x5-video-player-type="h5-page"：安卓微信系 X5 内核必需，否则走 native player，无法控制、无法监听事件
• 视频路径必须用绝对路径：/static/guide.mp4，不能用 @/static/ 或相对路径
• 格式只用 MP4（H.264 + AAC），分辨率 ≤ 720p，码率 ≤ 1500kbps，否则首帧加载慢、黑屏久

swiper 轮播引导页卡顿的配置要点

在低端机上容易掉帧、滑动不跟手，关键不在数据量，而在渲染策略：

• 禁用 autoplay：用户还没看清就切走，体验差，且 autoplay 触发频繁重绘
• duration 设为 320ms：比默认 500ms 更快，减少视觉拖沓感
• circular 设为 false：避免首尾衔接时的瞬时位移抖动
• 外层 必须设明确 height（如 height: 100vh 或 300rpx），否则高度塌陷导致图片不渲染
• 推荐 mode="aspectFill"：等比缩放填满，裁边不拉伸，适配各种图比；避免用 mode="widthFix"，易塌成一条线

最常被忽略的其实是「首帧一致性」和「storage 值类型校验」：一个像素偏差会让用户察觉闪屏，一个 === true 写成 == true 就会让引导页反复出现。