uni-app后台音频播放需ios配置uibackgroundmodes["audio"]、android启用前台服务及wake_lock权限,并必须使用uni.getbackgroundaudiomanager()而非createinneraudiocontext(),且初始化时须设置title/singer/coverimgurl元数据,五者缺一不可。

uni-app 无法“保持后台播放且不被系统杀死”——它只能按系统规则申请后台音频能力,真正在后台持续播放的前提是:iOS 必须配置 UIBackgroundModes,Android 必须用 uni.getBackgroundAudioManager() + 前台服务通知,缺一不可。
为什么 uni.createInnerAudioContext() 锁屏就停
这个 API 是为前台页面设计的,切后台后 iOS 立即挂起、Android 多数机型几秒内静音。系统根本不认为你在“播音频”,只是个普通网页音效上下文。
- 调用
play()后一切正常,锁屏/切后台无声 → 典型误用uni.createInnerAudioContext() - iOS 上即使加了权限也无效,因为没触发系统音频会话
- H5 端调用
uni.getBackgroundAudioManager()无任何效果,别白费劲 - 必须用条件编译隔离:仅在 App 端启用该 API,H5 和小程序走其他方案
iOS 必须配 UIBackgroundModes: ["audio"]
这不是可选项,是硬性准入门槛。没这行配置,iOS 连后台播放资格都没有,切后台瞬间暂停。
- 打开
manifest.json,切换到「源码视图」 - 在
"app-plus"->"distribute"->"ios"节点下添加:"UIBackgroundModes":"audio" - 只支持
audio、location、fetch等有限值,填错或拼错(比如Audio)全无效 - 改完必须重新云打包,本地调试不生效
Android 需要前台服务 + WAKE_LOCK 权限
单纯调用 uni.getBackgroundAudioManager().play() 不够,华为、小米等机型锁屏后仍会快速中断,必须搭配前台服务通知。
- 在
manifest.json的"app-plus"->"android"->"permission"中声明:"android.permission.WAKE_LOCK" - 运行时无需动态申请,但必须确保打包时已写入
- 更稳妥的做法是集成原生插件(如
Ba-KeepAliveSuit或Keep-Alive),启动带常驻通知的前台服务 - 通知内容需明确说明“正在播放音乐”,否则部分厂商 ROM 会自动折叠或禁用
容易被忽略的初始化细节
很多人配完权限、写了播放逻辑,还是锁屏无声——问题往往出在初始化顺序和元数据缺失。
-
uni.getBackgroundAudioManager()返回对象后,必须先设title、singer、coverImgUrl,再调play() - coverImgUrl 必须是网络地址或本地绝对路径(如
_www/icon.png),相对路径或未加载资源会导致 iOS 锁屏控制区空白 - iOS 上若开启
location后台能力,但代码里没调plus.geolocation.watchPosition({background:true}),系统照样不维持后台 - Android 12+ 某些定制 ROM 会拦截前台服务通知,需引导用户手动开启“显示在其他应用上层”权限
真正卡住的从来不是代码怎么写,而是哪一步没触发系统认定的“合法后台音频行为”。配置、API、元数据、通知、权限,五者缺一不可,漏一个,锁屏后就静音。











