播放与后台

后台不播放 / 应用被杀

确认已开启 通知栏音乐控制器（见权限与授权）——这是后台保活的前提；
加入电池优化白名单并锁定最近任务卡片；
确认播放时通知栏存在媒体通知；通知被划掉即代表前台服务停止。

允许与其他应用同时播放无效

该开关会重建音频引擎：

关闭（默认）：WebView 音频发声，系统独占音频焦点，播放时暂停其他应用；
开启：切换为原生 ExoPlayer 且 handleAudioFocus=false，不再抢占焦点。

切换后若行为未变化，请完全退出应用重进（引擎在启动时确定）。注意开启后不再响应「拔掉耳机暂停」之外的焦点丢失事件。

没有声音

检查媒体音量而非铃声音量；
关闭「允许与其他应用同时播放」重试，排除焦点冲突；
蓝牙设备连接时音频会路由到蓝牙，断开后自动回落到扬声器；
若仅个别歌曲无声，多为该曲解析到的播放地址失效，切歌或重试即可。

进度条跳变 / seek 回到 0:00

该问题已在 v3.0.0-rc.3 修复（含「跳转后 seek 位置丢失」「自动切下一首进度条跳到非 0:00」）。仍出现请升级到最新 Release 后再反馈。

切歌卡顿 / gapless 不生效

开启 下一首歌曲预载 可显著改善切歌间隔；
原生模式下原生侧会预解析队列窗口内的播放地址，WebView 冻结也不影响切歌；
网络极差时预解析失败会回落到实时解析，表现为切歌短暂停顿。

提示「内置 API 服务异常，正在自动恢复...」

内置网易云 API 每 30s 自检一次，连续两次失败即自动重启内嵌 Node 运行时。偶发一次属正常自愈；频繁出现时：

检查设备剩余存储与内存是否过低；
完全退出应用重进；
抓取 logcat 中 nodejs 相关输出后提交 Issue。

拔掉耳机自动暂停

这是预期行为（handleAudioBecomingNoisy），防止外放惊扰他人，暂无关闭选项。

通知栏按钮无响应

收藏按钮需要网易云登录态，未登录时点击无效属正常；
桌面歌词按钮需要先授予悬浮窗权限；
系统媒体面板（蓝牙 / 锁屏）只有上一首 / 播放暂停 / 下一首三个命令，这是 MediaSession 的标准命令集。

横屏沉浸式无法退出

上滑或点击返回会退出沉浸模式；系统返回键已被统一拦截处理（弹窗 / 菜单优先关闭）。若卡死，可用最近任务划掉应用。