uni.getBackgroundAudioManager()是微信小程序锁屏音频控制唯一有效API,需填title/singer/coverImgUrl三字段且coverImgUrl必须HTTPS,播放须用户手势触发,App端需manifest.json正确配置后台音频权限。

uni.getBackgroundAudioManager() 是锁屏控制的唯一入口
微信小程序里,uni.createInnerAudioContext() 切后台就停,iOS 上甚至实例直接销毁;只有 uni.getBackgroundAudioManager() 是微信原生提供的独立音频服务,它不依赖页面生命周期,能响应锁屏、耳机键、通知栏操作。其他平台(支付宝、字节、快应用)压根没这个 API,调用返回 undefined 或空对象,别硬套。
title/singer/coverImgUrl 缺一不可,否则锁屏界面不显示
iOS 微信锁屏界面只认 title、singer、epname 这三个字段,至少填两个,否则显示“未知”;coverImgUrl 必须是 HTTPS 地址,尺寸 ≥ 300×300,Android 微信通知栏才显示清晰缩略图。常见错误是只设了 title 和 src,结果锁屏一片空白。
-
title和singer是强制项,漏掉任一,iOS 直接不渲染控件 -
coverImgUrl填了但用 HTTP 协议,iOS 会拒绝加载封面 - 本地路径如
/static/cover.jpg在小程序里无效,必须走 HTTPS CDN
播放必须由用户手势触发,且不能在 onLoad 里自动调用
赋值 src 后不会自动加载,必须显式调用 manager.play();而这个调用必须发生在用户点击、tap 等交互之后,否则 iOS 直接静音或拒绝播放。很多项目卡在“点了没反应”,其实是把 play() 放在了 onLoad 或 onShow 里,系统直接拦截。
- 正确做法:绑定 button 的
@click,里面先设manager.src,再调manager.play() - 不要在
onHide里手动pause()再onShow恢复——用户从锁屏点播放,完全无响应 - 监听要用
manager.onPlay/manager.onPause,不是页面的onShow/onHide
App 端配置错一个字段,后台播放就失效
uni.getBackgroundAudioManager() 在 App 端也生效,但必须配对 manifest.json —— iOS 要 UIBackgroundModes: ["audio"],Android 要 background.mode: "audio",且 app-plus.modules.Audio 必须为 {}。改完必须重新云打包,热更新和本地调试不生效。
- iOS 配置写成
"UIBackgroundModes": "audio"(字符串)或拼错成"audion",后台播放直接被系统拒 - Android 的
permissions字段要带转义 XML 标签:"<uses-permission android:name=\"android.permission.WAKE_LOCK\" />" - 真机测试前看打包日志有没有
background audio enabled提示,没有就是配置没生效
BackgroundAudioManager,其他小程序没有;App 端靠 manifest 配置,H5 根本不存在“后台”概念。跨端时别指望一套代码通吃。


















