uni.setKeepScreenOn是唯一跨平台防息屏方案,但仅防黑屏不防锁屏;Android需声明WAKE_LOCK权限并重打包,iOS在新机型存在失效问题,调用须防重入且配对关闭。

uni.setKeepScreenOn 是唯一推荐的、跨平台可用的防息屏方案,但它只阻止屏幕变黑,不干预系统锁屏界面弹出,也不能提高亮度。真机上无效,90% 是没配 Android 权限或没重打包。
Android 必须声明 WAKE_LOCK 权限并重打包
没加权限 = 白写代码,App 端完全无反应,且不报错。HBuilderX 中需在 manifest.json 的「App原生端 → Android → 权限」里手动添加:
{
"name": "android.permission.WAKE_LOCK",
"description": "保持屏幕常亮权限"
}
或者直接编辑 src/main/AndroidManifest.xml,加一行:
<uses-permission android:name="android.permission.WAKE_LOCK"/>
- 改完必须重新制作自定义基座或云打包,热更新、普通运行、H5 都不生效
- 小米、华为等厂商系统可能二次拦截,需额外在手机设置中关闭该 App 的“省电优化”
- iOS 不需要权限,但 iPhone X 及更新机型 + iOS 13.11.3 存在已知失效问题,可降级测试或换用
plus.device.setWakelock(true)
onShow/onHide 中调用必须加防重入标记
直接在 onShow 里反复调用 uni.setKeepScreenOn({ keepScreenOn: true }),容易触发循环或卡死,尤其页面快速切换时。
- 用布尔变量标记是否已启用,例如:
let keepOn = false,调用前先判断if (!keepOn) { ...; keepOn = true; } -
onHide中必须配对关闭:uni.setKeepScreenOn({ keepScreenOn: false }),否则退出页面后仍耗电 - 不要在
onUnload或onHide里再调一次setKeepScreenOn—— 多余且可能失败
别把 keepScreenOn 和亮度、锁屏混为一谈
keepScreenOn: true 后屏幕依然可以是全黑(亮度为 0),用户仍能按电源键进锁屏,系统待机策略也可能强制锁屏(尤其 OEM 定制 Android)。
- 要真正“亮着”,得组合调用:
uni.setKeepScreenOn+uni.setScreenBrightness -
uni.setScreenBrightness在 Android 需额外申请WRITE_SETTINGS权限,iOS 上getScreenBrightness会静默失败 - 所谓“锁屏常亮”是伪命题:uni-app 无法控制锁屏界面是否显示,只能让屏幕在解锁状态下不灭
最容易被忽略的是权限没生效就测试,以及在 onShow 里无条件重复调用。真机调试前务必确认:打包日志里有 WAKE_LOCK 权限写入,且手机系统未对该 App 启用电池优化。


















