2. ExoPlayer 错误码体系总览

播放失败时，终端用户可能看到黑屏、无限加载转圈、播放器界面弹出“播放出错”弹窗，或直接闪退。作为排查者，第一步是准确采集异常数据——ExoPlayer 通过 Player.EventListener 的 onPlayerError 回调将错误暴露给应用层，所有错误都被包装为 ExoPlaybackException 对象。本章从现象出发，沿着“数据采集 → 异常分类 → 定位方法 → 修复动作 → 复测预防”的路径，搭建完整的错误码排查框架。

2.1 现象识别与数据采集

在应用层注册 Player.Listener（推荐新接口）或 EventListener，并在 onPlayerError 内记录异常详情：

Player.Listener listener = new Player.Listener() {
  @Override
  public void onPlayerError(PlaybackException error) {
    // 记录完整堆栈和错误码
    Log.e("Playback", "ExoPlayer error occurred", error);
    Log.e("Playback", "Error code: " + error.errorCode);
    Log.e("Playback", "Error message: " + error.getMessage());
  }
};

2.2 异常分类：ExoPlaybackException 的五种类型

通过 exoPlaybackException.type 可获取底层原因分类。下面是完整的分类故障树，每个叶节点代表一类典型故障：

2.3 原因定位：判断规则与排查表

拿到 ExoPlaybackException 后，使用以下三步快速缩小根因：

1. 读 type：exoPlaybackException.type 决定大类。
2. 读 errorCode：结合 PlaybackException.getErrorCode() 获取设备/厂商自定义错误。
3. 读 cause：exoPlaybackException.getCause() 通常包含原生 Throwable。

2.4 修复动作与复测

• TYPE_SOURCE → 增加重试策略、降级备用 URL、添加预缓存。
• TYPE_RENDERER → 降级软解、限制分辨率/码率、提供默认解码器兜底。
• TYPE_UNEXPECTED → 修复时序竞态、添加空判断、确保播放器状态机正确序列化。
• TYPE_REMOTE → 增加设备发现重试、提供 fallback 本地播放。
• TYPE_OUT_OF_MEMORY → 降低预加载缓存大小、使用 Glide/LruCache 限制 Bitmap 数量。

2.5 自定义错误映射

为了统一应用层错误码（例如对接后端报表），建议将 ExoPlaybackException 映射为业务业务错误码。以下是一个简单映射模板：

public class ExoErrorMapper {
  public static int toBusinessCode(ExoPlaybackException e) {
    switch (e.type) {
      case TYPE_SOURCE:
        return 1001; // 资源加载失败
      case TYPE_RENDERER:
        return 2001; // 解码器异常
      case TYPE_UNEXPECTED:
        return 3001; // 内部状态异常
      case TYPE_REMOTE:
        return 4001; // 远程播放异常
      case TYPE_OUT_OF_MEMORY:
        return 5001; // 内存不足
      default:
        return 9001; // 未知错误
    }
  }
}

同时可在 onPlayerError 中附带自定义 errorCode 上报至错误监控平台（如 Crashlytics、Sentry），用于预防性分析：定期统计各类型占比，提前发现大规模失败。

2.6 预防实践

• 在播放前检测设备解码能力（MediaCapabilities API 或 CodecCapabilities）。
• 使用 DefaultMediaSourceFactory.setThrowOnMissingFile(false) 避免因资源缺失直接崩溃。
• 设置合理的 LoadControl（如 DefaultLoadControl.Builder().setBufferDurationsMs(...)）防止 OOM。
• 实现 Player.Listener.onPlayerErrorChanged 捕获错误恢复状态，自动重试 2–3 次后弹出友好提示。