📚 课程目录第1章项目初始化与依赖配置

1. 项目初始化与依赖配置

本章围绕 ExoPlayer 与 Compose 集成的基础配置工作，涵盖版本选型、Gradle 依赖声明、SDK 级别设定以及兼容性检查。正确完成本章的初始化步骤是后续 29 个章节所有示例能够运行的前提。

1.1 ExoPlayer 版本选择原则

ExoPlayer 官方仓库托管在 androidx.media3 下（自 2022 年起从 com.google.android.exoplayer 迁移）。推荐使用 Media3 1.x 系列，理由如下：

Compose 原生友好：Media3 的 PlayerView 可直接嵌入 Compose AndroidView，无需额外封装；
生命周期感知：内置 Player 与 Lifecycle 绑定，避免内存泄漏；
持续维护：Media3 1.4.0+ 支持 HDR、无缝切换等新特性，且兼容 minSdk 21 以上的所有 Android 版本。

下表列出常用版本及其关键特性，供项目选型参考：

Media3 版本	发布日期	依赖包名	Compose 最低要求	备注
1.0.0	2022-12	androidx.media3:media3-exoplayer	BOM 1.2.0	初始稳定版
1.3.1	2024-02	同上	BOM 1.6.0	支持 HDR10+
1.4.0 (推荐)	2024-08	同上	BOM 1.7.0	无缝切换、性能优化

📌 选择提示：
若项目 Compose BOM 版本 ≤ 1.6.0，请使用 Media3 1.3.1；若已升级至 BOM 1.7.0+，则直接选用 1.4.0 以获得最佳兼容性。

1.2 Compose 兼容性要求

Compose 本身不强制绑定 ExoPlayer，但在集成时需要注意以下两点：

Kotlin 版本：Media3 1.x 要求 Kotlin 1.8.0+，Compose Compiler 需与 Kotlin 匹配。推荐 kotlin = "1.9.22" + compose-compiler = "1.5.10"。
Android Gradle Plugin (AGP)：需 ≥ 8.0，否则可能触发 compileSdk 与 targetSdk 的校验错误。

1.3 Gradle 依赖配置

在模块的 build.gradle.kts 中添加依赖。以下为完整配置片段：

// app/build.gradle.kts
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
}

android {
    namespace = "com.example.composeexoplayer"
    compileSdk = 34

    defaultConfig {
        applicationId = "com.example.composeexoplayer"
        minSdk = 24
        targetSdk = 34
        versionCode = 1
        versionName = "1.0"
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.10"
    }

    buildFeatures {
        compose = true
    }
}

dependencies {
    // Compose BOM
    val composeBom = platform("androidx.compose:compose-bom:2024.08.00")
    implementation(composeBom)
    implementation("androidx.compose.ui:ui")
    implementation("androidx.compose.material3:material3")
    implementation("androidx.activity:activity-compose:1.9.0")

    // Media3 ExoPlayer
    implementation("androidx.media3:media3-exoplayer:1.4.0")
    implementation("androidx.media3:media3-ui:1.4.0")        // 用于 PlayerView
    implementation("androidx.media3:media3-exoplayer-hls:1.4.0")  // HLS 支持（可选）
}

⚠️ 常见错误：
1. 若同时声明 com.google.android.exoplayer:exoplayer 旧依赖（2.x），会和 Media3 冲突。请确保项目内只使用一组 ExoPlayer 依赖。
2. media3-ui 中的 PlayerView 用于与非 Compose 场合；若纯 Compose 应用，可直接通过 AndroidView 包装 SurfaceView，无需添加 media3-ui。

1.4 minSdk 与 targetSdk 设定

根据 ExoPlayer Media3 官方文档及 Android 实际分发情况，推荐以下设定：

参数	推荐值	理由
`minSdk`	24（Android 7.0）	Coverage > 95%；Media3 1.4.0 需 API 23+，设为 24 可避免 Android 6.0 部分 `MediaCodec` 已知问题。
`targetSdk`	34（Android 14）	满足 Play Store 2024 年后的新提交要求，且 Compose 1.7.0+ 对 API 34 有优化的后台省电策略。
`compileSdk`	34	与 targetSdk 一致，避免编译时引用已废弃 API 导致 lint 警告。

1.5 初始化流程总览

下图为本章涉及的初始化任务及数据流向：

  🔧 验证方法：

  执行 ./gradlew assembleDebug 后，在 app/build/intermediates/ 下应当生成 ExoPlayer 的 .class 文件（如 com/google/android/exoplayer2/Player.class 或 androidx/media3/common/Player.class）。若成功，表明依赖配置正确。

1.6 常见错误与解决

Duplicate class 冲突
错误日志：Duplicate class com.google.android.exoplayer2.*。
原因：同时引入了 Media3 和旧版 com.google.android.exoplayer 依赖。
解决：全局搜索 com.google.android.exoplayer:，替换为 androidx.media3:。
minSdk 过老导致 API 缺失
错误日志：Call requires API level 21 (current min is 19)。
解决：将 minSdk 至少提升至 21（推荐 24）。
Compose Compiler 版本不匹配
编译错误：Kotlin compile warning: 'compose-compiler' version is not compatible with Kotlin。
解决：在 Compose Kotlin 兼容表中查找匹配版本，并同步调整 kotlinCompilerExtensionVersion。