播放与后台
后台不播放 / 应用被杀
- 确认播放时存在 MediaStyle 媒体通知——前台服务依赖它保活，划掉通知即停止服务；
- 加入电池优化白名单并在最近任务中锁定卡片；
- 各厂商 ROM 的后台管理比原生 Android 更激进，关闭针对本应用的「智能省电」「睡眠待机优化」。
提示 embedded API is not ready
内嵌 Node 运行时未就绪时，接口调用会直接 reject 抛出 [bridge] embedded API is not ready，而非返回软失败：
- 偶发于冷启动后的头几秒，稍等重试即可；
- 频繁出现时检查设备剩余存储与内存；
- 可用
GET /api/health（返回{ ok, nodeReady }）确认就绪状态，详见 外部 API。
切歌慢 / 切歌失败
- 播放地址由
PlaybackUrlResolver对多个音源候选并行竞速得出，网络极差时竞速整体变慢； - 确认内嵌 Node 已就绪（见上条）；
- 插件音源解析失败会回落到其他候选，卡片状态为「错误」时见 插件使用。
没有声音
- 检查媒体音量而非铃声音量；
- 蓝牙连接时音频路由到蓝牙设备，断开后回落扬声器；
- 音频源必须是有效 URL（如
/api/cache/song/play），传入裸文件路径或file://会直接失败——若由第三方插件提供地址，请检查插件实现。
进度 / 频谱在后台不更新
这是预期行为：App 切到后台或 WebView 不可见时，高频进度与频谱推送会静默以节省功耗（webViewVisible 机制），回到前台即恢复。
通知栏按钮无响应
- 收藏等依赖登录态的操作在未登录时无效属正常；
- 系统媒体面板仅提供标准命令集（上一首 / 播放暂停 / 下一首）。
横屏沉浸式无法退出
上滑或返回会退出沉浸模式（同时恢复状态栏与手势导航条）。若界面无响应，可用最近任务划掉应用。