CameraX相机开发与拍照录实战 - 第1节

1.1 CameraX 架构与设计理念

CameraX 是 Google 推出的 Jetpack 相机库，旨在简化 Android 相机开发，同时保持设备兼容性。其核心架构基于 用例（UseCase） 模型，将相机操作抽象为预览、拍照、图像分析和视频录制四个维度，开发者只需声明用例并绑定生命周期，无需直接操作 Camera2 的多层回调。

1.1.1 CameraX 核心组件

组件	角色	生成输出
Preview	实时显示取景画面，绑定 SurfaceProvider	Surface / TextureView
ImageCapture	拍摄静态照片，支持不同分辨率与格式	JPEG / YUV_420_888
ImageAnalysis	逐帧交给处理分析器 (如 ML Kit)	ImageProxy
VideoCapture	录制视频（需绑定 Recorder）	MP4

1.2 开发环境要求与版本选择

1.2.1 最低系统与工具版本

• Android 5.0 (API 21) 及以上设备 — CameraX 使用 Camera2 API 作为底层，21 以上全覆盖。
• Android Studio Arctic Fox (2020.3.1) 或更高版本。
• Gradle 7.0+ 配合 AGP 7.0+。

1.2.2 CameraX 版本选择策略

自 1.0.0 稳定版 (2021.07) 起，CameraX 采用 1.x 系列。当前最新稳定版为 1.4.1（截至 2025 Q1）。
选择原则：

• 新项目直接使用最新稳定版，获得最优兼容性和扩展 API。
• 若需要 ML Kit 或 CameraX 扩展（人像/夜景），确保版本 ≥1.2.0。
• 若涉及视频录制功能，必须使用 ≥1.3.0（VideoCapture 正式稳定）。

1.3 创建 Android 项目模板与配置 Gradle 依赖

1.3.1 使用 Android Studio 创建空白 Activity 项目

1. 启动 Android Studio → New Project → Empty Views Activity。
2. 包名：com.example.cameraxdemo，最低 API：24（若要支持更老设备可设 21）。
3. 等待 Gradle Sync 完成。

1.3.2 添加 CameraX 依赖与仓库配置

在项目级 build.gradle.kts (或 build.gradle) 的 allprojects 或 dependencyResolutionManagement 中确保 google() 仓库已添加：

// settings.gradle.kts
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

在 app/build.gradle.kts 中添加 CameraX 核心依赖及可选扩展：

dependencies {
    // 核心
    implementation("androidx.camera:camera-core:1.4.1")
    implementation("androidx.camera:camera-camera2:1.4.1")
    implementation("androidx.camera:camera-lifecycle:1.4.1")
    implementation("androidx.camera:camera-view:1.4.1")

    // 可选扩展（人像/HDR等）
    implementation("androidx.camera:camera-extensions:1.4.1")

    // 视频录制（1.4+ 直接包含 VideoCapture，无需额外导入）
    // Audio 部分需额外引入
    implementation("androidx.camera:camera-video:1.4.1")
}

1.4 初始化 CameraProvider 与生命周期绑定

1.4.1 获取 ProcessCameraProvider

// 在 Activity 或 Fragment 的 onStart/onResume 中调用
val cameraProviderFuture = ProcessCameraProvider.getInstance(requireContext())
cameraProviderFuture.addListener(Runnable {
    val cameraProvider: ProcessCameraProvider = cameraProviderFuture.get()
    // 在此处绑定用例
}, ContextCompat.getMainExecutor(requireContext()))

1.4.2 绑定预览与拍照用例到生命周期

val preview = Preview.Builder().build()
val imageCapture = ImageCapture.Builder().build()

val cameraSelector = CameraSelector.DEFAULT_BACK_CAMERA

// 将预览与 lifecycleOwner 绑定
val camera = cameraProvider.bindToLifecycle(
    lifecycleOwner,
    cameraSelector,
    preview,
    imageCapture
)

1.5 常见错误与调试方法

错误现象	原因	解决方案
黑色预览画面	未为 Preview 设置 SurfaceProvider	调用 preview.setSurfaceProvider(previewView.surfaceProvider)
CameraXConfig 找不到	缺少 camera-camera2 依赖	添加 camera-camera2
安装后闪退，日志提示CameraAccessException	未在 Manifest 声明相机权限	添加 <uses-permission android:name="android.permission.CAMERA"/> 并运行时请求
视频录制无法启动	未添加 camera-video 依赖或 API 版本不足	确认依赖版本 ≥1.3.0，且 targetSdk 适配合适

1.6 性能与稳定性优化基线

• 异步初始化：始终使用 ListenableFuture 绑定，避免主线程阻塞。
• 取消绑定：在 onStop / onPause 中调用 cameraProvider.unbindAll() 释放 Camera2 资源。
• 配置最小分析帧率：ImageAnalysis.Analyzer 设置 STRATEGY_KEEP_ONLY_LATEST，避免积压。
• 预览尺寸匹配：使用 PreviewView 的 scaleType 为 FIT_CENTER 保证画面完整。

1.7 本章小结与动手清单

• ✅ 理解 CameraX 四大核心用例：Preview / ImageCapture / ImageAnalysis / VideoCapture。
• ✅ 配置 Gradle 依赖，选择最新稳定版 (如 1.4.1)。
• ✅ 实现 ProcessCameraProvider 初始化 → bindToLifecycle 绑定流程。
• ✅ 处理常见权限与 SurfaceProvider 错误。
• ✅ 应用性能优化基线：异步、解绑、ITAR/LATEST 策略。