第1章 环境搭建与项目初始化

本章将完成 Jetpack Compose 相机预览 项目的环境准备。环境搭建的正确性直接影响后续 CameraX + Compose 预览的编译与运行。本章覆盖 Android Studio 配置、Compose 项目创建、CameraX 依赖引入、Gradle 同步验证四个步骤，并在最后提供常见错误排查清单。

1.1 环境总览与原理说明

Jetpack Compose 相机预览的核心架构是 CameraX Lifecycle + PreviewView + AndroidView 桥接。CameraX 作为相机生命周期控制器，PreviewView 提供原生 Surface，通过 AndroidView 嵌入到 Compose 树中。整个预览链条依赖正确的编译环境、CameraX 版本、以及 androidx.camera:camera-view 库的引入。

原理要点：CameraX 1.2+ 支持 PreviewView 的 implementationMode 为 COMPATIBLE / PERFORMANCE；Compose 侧通过 AndroidView 包裹，将 PreviewView 转换为可组合组件。
🔧 环境搭建流程 Android Studio 2023+ 新建 Empty Compose Activity 添加 CameraX 依赖 Gradle Sync & 编译 运行验证相机预览 ⚠️ 关键检查点 AGP 8.0+ / Kotlin 1.9+ / minSdk 21+ / compileSdk 34+

1.2 实现流程

  1. 安装/更新 Android Studio：推荐 Hedgehog (2023.1.1) 或更高版本，内置 Kotlin 1.9+ 插件。
  2. 创建项目：选择 Empty Compose Activity（或 Empty Activity 后手动添加 Compose 配置）。
  3. 配置 Gradle 文件：在 app/build.gradle.kts 中添加 CameraX 依赖及 androidx.camera:camera-view。
  4. 同步项目：点击 Sync Now，等待下载依赖。
  5. 编写最小验证代码：在 MainActivity 中嵌入 AndroidView(PreviewView(context))，确保编译通过。
  6. 真机运行：连接 Android 10+ 设备，请求相机权限，基础预览可用。

1.3 关键配置与代码

1.3.1 AGP & Kotlin 版本

确保项目级 build.gradle.kts 使用不低于以下版本：

// projects/build.gradle.kts
plugins {
    id("com.android.application") version "8.2.0" apply false
    id("org.jetbrains.kotlin.android") version "1.9.21" apply false
}

1.3.2 Compose 编译配置

// app/build.gradle.kts
android {
    compileSdk = 34
    defaultConfig {
        minSdk = 21
        targetSdk = 34
    }
    buildFeatures {
        compose = true
    }
    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.7"
    }
}

1.3.3 CameraX 依赖（核心）

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

    // CameraX
    val cameraxVersion = "1.3.1"
    implementation("androidx.camera:camera-core:${cameraxVersion}")
    implementation("androidx.camera:camera-camera2:${cameraxVersion}")
    implementation("androidx.camera:camera-lifecycle:${cameraxVersion}")
    implementation("androidx.camera:camera-view:${cameraxVersion}")
}

1.3.4 AndroidManifest 权限

<!-- AndroidManifest.xml -->
<uses-feature android:name="android.hardware.camera" android:required="true"/>
<uses-permission android:name="android.permission.CAMERA"/>

1.4 调试与验证

  • Gradle 控制台：查看 BUILD SUCCESSFUL 字样，无红色错误。
  • Dependencies 窗口：双击 Shift → Enter dependencies，确认 androidx.camera:camera-view:1.3.1 出现。
  • 代码编译测试：在 ViewModel 中直接引用 ProcessCameraProvider 不报红。

1.5 常见错误及解决方案

错误现象原因解决方案
Cannot resolve symbol 'PreviewView'未添加 camera-view 依赖检查 implementation("androidx.camera:camera-view:...")
Compile SDK version 33compileSdk 低于 CameraX 要求提升至 compileSdk = 34 并更新对应依赖
minSdk 19 导致 CameraX 错误CameraX 1.3+ 要求 minSdk 21设置 minSdk = 21
Kotlin compiler extension version mismatchcomposeOptions 版本与 Kotlin 不匹配使用 Compose BOM 自动管理，或对照 官方兼容表
运行时 java.lang.SecurityException: Camera未动态请求 CAMERA 权限在 Activity 中写 rememberLauncherForActivityResult 请求权限
💡 性能建议：使用 compileSdk = 34 + targetSdk = 34 可享受 CameraX 1.3 的 imageAnalysis 背压优化；避免在 build.gradle.kts 中混用不同版本的 CameraX 依赖。

1.6 部署前检查清单

  • 真机系统 Android 10 (API 29) 以上（CameraX 最低要求）
  • 已授予相机权限（可先手动授权验证）
  • 项目 build 变更为 debug，选择目标设备
  • 关闭 Android Studio 缓存（可选）：File → Invalidate Caches...
← 上一章 📖 返回目录 下一章 →