微信小程序必须用uni.getBackgroundAudioManager()实现后台音频播放,因其是唯一支持跨页面、跨后台持续播放的API,但需满足HTTPS源、完整元数据、用户手势触发三条件。

必须用 uni.getBackgroundAudioManager(),其他方式在微信小程序里切后台必停——这不是 bug,是平台限制,换 API 才能绕过。
为什么 uni.createInnerAudioContext() 切后台就停
它绑定页面生命周期,页面退到后台或被挂起时,微信会强制暂停并销毁音频上下文,且无法恢复。iOS 尤其严格,连 onTimeUpdate 都停止触发。你看到“无声”“没反应”“进度条卡住”,基本就是掉进这个坑了。
-
uni-audio组件本质也是基于InnerAudioContext,同样不支持后台 - 试图加
autoplay: true或在onLoad里直接play(),iOS 和微信会静默拦截,无报错、无提示、无声响 - 支付宝、字节、快应用等平台压根没提供后台音频能力,
uni.getBackgroundAudioManager()在这些平台返回undefined,不能当作通用方案
微信小程序必须用 uni.getBackgroundAudioManager() 的硬性条件
这是微信原生 BackgroundAudioManager 的 uni-app 封装入口,唯一能跨页面、跨后台持续播放的通道,但必须满足三件事,缺一不可:
-
src必须是 HTTPS 远程地址(如https://cdn.example.com/song.mp3),本地路径(/static/xxx.mp3)在 app-plus 打包后常因路径解析失败而静音 - 播放前必须设置至少三项元数据:
title、singer、coverImgUrl;iOS 锁屏控制条不显示、甚至播放失败,往往是因为漏了singer或coverImgUrl -
play()必须由用户手势触发(如 button 的@click),不能在onLoad、onShow或定时器里调用,否则 iOS 微信直接忽略
manifest.json 和平台降级怎么配才有效
"requiredBackgroundModes": ["audio"] 只对 app-plus(iOS/Android 原生包)生效,**在小程序平台完全无效**——别往 mp-weixin 节点下写,写了也白写。
- app-plus:在
manifest.json源码视图中,填到"app-plus": { "distribute": { "ios": { "plist": { "UIBackgroundModes": ["audio"] } } } },否则 iOS 后台直接静音 - H5:
uni.getBackgroundAudioManager()会自动降级为普通播放(无后台能力),需主动检测:uni.getSystemInfoSync().platform === 'h5',然后改用uni.createInnerAudioContext(),仍需用户点击触发 - 非微信小程序(支付宝/字节):该 API 返回
undefined,只能降级为页面内播放,切后台必然中断,无法规避
全局管理与事件监听容易踩的坑
微信的 BackgroundAudioManager 是单例,重复初始化或乱绑事件会导致状态错乱、多次触发、内存泄漏。
- 不要在每个页面
onLoad里都调uni.getBackgroundAudioManager();推荐在App.vue的onLaunch中获取一次,挂到uni.$bgm上供全局读写 - 事件监听(
onPlay、onPause、onEnded)必须在首次使用前绑定,且只绑一次;onUnload里要用offPlay等解绑,但别调stop(),否则用户切回来得重点播放 -
onTimeUpdate触发频率低(约 250ms 一次),不适合做拖动进度条;拖动应调seek(120),而不是反复设currentTime
真正难的不是写几行代码,而是把「用户手势触发」「元数据填全」「单例管理」「平台差异兜底」这四件事串起来——漏掉任何一环,iOS 锁屏后就没声音,微信切后台就中断,H5 还以为自己能后台播。











