安卓锁屏控制栏需前台服务+媒体通知+权限配置，uni.setkeepscreenon无效；必须用原生插件（如xzh-musicnotification）实现mediasession，配置manifest权限，适配厂商省电策略。
uni-app 安卓版无法真正“常驻锁屏控制栏”——这是系统级限制，不是代码能绕过的。你能做的，是让音频播放在锁屏后继续、并在状态栏显示可控的媒体通知（即“锁屏控制栏”），但必须依赖前台服务 + 媒体通知模板 + 正确权限配置。
为什么直接调 uni.setKeepScreenOn 不行
这个 API 只管屏幕亮灭，和锁屏后的控制栏完全无关。锁屏时系统会销毁 Activity 上下文，uni.setKeepScreenOn 调用失效，且 Android 8.0+ 对后台服务有严格限制，没前台服务支撑，音频一锁屏就停。
- 常见错误现象：
uni.getBackgroundAudioManager()在锁屏后静音、onHide触发后播放中断、状态栏无播放控件 - 根本原因：没有前台服务绑定媒体会话（MediaSession），系统认为 App 已退到后台，按策略回收资源
- 性能影响：不加前台服务，锁屏 1–3 分钟内音频必然被杀；加了则可稳定运行数小时（取决于厂商省电策略）
必须用原生插件实现前台媒体服务
uni-app 官方 API 不提供 MediaSession 和前台服务封装，必须引入支持 Android 前台服务的原生插件，例如 XZH-musicNotification 或 uni-app-audio-foreground。纯 JS 方案在 Android 9+ 全面失效。
- 插件需在
manifest.json的"nativePlugins"节点注册，并确保离线打包时启用 - AndroidManifest.xml 必须声明以下权限（缺一不可）：
android.permission.FOREGROUND_SERVICE、android.permission.POST_NOTIFICATIONS（Android 13+）、android.permission.WAKE_LOCK - 离线打包时，插件的
dcloud_uniplugins.json需正确配置 service 类路径和 intent-filter，否则前台服务无法启动 - 真机调试必须用正式 APK，HBuilderX 模拟器不触发前台服务生命周期
JS 层调用必须配合生命周期和媒体会话
插件只是载体，JS 层调用逻辑错一步，通知栏控件就不显示或无法响应点击。
- 播放开始时立即调用插件初始化方法（如
audioPlugin.startForegroundService()），不能等onShow或用户操作后再调 - 必须调用
uni.getBackgroundAudioManager()并设置title、epname、singer等字段，否则通知栏只显示默认文字或空白 - 监听
onPlay、onPause、onStop后同步更新插件的播放状态，否则锁屏后点击暂停按钮无响应 - 退出播放页时，必须显式调用
audioPlugin.stopForegroundService()，否则通知栏残留、服务持续耗电
厂商适配是最大坑点
小米、华为、OPPO 等对前台服务拦截极严，同一套代码在不同机型表现差异极大。
- 小米 HyperOS：需手动开启“后台弹出界面”+“自启动”+“锁屏显示”，否则通知栏控件不出现
- 华为 EMUI/鸿蒙：必须在 AppInfo → 电池优化中设为“不受限制”，否则前台服务 2 分钟后被杀
- vivo/Realme：需关闭“熄屏后停止网络”和“后台高耗电提醒”，否则音频流断开
- 所有厂商都要求用户首次启动时主动弹窗申请
POST_NOTIFICATIONS权限，拒绝即无通知栏控件
锁屏控制栏不是“写段 JS 就出来”的功能，它本质是 Android 媒体会话与前台服务的协同结果，任何环节缺失都会导致白屏、无声、无控件。最易被忽略的是离线打包时插件未生效，以及厂商权限未手动开启——这两点占线上问题的 70% 以上。
