锁屏界面显示歌手头像必须用uni.getBackgroundAudioManager()并正确设置coverImgUrl,因其需HTTPS地址、≥300×300像素、JPG/PNG格式、合法响应头,且须在play()前按序设置title/singer/coverImgUrl/src,并配全manifest原生权限后云打包真机验证。

锁屏界面显示歌手头像,本质是让系统媒体中心渲染封面图,必须用 uni.getBackgroundAudioManager() 并正确设置 coverImgUrl,其他方式(比如 uni.createInnerAudioContext())完全无效。
为什么 coverImgUrl 设了却不出现在锁屏界面
常见错误是只填了 URL 却忽略协议、路径或格式限制:
-
coverImgUrl必须是 HTTPS 地址(iOS 强制,Android 多数版本也要求),http://或本地路径(如/static/xxx.jpg)在锁屏下不显示 - 图片尺寸建议 ≥ 300×300 像素,过小会被系统忽略或模糊拉伸
- 图片格式仅支持 JPG/PNG,WebP 在部分 Android 机型上无法解析
- iOS 对图片响应头有要求:必须返回
Content-Type: image/jpeg或image/png,否则静默失败
App 端 manifest.json 必须配齐三项原生权限
缺一不可,否则 coverImgUrl 根本不会被系统读取:
- iOS:在
manifest.json的app-plus.distribute.ios.UIBackgroundModes中填["audio"](不是["playback"]或空数组) - Android:在
app-plus.background.mode中设为"audio"(不是"location") - 两个平台都需确保
app-plus.modules.Audio为{}(启用音频模块)
配置后必须重新「云打包」,真机测试才生效;本地运行或热更新不触发后台音频能力。
coverImgUrl 赋值时机和常见陷阱
不能等 play() 之后再设,必须在调用 play() 前完成所有元信息设置:
- 顺序必须是:
bgAudio.title→bgAudio.singer→bgAudio.coverImgUrl→bgAudio.src→bgAudio.play() -
coverImgUrl设成空字符串、null或 404 地址,iOS 锁屏直接不显示任何封面,也不报错 - Android 部分厂商 ROM(如华为、小米)会缓存封面图,换歌后需加时间戳参数避免旧图残留:
coverImgUrl + '?t=' + Date.now()
最容易被忽略的是:iOS 对 coverImgUrl 的加载超时极短(约 2 秒),如果 CDN 响应慢或图片体积过大(>500KB),封面就会白屏——这不是代码问题,是系统策略。建议压缩封面图并托管到稳定 CDN,且务必用真实真机验证锁屏效果,模拟器无法复现。


















