# 可疑但实际不是 Bug 的已知问题

这个文档记录一些在开发、测试或使用过程中看起来很像 Bug，但排查后确认并非前端业务逻辑缺陷的问题。

目标：

- 避免后续重复排查同类问题
- 帮助区分“代码回归”和“环境 / 资源链路问题”
- 给后续优化留下上下文

## 1. 在线歌曲点击时间轴跳转后，播放与可视化短暂停顿

### 表现

- 点击时间轴或歌词时间线后，播放器会出现一小段“卡住”的感觉
- 这段时间内：
  - 歌曲播放暂停推进
  - 歌词高亮暂停
  - visualizer 动画暂停
  - 看起来像整个 UI 卡死
- 在 DevTools 开启时，这个现象通常更明显
- 在本地歌曲上通常不明显或几乎不出现

### 初始怀疑

排查过程中曾怀疑这些方向：

- `VisualizerPartita` 的预热 / 缓存机制
- visualizer 的词级 `useMotionValueEvent` 订阅过多
- 最近的模块化重构引入了性能回归
- Electron 主进程被阻塞

这些方向都不是根因。

### 最终结论

问题根因是：

- 在线音频文件在远距离 seek 后的恢复速度受 CDN / 网络链路影响明显
- 更换到距离 API 更近、响应更快的 CDN 后，问题消失

因此这不是 visualizer 的逻辑 Bug，也不是本次前端架构重构引入的问题。

### 为什么看起来像 UI Bug

播放器中的歌词与可视化时间推进依赖 `audio.currentTime`。

当在线音频在 seek 后暂时无法立即恢复播放时：

- `audio.currentTime` 不推进
- 依赖它的歌词、进度和 visualizer 也会一起停止更新

所以用户看到的是“整个界面停住了”，但本质上是媒体 seek 恢复阶段的等待。

### 已确认的现象

- 这个问题在较早提交中已经存在，并不是最近一次 visualizer 模块化抽象引入的
- 本地歌曲 seek 基本不会出现同等级停顿
- 在线歌曲在较慢 CDN / 远距离链路下更容易复现
- 更换更快的 CDN 后问题解决

### 处理建议

- 优先检查在线音频资源的 CDN、区域延迟、Range 请求支持和响应速度
- 不要优先把它判定为 visualizer 回归
- 如果以后要优化体验，可以考虑：
  - seek 期间增加轻量状态提示
  - 区分“媒体恢复等待”与“前端渲染卡顿”

## 如何新增条目

建议新增条目时保持以下结构：

1. 表现
2. 初始怀疑
3. 最终结论
4. 为什么看起来像 Bug
5. 已确认现象
6. 处理建议
