Player

播放器

播放器基于 ArtPlayer + hls.js，封装在 src/components/player-shell.tsx，页面入口为 /watch 路由。

播放链接格式

/watch?source=custom_0&id=20717&index=0&title=流浪地球&sourceUrl=https://..
        └─数据源 key    └─影片 id   └─集数     └─标题        └─数据源地址（分享链接兜底）

• source + id 存在时：从 /api/detail 拉取剧集列表，index 指定当前集；
• 仅 url 参数时（直连分享）：直接播放该地址，无剧集列表；
• URL 即状态：刷新/分享/前进后退均无损。

功能

功能	说明
自动连播	单集结束 0.8s 后自动下一集；片尾自动清除该集进度
进度恢复	优先 URL position 参数，否则读 IndexedDB；>10s 且非片尾（95%）时恢复并提示"已从 XX:XX 继续播放"
换源	「切换资源」→ 跨源搜索同名影片 → 详情接口测速 → 按速度排序；切换后保留当前集数索引
集数倒序	倒序排列按钮，激活集自动滚动进可视区
广告过滤	自定义 hls.js loader 对 manifest/level 文本剔除 #EXT-X-DISCONTINUITY 广告分段（设置中可关）
错误恢复	HLS 网络错误自动 startLoad，媒体错误自动 recoverMediaError；多次失败显示错误面板
代理回退	直连致命网络错误（CORS/防盗链/分片被拒）时，自动改走 /api/proxy/（cookie 鉴权）重试一次
画中画 / 截图 / 网页全屏 / 倍速	ArtPlayer 原生能力

快捷键

按键	功能
空格	播放 / 暂停
← / →	快退 / 快进 5 秒
↑ / ↓	音量 ±10%
F	全屏切换
Alt + ← / Alt + →	上一集 / 下一集
双击	全屏切换
移动端长按	3 倍速播放（松开恢复）

播放进度与历史

• 进度：video:timeupdate 每 5 秒节流保存 + 暂停/页面隐藏/组件卸载时强制保存 → IndexedDB progress 表；
• 历史：进入播放页 2 秒后写入 history 表（仅 sourceKey + vodId + episodeIndex 定位信息），播放中增量更新进度；
• 剧集同步：从历史进入播放页时重新拉取详情，天然获得最新剧集列表（旧版需专门的同步逻辑）。

播放失败的排查顺序

1. 换源：点击「切换资源」，选择测速绿色（低延迟）的其他源；
2. 观察回退提示：若出现"直连失败，改用代理重试"说明该源分片有防盗链，代理通常可解；
3. 关广告过滤：个别源本身依赖 DISCONTINUITY 做多码率切换，误过滤会黑屏；
4. 直接验证：浏览器访问详情返回的 m3u8 地址确认源本身可用。