根本原因是系统级音频会话未正确激活,导致ios/android未将应用注册为媒体播放器;需ios配置info.plist启用audio后台模式并原生激活audiosession,android声明foregroundservice权限并启动前台服务,且所有平台必须原生拦截蓝牙按键事件。

UniApp 应用在锁屏状态下,蓝牙耳机连接后控制栏(如播放/暂停、上一首/下一首)无法响应或显示异常,根本原因不是 UI 层问题,而是系统级音频会话(Audio Session)未正确激活,导致 iOS/Android 未将应用注册为「媒体播放器」,从而不向锁屏控制栏暴露控制接口。
uni-app 锁屏控制栏不显示蓝牙耳机控制项
现象:App 正常播放音频,但锁屏后控制栏无按钮,或点击无响应;部分 Android 机型甚至无法触发 uni.onBackgroundAudioPlay 等事件。
- iOS 必须在
Info.plist中启用UIBackgroundModes→audio,且调用uni.setKeepScreenOn(true)不起作用——它只防熄屏,不保音频后台能力 - Android 需在
AndroidManifest.xml中声明android.permission.FOREGROUND_SERVICE,并启动前台服务(仅限 Android 8.0+),否则系统会在锁屏后 1–2 分钟内杀死音频线程 - uni-app 本身不提供原生音频会话管理 API,
uni.startBackgroundAudio已废弃,必须切换到uni.createInnerAudioContext()+ 手动配置原生层
uni.createInnerAudioContext 在锁屏下失效的修复路径
关键点:默认创建的 innerAudioContext 实例不具备后台音频能力,需配合平台特定初始化。
- iOS:必须在调用
play()前,通过 Native.js 注入 Objective-C 代码激活音频会话,示例片段:
const nativeObj = uni.requireNativePlugin('AudioSession');
nativeObj.activate({ category: 'Playback', mode: 'Default' });
- Android:需在
mainfest.json的android节点中添加 foregroundService 配置,并确保音频播放时调用uni.getBackgroundAudioManager()(仅 App 端有效,小程序走BackgroundAudioManager) - 所有平台都必须监听
uni.onAudioInterruptionBegin和uni.onAudioInterruptionEnd,否则蓝牙耳机断连/切歌时状态不同步
蓝牙耳机物理按键事件无法捕获
现象:按耳机播放键无反应,或触发了系统默认行为(如 Siri/小爱同学)。
- iOS 侧:需在 Native.js 中注册
MPRemoteCommandCenter,拦截play/pause/nextTrack/previousTrack事件,uni-app 无对应 JS API - Android 侧:依赖
MediaSession,必须通过原生插件暴露onMediaButtonEvent回调,否则按键事件被系统吞掉 - 微信小程序例外:可直接用
wx.getBackgroundAudioManager()的onPlay/onPause监听,但仅限已授权「后台音乐播放」场景,且不支持自定义快捷键映射
真正影响体验的不是“怎么写”,而是“哪一步必须原生介入”——比如 iOS 的音频会话激活、Android 的前台服务声明、所有平台的物理按键拦截,这些 uni-app JS 层完全不可绕过。漏掉任意一项,锁屏控制栏就只是个摆设。











