锁屏通知栏点击无响应的主因是play()未在用户手势中调用、iOS三字段缺失或平台不支持。必须在click等交互事件中调用play(),确保title/coverImgUrl/src齐全且合规,微信外平台需降级处理,并检查manifest中后台音频权限配置。

uni.getBackgroundAudioManager() 的 play() 必须由用户手势触发
锁屏通知栏点击无反应,90% 是因为 manager.play() 没在用户点击事件里调用。iOS 和微信小程序强制要求首次播放必须由 click、touchend 等明确交互触发,否则静默失败——不报错、不提示、无声响,但后续所有控制(包括锁屏界面的播放/暂停按钮)都失效。
- 错误写法:
onLoad里直接manager.play(),或onShow自动播 - 正确路径:必须绑定到 button 的
@click或类似事件回调中,且该事件不能是自动触发(比如mounted里模拟 click) - 注意:锁屏界面的“播放”按钮本质是向后台音频 manager 发送 play 指令,如果 manager 根本没成功启动过,这个指令就无处投递
title / coverImgUrl / src 缺一不可,iOS 锁屏控件才可交互
iOS 锁屏界面只认 title、coverImgUrl、src 这三个字段。缺任意一个,系统判定为“无效媒体会话”,锁屏控件显示为灰色、不可点,点击也无响应——不是 bug,是 iOS 原生策略。
-
title必填(字符串非空),否则锁屏只显示“未知” -
coverImgUrl必须是 HTTPS 地址,尺寸 ≥ 300×300,否则 Android 通知栏缩略图糊,iOS 可能拒绝渲染控件 -
src必须是可直链访问的远程地址(如https://xxx.com/a.mp3),/static/xxx.mp3在 App 端打包后常因路径解析失败导致 manager 初始化失败
支付宝/字节/快应用平台根本无法响应锁屏点击
这些平台没有原生后台音频会话支持,uni.getBackgroundAudioManager() 在它们内部返回空对象或直接报错,锁屏通知栏压根不会出现,更谈不上点击响应。强行在非微信平台调用该 API,只会让逻辑卡死或静默降级。
- 别用条件编译硬套微信逻辑,例如
process.env.UNI_PLATFORM === 'mp-weixin'才初始化 manager - 支付宝等平台只能降级:切后台时
manager.pause()(实际是innerAudioContext.pause()),前台恢复后提示“继续播放”,或直接隐藏锁屏控制入口 - H5 端同理:
uni.getBackgroundAudioManager()返回的对象不具备真实后台能力,play() 失败也不抛错,需用new Audio()+document.visibilityState监听做页面内播放
App 端锁屏点击无响应,大概率 manifest.json 权限没生效
App 端锁屏控制依赖原生层音频会话,manifest.json 配置漏项或位置错误,会导致 manager 无法获取系统音频焦点,锁屏点击后无任何回调——连 onPlay 都不会触发。
- iOS 配置必须嵌套在
"app-plus": {"distribute": {"ios": {"UIBackgroundModes": ["audio"]}}},"audio"是数组元素,不是字符串 - Android 需加
"permissions": ["<uses-permission android:name='\"android.permission.WAKE_LOCK\"'></uses-permission>"],XML 标签要转义,斜杠不能省 - 改完 manifest 后必须重新云打包,本地调试和热更新完全不生效;真机测试前看打包日志是否有
background audio enabled提示



















