网络故障导致长时间无法正常播放音乐，被误报为「未找到支持该平台的插件」并引发自动连切歌 #314

检查清单

• 我已检索仓库中所有的 Issues，确保我没有重复提交问题；或有相似 Issue，但我觉得我的情况不包含在那个相似 Issue 之内
• 我已经找到了可以复现这个问题的方法，并且写在了下面的「具体信息」中
• 此问题可以在我的设备和当前环境中稳定复现
• 此问题可以在最新版本 (Latest Release) 中复现
• 此问题是在我更新到当前版本后才出现的

环境信息

Commit: f6e2d7a
Date: 2026-09-02T15:16:52+08:00 (3 weeks ago)
Electron: 43.2.0
Chromium: 150.0.7871.129
Node.js: 24.18.0
V8: 15.0.1240245-electron.0
OS: Linux x64 7.2.6-1-cachyos

具体信息

问题描述

核心症状：长时间无法正常播放音乐——自 2026-09-23 凌晨起即无法使用，分两段：

1. 凌晨段（01:32:56–01:38:27）：netease.song_url API 连续 502（33 行
   netease.song_url failed: NeteaseRequestError: netease 502: fetch failed），
   取不到播放链接，未缓存歌曲无法播放；01:47 关闭播放器，白天未再使用。
2. 下午段（15:11–17:26，启动于 15:11:10）：日志记录 186 次 NETWORK_ERROR，
   期间仅 4 首成功播放（15:11:12 / 16:51:16 / 16:53:08 / 17:16:40），
   用户侧表现为歌一首接一首地切、始终不出声。

下午段更糟的是，播放器给出的反馈全部是错的：

• 每次失败弹出的 toast 都是**「未找到支持该平台的插件」**——全日志中
  NO_PLUGIN_AVAILABLE 相关记录为 0 行，该提示与实际情况完全无关（未使用任何音源插件）；
• 真正的网络错误文案「音源连接失败，请检查网络或更换音源」从未上屏
  （被 shouldSuppressLoadError 抑制），用户无从得知真实原因；
• 每次失败 1 秒后自动跳下一首，连续 5 次触发「连续播放失败次数过多」后停止队列，
  表现为自动连切歌。

下午段真实原因是网络层故障：本机无全局 IPv6，DNS 间歇性返回音源 CDN 的 AAAA 记录，
Rust 音频引擎（reqwest）连接失败（errno 101 ENETUNREACH）；同一故障窗口内评论区等
undici 请求完全正常（API 层通、音频 CDN 层不通）。修正系统 IPv6 优选配置（/etc/gai.conf）
并重启播放器后，17:44 起 0 报错、连续 22 首正常播放至今——播放器本身无损，
问题在于故障期间的错误归因与自动连跳，让用户完全无法定位真实原因。
凌晨段则是 API 层 502（详见 #286，我抓到的是 song_url 接口的同款现象）。

复现步骤

（针对下午段的误导提示 + 自动连切歌，可确定性复现）

1. 制造「API 通、音频 CDN 不通」的两层网络状态：

   # /etc/hosts 追加两行（阻断网易云音频 CDN 域名）
   127.0.0.1 m7.music.126.net
   127.0.0.1 m801.music.126.net
   

2. 启动 SPlayer-Next，播放在线歌曲（示例：https://music.163.com/#/song?id=1418950940 ）；

3. 观察 toast 文案与自动跳过行为，对照开发者工具 / 日志文件输出。

注：完全离线（API 层也不通）不会触发该误导提示（officialErrorCode 在 resolve 阶段被保留，
错误会正确上报为网络错误）；只有「API 通、音频流不通」才会走到插件兜底分支。

实际行为

1. 音乐无法播放（核心）：凌晨段取播放链接连续失败 33 次；下午段 186 次失败、
   仅 4 首成功，直到网络条件恢复且重启进程才恢复；
2. toast 显示「未找到支持该平台的插件」，日志中同时刻记录的却是 NETWORK_ERROR，
   两者不一致，且正确的网络错误文案从未展示给用户；
3. 以约 1 秒间隔自动 nextTrack()，连切 5 首后触发
   「连续播放失败次数过多」（MAX_CONSECUTIVE_FAILURES）终止队列。

预期行为

1. 网络故障时应展示真实的 NETWORK_ERROR 文案（音源连接失败，请检查网络或更换音源），
   让用户能定位到网络问题；
2. 「未找到支持该平台的插件」只应在插件确有问题时出现，不应作为网络失败的兜底提示；
3. 连续失败不应以 1 秒间隔自动连切歌（至少应提示、暂停或等待用户处理）；
4. 网络恢复后应能继续播放（实测重启后即完全恢复，期望免重启或给出明确指引）。

根因分析（下午段）

resolveTrackSource 解析链（对 /opt/SPlayer-Next/resources/app.asar 静态分析）：

1. 音频引擎加载失败 → reportLoadError 被 shouldSuppressLoadError 抑制
   （provider 为 official/plugin 时静默，重试期间不上屏）；
2. markRetryableSourceFailure 将官方源标记失败（skipOfficialOnline）→ 官方源被跳过；
3. officialErrorCode 为 null → resolveByPlugin 找到 0 个候选 → 抛出
   NO_PLUGIN_AVAILABLE「未找到支持该平台的插件」——这是解析链末端的兜底错误，
   与用户是否安装插件无关；
4. resolve 返回 null → status: "unresolved" → shouldSkip → skipOnFailure()：
   计数 +1，延迟 SKIP_ON_ERROR_DELAY_MS = 1000 后 nextTrack()；累计 5 次触发
   onQueueEnded()（MAX_CONSECUTIVE_FAILURES）——即自动连切歌；
5. 失败窗口内偶发成功会将 consecutiveFailures 清零，因此计数器反复从头开始。

凌晨段为 API 层 502（undici fetch failed），发生在解析链之前，与本段根因不同层，
但同样表现为无法播放。

日志

• 2026-09-23.log（附件 1）：会话启动于 15:11:10；15:11–17:26 共 186 行 NETWORK_ERROR；
  NO_PLUGIN / 中文 toast 文案 0 行；17:44 修复重启后 0 报错，22 首连续成功。
• 2026-09-22.log（附件 2）：日志文件按会话启动日命名、该会话跨零点——
  其中 09-23 01:32:56–01:38:27 共 33 行 netease.song_url failed: netease 502: fetch failed，
  01:47 应用退出。
• 2026-09-21.log：0 错误（故障起点确认为 09-23 凌晨）。

与既有 Issue / PR 的关系

• 偶发网易云 API 502 #286（偶发网易云 API 502）：凌晨段抓到的正是同款现象（接口为 song_url，
  偶发网易云 API 502 #286 为 playlist_detail），可作为其又一例复现证据；本 Issue 主诉的是 偶发网易云 API 502 #286 未覆盖的
  音频 CDN 层失败 + 错误归因 + 自动连跳，不包含在 偶发网易云 API 502 #286 之内。

附件

• 2026-09-21.log
• 2026-09-22.log
• 2026-09-23.log

⚠️ 声明

本 Issue 的日志统计、根因推断与代码路径定位由 AI 辅助完成（包含对 app.asar 打包产物的静态分析）。日志行数、时间戳、播放历史等均为本机实测数据，但对内部代码逻辑的解读可能存在误差——如结论与官方源码不符，以源码为准，欢迎维护者指正。