锁屏标题显示“未知曲目”是因为未正确设置title、singer、coverImgUrl三个必填字段,且coverImgUrl必须为HTTPS地址、字段名严格区分大小写、需在play()前动态赋值,并确保manifest.json权限配置层级正确。

锁屏标题显示“未知曲目”是因为没填全三个必填字段
iOS 锁屏界面只认 title、singer、coverImgUrl 这三个字段,缺一个就降级为“未知曲目”。Android 虽不严格校验,但同样建议配齐——否则媒体控件可能不显示或信息残缺。
-
coverImgUrl必须是 HTTPS 地址(iOS 强制),/static/cover.jpg或本地路径会被忽略 -
title和singer不能为空字符串,传""或undefined等效于缺失 - 字段名大小写敏感,写成
Title或songName都无效
uni.getBackgroundAudioManager() 设置字段的正确时机
必须在调用 play() 之前或播放中设置,且不能只设一次——如果音频中途切换,需重新赋值。
- 不要在
onLoad里一次性设完就不管了,得绑定onCanPlay或接口返回后立即更新 - 避免异步延迟:比如先请求歌曲信息,再 set,但还没等 set 完就调了
play(),系统读到的仍是旧值或空值 - 示例写法:
const bgm = uni.getBackgroundAudioManager(); bgm.title = '夜曲'; bgm.singer = '周杰伦'; bgm.coverImgUrl = 'https://cdn.example.com/cover.jpg'; bgm.src = 'https://cdn.example.com/night.mp3'; // src 设置后自动触发加载,此时字段必须已就绪
App 端真机测试时标题仍不显示?检查 manifest.json 权限嵌套位置
即使代码全对,manifest.json 写错层级也会让系统忽略所有媒体信息。iOS 的 UIBackgroundModes 必须精确落在 app-plus → distribute → ios 下,Android 的 WAKE_LOCK 权限也必须包裹在 app-plus → distribute → android → permissions 中。
- 错误写法:
"distribute": { "permissions": [...] }—— 缺少android一级,权限不生效 - 正确写法:
"distribute": { "android": { "permissions": ["<uses-permission android:name='\"android.permission.WAKE_LOCK\"'></uses-permission>"] } } - 改完必须重新云打包,热刷新和本地调试无法验证后台行为
动态标题场景下 coverImgUrl 容易被忽略的细节
当标题来自接口(比如用户上传的歌单),封面图 URL 往往是相对路径或内部地址,直接赋给 coverImgUrl 会静默失败。
- 务必提前转成完整 HTTPS URL,哪怕只是加个域名前缀:
https://yourdomain.com${res.cover} - 避免使用 base64 图片,iOS 不支持 base64 作为
coverImgUrl - CDN 缓存可能导致封面更新延迟,可加时间戳参数:
coverImgUrl + '?t=' + Date.now()


















