微信小程序锁屏音频需用uni.getBackgroundAudioManager()而非uni.createInnerAudioContext(),并正确配置manifest.json中iOS的UIBackgroundModes和Android的background.mode及Audio模块,且必须真机云打包验证。

不能“禁止锁屏”,只能让音频在锁屏后继续播放——这取决于平台能力、原生配置和 API 选型,不是 JS 层面能开关的。
微信小程序必须用 uni.getBackgroundAudioManager()
切后台或锁屏后音频中断,99% 是误用了 uni.createInnerAudioContext()。它在微信里本质是 InnerAudioContext,生命周期绑定页面,一 onHide 就销毁或暂停,iOS 甚至直接释放实例。
-
uni.getBackgroundAudioManager()是微信原生提供的单例服务,独立于页面,支持锁屏控制、耳机键响应、通知栏操作 - 必须在用户点击等交互中调用
play(),不能在onLoad或onShow自动触发(iOS 会静默拒绝) -
title、singer、epname至少填两个,否则 iOS 锁屏界面只显示“未知”,控制条不出现 -
coverImgUrl必须是 HTTPS 地址,建议 ≥ 300×300,Android 微信通知栏才显示清晰缩略图 - 赋值
src后必须显式调用play(),光设src不会加载也不播放
App 端必须配 manifest.json + uni.getBackgroundAudioManager()
iOS 和 Android 后台音频不是靠 JS 调用就能开启的,系统需要明确“报备”。漏掉任一配置,锁屏几秒后必停,且无错误提示。
- iOS:在
manifest.json的app-plus.distribute.ios.UIBackgroundModes中填["audio"](必须是数组,不能是字符串或空) - Android:在
app-plus.background.mode设为"audio",同时确保app-plus.modules.Audio为{} - 改完必须重新云打包,热更新和本地调试无法生效;真机测试前确认打包日志有 “background audio enabled” 提示
-
uni.createInnerAudioContext()在 App 端锁屏下也无效——它没声明后台意图,系统默认挂起,iOS 尤其严格
支付宝/字节/快应用等平台根本没后台音频能力
这些平台未提供类似微信 BackgroundAudioManager 的稳定接口。uni.createInnerAudioContext() 切后台必停,且无法通过 manifest 配置、权限声明或事件监听恢复。
- 别在非微信平台硬套微信方案:
uni.getBackgroundAudioManager()在支付宝里返回undefined或空对象,调用play()会直接报错 - 降级策略只能是:切后台时主动
pause(),前台恢复时提示“继续播放”,或直接隐藏控制条 - 不要尝试在
onHide里手动pause()再onShow恢复——用户从锁屏点播放,完全无响应
锁屏控制信息只对原生渲染模式生效
封面、标题、进度条能否在锁屏界面显示,不仅取决于 JS 设置,还受渲染模式限制。
- 必须使用原生渲染模式(
vue.config.js或 HBuilderX 中关闭“使用 webview 渲染”) -
coverImgUrl必须是本地绝对路径(如/static/cover.jpg),不能是相对路径或未打包资源 - iOS 上需额外调用
plus.audio.setLockScreenControl(),但必须包裹在#ifdef APP-PLUS中,H5 和小程序不支持 - 循环播放不能只设
loop = true,需监听onEnded手动seek(0)+play(),并加try/catch兜底
最易被忽略的点:iOS 锁屏控件不显示,往往不是代码问题,而是 manifest.json 配置位置错了——必须嵌套在 app-plus → distribute 下,iOS 和 Android 配置不能混写,也不能漏掉 Audio 模块启用。真机测试前,务必确认云打包日志里有对应提示。


















