第二章 开发环境搭建与Gradle依赖配置

ExoPlayer 是一个高度模块化的 Android 媒体播放器库，其集成过程高度依赖 Gradle 构建系统的精确配置。本章将围绕 minSdkVersion、Java/Kotlin 版本、ExoPlayer 模块选择 和 依赖冲突解决 四个核心要点，从原理到实践搭建一个干净、可复现的开发环境。

2.1 minSdkVersion 与 Java/Kotlin 版本设定

minSdkVersion 直接决定了 ExoPlayer 模块中哪些 API 编配可用，同时影响应用的兼容范围和包体积。ExoPlayer 官方对 API 级别有明确的下限与推荐值。

Java 版本方面：ExoPlayer r2.17 及以后要求 Java 8+（Gradle 7.0+ 默认启用 Java 8 编译）。Kotlin 版本建议 1.6.0 以上，以兼容 ExoPlayer 官方发布的 Kotlin 扩展库（如 media2-session 的 Kotlin 绑定）。

2.2 ExoPlayer 模块选择：按需引入 vs 全量引入

ExoPlayer 采用模块化架构，核心库仅包含最基础的播放与渲染能力。实际项目应只引入必需的模块，避免包体积膨胀和 API 污染。下表列出常用模块及其场景。

典型的 build.gradle (app) 依赖配置如下：

dependencies {
    // 核心 + UI 必须
    implementation "androidx.media3:media3-exoplayer:1.3.1"
    implementation "androidx.media3:media3-ui:1.3.1"

    // 协议模块，按需添加
    implementation "androidx.media3:media3-exoplayer-hls:1.3.1"
    implementation "androidx.media3:media3-exoplayer-dash:1.3.1"

    // 如需解码扩展（如 FFmpeg）
    // implementation "androidx.media3:media3-decoder-ffmpeg:1.3.1"

    // 如需 Transformer
    // implementation "androidx.media3:media3-transformer:1.3.1"
}

2.3 依赖冲突解决

多个库（包括 ExoPlayer 的子模块）可能依赖相同库的不同版本，从而引发 Duplicate classes 或运行时 NoSuchMethodError。常见冲突源包括：Guava、Kotlin stdlib、AndroidX annotation、OkHttp 等。

2.3.1 诊断依赖树

在项目根目录执行以下命令输出完整依赖树，查找冲突：

./gradlew :app:dependencies --configuration releaseRuntimeClasspath

看到类似 com.google.guava:guava:30.1-jre -> 31.1-jre (*) 表示版本已升级。如果出现 conflicts 标记，需用 Gradle 策略处理。

2.3.2 常用解决方案

• force：在 app 的 configurations.all 中强制指定某版本。
• exclude：在特定依赖上排除传递依赖。
• resolutionStrategy：全局统一替换。

示例配置（app/build.gradle）：

configurations.all {
    resolutionStrategy {
        // 强制使用特定版本
        force "com.google.guava:guava:31.1-android"
        // 如果有重复类，可以排除某个模块传递的特定坐标
        eachDependency { details ->
            if (details.requested.group == 'org.jetbrains.kotlin'
                    && details.requested.name == 'kotlin-stdlib-jdk8') {
                details.useVersion '1.9.22'
            }
        }
    }
}

dependencies {
    implementation('androidx.media3:media3-exoplayer:1.3.1') {
        // 示例排除非必需传递依赖
        exclude group: 'com.google.guava', module: 'listenablefuture'
    }
}

2.4 调试与验证

搭建完成后，可通过以下步骤验证环境正确性：

1. 执行 ./gradlew :app:assembleDebug，观察无编译错误。
2. 在 Activity 或 Fragment 中实例化 ExoPlayer.Builder(context).build()，确保不抛 UninitializedPropertyAccessException。
3. 使用 adb shell dumpsys media.camera 或 logcat 过滤 ExoPlayerImpl 查看初始化日志。

常见错误及解决：

2.5 模块依赖关系总览

下图清晰展示了从应用层到 ExoPlayer 各核心、可选模块以及底层媒体框架的依赖流向：

通过上图可以看出，应用层直接依赖 exoplayer-ui（可选）和 exoplayer-core（必须），核心模块再向下对接解码器与各类数据源。协议模块（HLS、DASH 等）作为 MediaSource 的子实现被按需加载。整个架构清晰且拆解粒度细，这正是需要在 Gradle 中精确管理的根本原因。

2.6 性能与稳定性优化建议

• 开启 R8 混淆：在 proguard-rules.pro 中添加 ExoPlayer 的保留规则（官方仓库提供），避免运行时反射失败。
• 控制解码器数量：只添加需要的扩展解码器（如 FFmpeg 扩展会增加包体积和初始化耗时），使用 DefaultRenderersFactory 的扩展列表时可以按需注册。
• 版本固化：使用 gradle.properties 或 buildSrc 统一管理所有 ExoPlayer 模块版本，避免子模块间版本漂移。