锁屏音频需用uni.getBackgroundAudioManager()并配全manifest权限,否则静音;H5不支持;iOS/Android配置不同且必须云打包;缺WAKE_LOCK权限安卓会暂停;用户拒绝后无法重申请。

锁屏控制本身不需单独申请权限,但实现锁屏后持续播放音频必须走后台音频通道,而这个通道的启用依赖系统级权限声明与 API 配合——漏掉任一环,锁屏就静音。
uni.getBackgroundAudioManager() 是唯一能触发锁屏控制的 API
别用 uni.createInnerAudioContext() 尝试锁屏播放,它在切后台后会被系统强制静音或中断,iOS 上尤其明显。只有 uni.getBackgroundAudioManager() 能注册系统媒体会话,让锁屏界面显示封面、标题、进度条,并响应物理按键(如耳机单击暂停)。
- 调用前必须先设置
title、singer、coverImgUrl,否则 iOS 锁屏无信息展示 - src 必须是有效 URL:本地资源用
/static/xxx.mp3,不能用相对路径或未打包的./assets/xxx.mp3 - H5 端完全不支持该 API,调用无报错也无效果,务必用条件编译隔离:
#ifdef APP-PLUS
manifest.json 中 iOS 和 Android 后台权限必须分别配对
iOS 和 Android 对“后台音频”的启用机制完全不同,不能混写、不能省略、不能靠猜。
- iOS:必须在
app-plus.distribute.ios.UIBackgroundModes中填["audio"](注意是字符串数组,不是"audio"或["playback"]) - Android:必须在
app-plus.background.mode中设为"audio"(不是"location",也不是空字符串) - 两者都依赖
app-plus.modules.Audio为{}(即启用音频模块),缺一不可 - 改完 manifest 后必须重新云打包,热更新和本地调试无法生效
Android WAKE_LOCK 权限不是可选,而是保底刚需
即使用了 uni.getBackgroundAudioManager(),部分安卓机型(华为、小米、OPPO)在锁屏几秒后仍会暂停播放——这不是代码问题,是系统休眠策略导致的。必须显式申请 WAKE_LOCK 权限才能维持 CPU 活跃。
- 在
manifest.json → app-plus → distribute → android → permissions中添加:"<uses-permission android:name=\"android.permission.WAKE_LOCK\" />" - 注意 XML 标签必须带转义,且结尾斜杠不能省略
- 若已在
AndroidManifest.xml手动加过该权限,也要同步删掉,避免冲突 - 不加此权限时,
uni.setKeepScreenOn(true)可能失效,但音频暂停与屏幕是否常亮无关,这是两个独立问题
用户拒绝后台音频权限后,没有“再次申请”入口
iOS 用户一旦在系统弹窗点「不允许」并勾选「不再询问」,后续所有 uni.getBackgroundAudioManager().play() 调用都不会触发弹窗,也不会报错,只是无声。Android 上虽不会永久封禁,但用户拒绝后,uni.getBackgroundAudioManager() 的状态事件(如 onError)可能不触发,行为不可靠。
- 无法用
uni.authorize({ scope: 'scope.backgroundAudio' })—— 这个 scope 在 App 端根本不存在,会静默失败 - 检测不到明确拒绝状态时,应默认引导用户去设置页:调用
uni.openSetting(),并在弹窗中说明“需开启后台音频权限” - 注意:iOS 的设置页无法跳转到具体开关项,只能打开通用设置;Android 可精准跳转,前提是 manifest 已正确声明
最常被忽略的点是:后台音频能力不是 JS 层能“调用即生效”的功能,它是原生层的契约。manifest 配错、没云打包、没设 coverImgUrl、没用对 API——任意一个环节断掉,锁屏就失效,而且往往没有任何错误提示,只表现为“无声”。


















