故障排查

先确认播放器使用的是 SDK 返回的 playbackUrl，并且播放会话在播放器结束前没有被提前释放。下面的检查顺序适用于 Web、Android、iOS 和 Windows SDK。

快速定位

现象	优先检查	正常预期
播放失败	原始播放地址、源站鉴权、播放器错误日志	SDK 不应替换播放器的鉴权和解码逻辑
播放正常但没有加速	Key 状态、内容标识、网络权限、是否存在其他合格观看者	加速暂不可用时，播放仍可继续
Peer 数量为 0	应用、Key、contentId 和播放内容是否一致	没有其他相同内容的在线观看者时，0 是正常结果
控制台没有数据	会话是否正常结束、上报域名是否可达、查询时间范围	统计为异步处理，可能有短暂延迟
只有部分设备异常	平台版本、ABI、浏览器 Service Worker、网络策略	先按平台文档确认运行环境

TRACKER_UNAVAILABLE

这表示当前会话暂时无法建立加速连接。请依次检查：

1. 控制台中的 SDK Key 是否已启用，且绑定了正确的应用和平台。
2. 应用是否允许访问配置服务和加速服务使用的 HTTPS/WSS 地址。
3. 浏览器、企业网关、防火墙或 VPN 是否拦截了 WebSocket。
4. 播放地址是否仍可由播放器直接访问。

这类问题不会改变播放器的正常播放路径。修复 Key 或网络策略后，重新创建播放会话即可验证，不要在同一个失败会话上反复重试。

Peer 数量为 0

Peer 只有在以下条件同时满足时才会出现：

• 客户端使用同一应用下允许互通的 SDK Key；
• 播放的是同一份内容，且 contentId 稳定；
• 其他观看者此时仍在线，并且已请求相同内容；
• 客户端网络允许建立必要的连接。

动态签名 URL 不应直接作为内容标识。请给每个实际媒体内容传入稳定的 contentId，不要把每次变化的签名、时间戳或随机参数拼进标识。刚开始播放时 Peer 为 0 也很常见，等待其他观看者加入后再观察。

播放地址不生效

SDK 创建会话后会返回新的播放地址。请确认：

1. 播放器加载的是 session.playbackUrl，而不是仍保存的原始 URL。
2. URL 没有被业务层重新拼接、编码或替换。
3. 播放器请求所需的 Cookie、Authorization 或其他源站请求头已按平台 API 传入。
4. 播放地址的有效期覆盖整个播放过程；短时签名地址需要在业务层按源站规则刷新。

SDK 不会替客户生成媒体鉴权，也不会把源站 Token 发送给其他观看者。

401、403、421 或 503

• 401 / 403：通常是媒体 URL、Cookie、Authorization 或源站白名单校验失败。先用播放器之外的受控请求验证原始地址权限。
• 421：请求到达了不匹配的服务区域。检查部署入口、反向代理和租户区域路由，不要在客户端临时添加区域字段。
• 503 HOME_REGION_UNRESOLVED：服务端无法解析 SDK Key 的租户归属区域。检查 Key 是否来自当前环境，以及服务端区域配置是否完整。

修复服务端或源站配置后，请关闭旧会话并创建新会话。不要把这些响应当作播放器解码错误处理。

播放正常但控制台没有统计

统计通过后台链路异步处理，不要求业务代码直接调用统计接口。请确认：

• 会话确实调用了 close、dispose 或平台对应的释放方法；
• 播放器没有在初始化后立即销毁会话；
• 统计和配置域名没有被 CSP、代理或防火墙拦截；
• 控制台查询的应用、Key、平台和时间范围正确。

短暂延迟是正常的。不要因为统计尚未出现就重复初始化 SDK 或重放上报请求。

切换内容后仍显示旧数据

每路媒体内容都应创建独立播放会话。切换内容时按以下顺序处理：

1. 停止旧播放器并释放旧会话；
2. 使用新的 URL 和稳定的 contentId 创建会话；
3. 将新会话返回的 playbackUrl 交给播放器；
4. 将新的缓冲区和播放位置同步给新会话。

不要跨不同媒体内容复用同一个会话或 contentId。

MP4、MP3 或分段请求异常

MP4/MP3 直链加速需要播放器和源站支持单 Range 请求，并返回有效的 206 Partial Content 与 Content-Range。请检查：

• 源站或 CDN 没有移除 Range 请求头；
• Content-Length、Content-Range 和 MIME 类型正确；
• Web 端已按文档注册并启用同源 Service Worker；
• 没有扩展名的 URL 已显式设置正确的 MIME 类型。

条件不满足时，媒体仍可按普通方式播放，但不会启用对应的加速能力。

直播延迟或卡顿

先区分播放器缓冲问题和加速连接问题：

1. 记录播放器的缓冲时长、当前播放位置和清单刷新错误；
2. 确认直播会话使用稳定的直播 contentId，不要为每个分片创建会话；
3. 检查直播清单、分片和鉴权 URL 是否持续有效；
4. 对比关闭 P2P 后的同一播放地址，确认问题是否只在加速开启时出现。

不要为了追求更低延迟而关闭播放器自身的直播缓冲和重连策略。

安全与日志

提交问题时可以提供时间、平台、SDK 版本、脱敏后的 Key 后缀、contentId、会话 ID、错误码和统计摘要。请勿上传完整 SDK Key、源站 Token、Cookie、Authorization 请求头或用户个人信息。

提交工单前的最小信息

发生时间（含时区）：
平台与系统版本：
SDK 版本：
应用 / Key（脱敏）：
contentId：
原始媒体类型：HLS / DASH / MP4 / MP3
现象：播放失败 / Peer 为 0 / 无统计 / 卡顿 / 其他
错误码或日志（已脱敏）：
是否更换网络后复现：是 / 否
是否使用 SDK 返回的 playbackUrl：是 / 否