必须在首次播放前初始化uni.getBackgroundAudioManager(),切换音轨需原子性更新src及全部元数据并调用play()刷新锁屏;iOS需配置UIBackgroundModes、规范coverImgUrl路径;Android需添加WAKE_LOCK权限并全局管理实例。

uni.getBackgroundAudioManager() 必须在首次播放前就初始化
多音轨切换本质是频繁替换 bgm.src,但锁屏信息(封面、标题、歌手)不会自动同步更新——系统只认第一次调用 play() 时已设置的元数据。如果切换音轨后只改 src 不重设 title/singer/coverImgUrl,锁屏界面仍显示旧信息,甚至可能因元数据缺失导致控制栏消失。
实操建议:
- 每次切换音轨前,必须显式重置全部元数据字段,哪怕只换一首歌也要重新赋值
- 避免在
onPlay回调里设元数据——此时音频已开始播放,系统不刷新锁屏 UI - 推荐封装切换函数,确保 src 和元数据原子性更新:
const bgm = uni.getBackgroundAudioManager();
function switchTrack(track) {
bgm.src = track.url;
bgm.title = track.title;
bgm.singer = track.singer;
bgm.epname = track.album || '';
bgm.coverImgUrl = track.cover;
// 必须主动触发一次 play 才能刷新锁屏信息(即使已在播放)
bgm.play();
}
iOS 锁屏信息不显示?检查 UIBackgroundModes 和 coverImgUrl 格式
iOS 对锁屏信息展示极其敏感:缺权限、图片路径不对、尺寸不合规,都会导致封面空白或整个控制栏不出现。常见错误是把本地路径写成 /static/cover.jpg —— iOS 要求必须是绝对路径或网络 URL,且图片需为 PNG/JPEG,尺寸建议 ≥ 300×300px。
实操建议:
- manifest.json 中确认已开启
UIBackgroundModes: ["audio"],否则锁屏信息根本不会注册 -
coverImgUrl不能用相对路径,优先用网络地址(如https://cdn.example.com/cover.jpg);若必须用本地资源,转成 base64 或通过plus.io.convertLocalFileSystemURL()获取 iOS 可识别的 file:// 路径 - 测试时用真机,模拟器无法验证锁屏效果
Android 多音轨切换后锁屏控制失效?注意 WAKE_LOCK 权限和厂商后台策略
部分 Android 厂商(华为 EMUI、小米 MIUI)会在切后台后强制冻结进程,导致 bgm.onTimeUpdate 等事件停止触发,锁屏控件变灰、无法响应暂停/上一首操作。这不是代码问题,而是系统级限制。
实操建议:
- manifest.json 的
permissions中必须包含"WAKE_LOCK",否则后台保活能力直接归零 - 不要依赖
onStop或onHide做音轨切换——App 进入后台后这些钩子可能不执行,应提前在前台完成切换逻辑 - 对关键操作(如暂停)做双重保障:除调用
bgm.pause()外,加一层本地状态标记,App 切回前台时立即校验并同步到bgm实例
页面跳转时音轨中断?全局管理实例不能被销毁
如果在每个页面都调用 uni.getBackgroundAudioManager(),不同页面拿到的是独立实例,切换页面后原实例被 GC,新页面的实例没继承播放状态,必然中断。锁屏信息也丢失,因为系统只绑定最初那个实例。
实操建议:
- 全局唯一实例:在
app.vue的created钩子里初始化bgm并挂到uni.$bgm,所有页面复用同一引用 - 禁止在页面
onUnload中调用bgm.destroy()—— 这会彻底断开后台播放链路 - 监听
onShow检查当前播放状态,必要时手动触发bgm.play()恢复(尤其从后台切回时)


















