📚 课程目录第3章 CameraX依赖配置

3. CameraX 依赖配置：在 build.gradle 中添加 CameraX 依赖、同步项目、权限声明

在开始编写自定义相机代码之前，必须先将 CameraX 库集成到项目中。本章将详细讲解依赖配置的完整流程，包括版本选择、Gradle 配置、项目同步以及 Android 权限声明。正确的依赖配置是 CameraX 正常工作的基础，任何遗漏或版本不匹配都可能导致运行时崩溃或功能异常。

3.1 CameraX 依赖架构概览

CameraX 是一个由多个模块组成的 Jetpack 库，每个模块负责不同的功能层次。理解模块间的依赖关系有助于按需引入，避免包体积膨胀。

  核心模块说明： CameraX 采用分层架构设计，核心层提供生命周期绑定与用例抽象，扩展层提供高级特性如扩展效果和相机切换。

3.2 在 build.gradle 中添加依赖

CameraX 依赖需要添加到模块级别的 build.gradle 文件中（通常是 app/build.gradle）。以下是最小化依赖配置，仅包含核心模块和生命周期集成。

版本策略： 建议使用最新的稳定版本。截至 2025 年，推荐使用 1.4.1 或更高版本。请始终参考官方版本发布页获取最新版本号。

// app/build.gradle
android {
    // 确保 compileSdk 至少为 34
    compileSdk 34

    defaultConfig {
        // minSdk 至少为 21 (Android 5.0)
        minSdk 21
        targetSdk 34
        // ...
    }
}

dependencies {
    // CameraX 核心库
    def camerax_version = "1.4.1"

    // 1. 核心库：提供 CameraX 基础 API
    implementation "androidx.camera:camera-core:${camerax_version}"

    // 2. Camera2 适配层：必须依赖，连接 CameraX 与系统 Camera2 API
    implementation "androidx.camera:camera-camera2:${camerax_version}"

    // 3. 生命周期集成：将 CameraX 绑定到 Activity/Fragment 生命周期
    implementation "androidx.camera:camera-lifecycle:${camerax_version}"

    // 4. 视图组件：提供 PreviewView 用于相机预览
    implementation "androidx.camera:camera-view:${camerax_version}"

    // 5. (可选) 扩展效果：人像、HDR、夜景等
    implementation "androidx.camera:camera-extensions:${camerax_version}"
}

3.3 依赖版本与兼容性对照

不同版本的 CameraX 对 compileSdk、minSdk 以及 Kotlin 版本有明确要求。下表列出了常用版本的兼容性矩阵。

CameraX 版本	最低 compileSdk	最低 minSdk	推荐 Kotlin 版本	主要变更
1.0.0	28	21	1.4.0	首个稳定版
1.1.0	30	21	1.5.0	新增扩展效果
1.2.0	31	21	1.6.0	改进性能
1.3.0	33	21	1.8.0	新增 HDR 支持
1.4.1	34	21	1.9.0	当前推荐稳定版

3.4 同步项目

添加依赖后，需要执行 Gradle 同步以下载库文件。同步方式有两种：

手动同步： 点击 Android Studio 工具栏中的 "Sync Now" 按钮（通常出现在修改 build.gradle 后的提示栏中）。
菜单同步： 选择 File → Sync Project with Gradle Files。

常见同步失败原因：

网络问题导致无法下载依赖（建议使用国内镜像仓库，如阿里云 Maven）。
compileSdk 版本低于 CameraX 要求（请升级到 34 或更高）。
Kotlin 版本过低（请升级到 1.9.0 或更高）。
Gradle 插件版本不兼容（建议使用 Gradle 8.2+ 和 AGP 8.1+）。

3.5 Android 权限声明

CameraX 需要相机权限才能运行。在 AndroidManifest.xml 中声明权限是强制步骤，缺少权限会导致应用在运行时崩溃或无法打开相机。

<!-- AndroidManifest.xml -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.cameraapp">

    <!-- 相机权限：必须声明 -->
    <uses-permission android:name="android.permission.CAMERA" />

    <!-- (可选) 存储权限：如果保存照片/视频到外部存储 -->
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"
        android:maxSdkVersion="28" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"
        android:maxSdkVersion="32" />

    <!-- (可选) 录音权限：如果录制视频需要音频 -->
    <uses-permission android:name="android.permission.RECORD_AUDIO" />

    <!-- 声明相机硬件特性：非必需，但建议声明 -->
    <uses-feature android:name="android.hardware.camera" android:required="true" />

    <application ...>
        <!-- 应用组件 -->
    </application>
</manifest>

  权限最佳实践：
  uses-feature 声明： 设置 android:required="true" 可让 Google Play 过滤掉没有相机的设备。如果应用也支持无相机设备（如平板），则设为 false。
运行时权限： Android 6.0+ 需要动态请求相机权限，仅声明 Manifest 不够。下一章将实现运行时权限请求逻辑。
存储权限限制： Android 10+ 推荐使用 MediaStore 或 SAF，不再需要 WRITE_EXTERNAL_STORAGE。对于 Android 11+，该权限已废弃。

3.6 权限声明流程示意

以下 SVG 图展示了从权限声明到运行时请求的完整流程，帮助理解权限体系在 CameraX 应用中的位置。

3.7 验证配置是否成功

完成依赖添加和权限声明后，可以通过以下方式验证配置是否正确：

Gradle 控制台： 同步成功后，控制台输出 BUILD SUCCESSFUL，无红色错误信息。
External Libraries： 在 Android Studio 的 Project 视图下，展开 External Libraries，应能看到 androidx.camera:camera-core-1.4.1 等库。
快速测试： 在 Activity 的 onCreate 中临时添加 ProcessCameraProvider.getInstance(this) 调用，编译运行不崩溃即表示依赖配置成功。

避坑指南：

不要同时引入多个版本的 CameraX 模块，确保所有模块版本号一致。
如果使用 Kotlin 协程，建议同时引入 kotlinx-coroutines-android 以配合 CameraX 异步 API。
在 build.gradle 中启用 Java 8+ 支持：compileOptions { sourceCompatibility JavaVersion.VERSION_1_8; targetCompatibility JavaVersion.VERSION_1_8 }。

3.8 本章小结

至此，CameraX 依赖配置已全部完成。你已掌握：

CameraX 模块架构与各模块职责
在 build.gradle 中正确添加依赖并同步项目
版本兼容性矩阵与选择策略
AndroidManifest 权限声明与运行时权限流程