uni.getBackgroundAudioManager()是App端后台播放唯一入口,必须配合iOS的UIBackgroundModes:["audio"]、Android的WAKE_LOCK权限、HTTPS封面图及用户手势触发play(),缺一不可。

uni.getBackgroundAudioManager() 是 App 端后台播放的唯一入口
App 端锁屏后还想播音乐,uni.getBackgroundAudioManager() 不是“推荐用”,而是必须用。它直接桥接 iOS 的 AVAudioSession 和 Android 的 MediaSession,让系统承认“这个 App 正在播音频”,从而授予后台运行资格。用 uni.createInnerAudioContext() 或 <audio></audio> 标签,在真机锁屏后基本 1–3 秒内就会被静音或销毁,尤其 iOS 上几乎必然失效。
manifest.json 权限配置必须手动写对位置和格式
改 manifest 不是勾个选项就行,漏一项就白忙。关键点:
- iOS 配置必须嵌套在
"app-plus" → "distribute" → "ios"下,写成:"UIBackgroundModes": ["audio"](注意是数组,"audio"不能拼错、不能带空格) - Android 配置在
"app-plus" → "distribute" → "android"下,"permissions"必须是字符串数组:["<uses-permission android:name='\"android.permission.WAKE_LOCK\"'></uses-permission>"](XML 标签必须转义,结尾斜杠不能少) - 改完必须重新云打包——本地调试、热更新、HBuilderX 模拟器均不生效;打包日志里出现
background audio enabled才算成功
播放前必须填全 title/singer/coverImgUrl 三项元数据
iOS 锁屏界面只认这三个字段,缺任意一个,系统就当“无媒体信息”,直接不渲染控制条。Android 虽稍宽松,但这也是基础门槛:
虚拟歌手场景 MV 制作流水线。输入音乐音频、歌词、视频脚本、虚拟歌手三视图参考图,自动生成完整场景 MV。支持 AI 动态视频、风格化动画模板、3D 模型三种动画模式。不支对口型。
-
coverImgUrl必须是本地绝对路径(如/static/cover.jpg),网络地址在 App 端无效 -
title和singer至少填两个,否则 iOS 锁屏只显示“未知” - 必须在调用
play()前设置好这三项,顺序不能颠倒;play()后再设,iOS 不同步显示
播放动作必须由用户手势触发,且监听要用 manager 自身事件
不能在 onLoad 或 onShow 里自动调 play(),否则 iOS/Safari 微信会拦截且不抛错。状态监听也别依赖页面生命周期:
- 可靠做法:绑定到按钮
@click回调中执行manager.play() - 监听实际播放状态,只能用
manager.onPlay()、manager.onPause()、manager.onEnded()—— 用户从锁屏点播放键时,页面根本没onShow,但onPlay一定会触发 -
onEnded后需手动seek(0)+play()实现循环,loop = true在后台无效
最容易被忽略的是:H5 端完全不支持 uni.getBackgroundAudioManager(),调用无报错但也不起作用,务必用条件编译隔离;而 iOS 对 HTTPS、字段完整性、触发时机的限制极严,错一点就静默失败,连错误都不抛。

















