必须使用 uni.getBackgroundAudioManager() 实现 App 端锁屏音频,因 uni.createInnerAudioContext() 仅支持页面级音频、锁屏后必中断;需配置 manifest.json(iOS 填 ["audio"]、Android 设 audio 模式)、HTTPS 封面、用户交互触发、显式 play(),并针对非微信平台和 H5 做条件编译与降级处理。

uni.getBackgroundAudioManager() 是 App 端锁屏音频的唯一入口
App 真机锁屏后音频中断,根本原因不是代码写错了,而是用了 uni.createInnerAudioContext()。这个 API 创建的是页面级音频上下文,系统不认为它需要后台存活,iOS 会几秒内静音,Android 则看厂商策略——大概率直接掐断。
必须改用 uni.getBackgroundAudioManager(),它是 uni-app 对接原生媒体会话的唯一通道,能触发系统音频焦点、响应锁屏界面控件、支持耳机键和通知栏操作。
- 调用前确保用户已触发交互(如点击播放按钮),不能在
onLoad或onShow自动调用,否则 iOS 会拒绝授权 -
title、singer、epname至少填两个,否则 iOS 锁屏界面只显示“未知” -
coverImgUrl必须是 HTTPS 地址或本地绝对路径(如/static/cover.jpg),相对路径或未打包资源会失效 - 赋值
src后必须显式调用manager.play(),光设 src 不会加载也不播放
manifest.json 配置缺一不可
没配 manifest,uni.getBackgroundAudioManager() 就是个摆设。iOS 和 Android 的后台音频权限不是 JS 能打开的,得靠原生层“报备”。漏掉任意一项,锁屏后必然中断,且通常不报错,只默默静音。
- iOS:在
manifest.json的app-plus.distribute.ios.UIBackgroundModes中填["audio"](不是["playback"],也不是空数组) - Android:在
app-plus.background.mode中设为"audio"(注意不是"location"或留空) - 同时确认
app-plus.modules.Audio为{}(启用音频模块) - 改完必须重新云打包,本地调试器不生效
不同平台能力差异极大,别硬套微信方案
微信小程序有 uni.getBackgroundAudioManager(),但支付宝、字节、快应用等平台压根没提供等效接口。它们不支持后台音频,这是平台限制,不是配置问题。
- 在非微信平台调用
uni.getBackgroundAudioManager(),可能返回空对象或直接报错 -
uni.createInnerAudioContext()在这些平台切后台必停,且无法通过任何manifest、权限声明或事件监听恢复 - 降级策略只能是:检测到非微信平台时,切后台自动
pause(),前台恢复后提示“继续播放”,或直接隐藏控制条 - H5 端该 API 完全无效,务必用
#ifdef MP-WEIXIN或#ifdef APP-PLUS条件编译隔离
循环播放和锁屏信息要手动兜底
后台播放不是设个 loop = true 就万事大吉。系统级音频管理器不会自动重播,锁屏界面信息也容易因路径或时机问题丢失。
- 循环播放必须监听
onEnded事件,手动seek(0)+play(),并加try/catch防止异常中断 - 锁屏控制信息(标题、封面)仅在原生渲染模式下生效,且
coverImgUrl若是网络地址,需确保尺寸 ≥ 300×300,否则 Android 微信通知栏缩略图模糊 - iOS App 端若用
plus.audio.setLockScreenControl(),必须包裹在#ifdef APP-PLUS中,否则 H5 或小程序会报错


















