锁屏状态下定时器失效、页面横竖屏错乱、后台任务中断等问题是uni-app因原生系统休眠策略响应不一致导致的必然行为,必须绕过JS线程限制,用iOS的UNBackgroundTaskIdentifier、Android的WorkManager或前台Service等原生能力兜底,业务逻辑需降级为锁屏前保存状态、唤醒后校验补偿,纯前端定时器不可靠。

锁屏状态下定时器失效、页面横竖屏错乱、后台任务中断——这些问题不是“偶尔出错”,而是uni-app在iOS/Android原生层对系统休眠策略响应不一致导致的必然行为,必须绕过JS线程限制,用原生能力兜底。
onLaunch里没await异步调用,锁屏后白屏或卡死
锁屏瞬间常触发App.vue的onLaunch重执行(尤其冷启动),若其中混入未await的uni.getStorage或uni.request,主线程直接挂起,后续Vue实例无法挂载,表现就是白屏且console.log('start')都不输出。
- 所有
uni.xxx异步API(包括uni.getSystemInfoSync之后的字段访问)必须await,不能只写调用语句 - 禁止在
onLaunch中做同步耗时操作:比如JSON.parse几MB缓存、正则匹配长文本、遍历万级数组 - 实在要处理本地大对象,改用
setTimeout(() => { /* logic */ }, 0)让出主线程,或用uni.nextTick - 加一句
console.log('onLaunch start')在函数开头——如果这行都没输出,问题在更早阶段(如main.jsimport报错、store循环依赖)
setTimeout/setInterval在锁屏后延时不准甚至失效
这是原生系统级限制:iOS后台最多运行3分钟,Android各厂商策略不一(华为/小米常强制冻结),JS定时器在WebView被挂起后完全停摆,不是uni-app的bug,而是跨端框架无法绕过的事实。
- 纯前端方案无效,
setInterval在锁屏后基本不可靠,别指望它准时触发 - 需改用原生能力:iOS用
UNBackgroundTaskIdentifier申请后台运行时间,Android用WorkManager或前台Service保活(uni-app需通过uni.requireNativePlugin调用) - 业务逻辑必须做降级:锁屏前保存状态,唤醒后检查时间差并补偿执行,而非依赖定时器“准时”
- 视频播放、语音识别等强时效场景,必须走原生SDK(如腾讯云TRTC、阿里云RTC),它们内部已封装后台保活逻辑
pages.json里pageorientation配置在锁屏后失效
"pageorientation": "landscape"只控制页面初始化方向,不监听或响应系统旋转事件。锁屏再亮屏、从其他页面跳转进来时,设备物理方向已变,但页面CSS和渲染逻辑没重算,导致布局错位、状态栏遮挡内容。
- 纯CSS媒体查询(
@media (orientation: landscape))只能响应浏览器窗口变化,对原生锁屏/唤醒无感知 - 必须配合原生API:
uni.setScreenOrientation锁定方向(仅App端有效),小程序端需用wx.setScreenBrightness+ 自定义全屏容器模拟 - iOS真机上,
setScreenOrientation需在manifest.json中开启"ios": { "usesFullScreen": true },否则被系统拦截 - 横竖屏切换时,务必监听
uni.onWindowResize(H5/App)或wx.onWindowResize(小程序),手动重绘ECharts等图表库
锁屏后推送通知点击无法唤醒页面或跳转错误
锁屏状态下用户点击通知,App被拉起但onLaunch参数可能丢失或格式异常,导致路由跳转失败、页面空白,尤其在Android厂商通道(华为/荣耀/vivo)上高发。
- 微信小程序端通知跳转路径必须是绝对路径(如
/pages/detail/detail?id=123),相对路径../detail/detail会解析失败 - App端需在
onLaunch和onResume两个生命周期里都处理options参数,锁屏唤醒走onResume,冷启动走onLaunch - 华为/荣耀通道返回的
payload字段名是data,vivo是custom_content,FCM是notification,必须按厂商分别解析 - 跳转前先校验目标页面路径是否存在,用
uni.preloadPage预加载,避免uni.navigateTo因页面未注册而静默失败
锁屏相关问题的本质,是Web引擎与原生系统休眠机制的冲突。uni-app能做的只是桥接,真正可靠的逻辑必须下沉到原生层——别在JS里跟系统抢CPU,该交还给原生的,就交还。


















