2. 项目环境搭建：添加CameraX依赖、Compose版本要求、minSdk配置、权限声明

本章聚焦CameraX与Jetpack Compose协同开发的前置工程环境配置。一个稳定的依赖版本组合、正确的minSdk以及完整的权限声明是后续所有功能实现的基础。以下按照Android Studio新项目模板逐步说明。

2.1 依赖版本对应关系

CameraX与Compose存在隐式版本依赖：Compose BOM 管理UI工具包版本，CameraX BOM管理相机库版本。两者需通过AGP和Kotlin版本间接对齐。下表列出经过验证的稳定组合：

2.2 模块级 build.gradle（或build.gradle.kts）配置

以Kotlin DSL为例，在 app/build.gradle.kts 的 dependencies 块中添加CameraX和Compose依赖。CameraX BOM自动拉取内部子库兼容版本。

android {
    compileSdk = 34
    defaultConfig {
        minSdk = 21
        targetSdk = 34
        ...
    }
    buildFeatures {
        compose = true
    }
    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.10"
    }
}

dependencies {
    // Compose BOM
    val composeBom = platform("androidx.compose:compose-bom:2024.02.00")
    implementation(composeBom)
    implementation("androidx.compose.ui:ui")
    implementation("androidx.compose.ui:ui-graphics")
    implementation("androidx.compose.ui:ui-tooling-preview")
    implementation("androidx.compose.material3:material3")
    debugImplementation("androidx.compose.ui:ui-tooling")

    // CameraX BOM
    val cameraxBom = platform("androidx.camera:camera-bom:1.3.1")
    implementation(cameraxBom)
    implementation("androidx.camera:camera-camera2")
    implementation("androidx.camera:camera-lifecycle")
    implementation("androidx.camera:camera-view")

    // 生命周期库（CameraX lifecycle 需要）
    implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.7.0")
    implementation("androidx.lifecycle:lifecycle-runtime-compose:2.7.0")
}

2.3 minSdk 配置详解

CameraX要求 minSdk = 21（Android 5.0）。若项目原本支持更低版本（如API 19），需在 app/build.gradle.kts 中提升。原因：CameraX底层依赖API 21引入的camera2接口。低于21的设备无法使用CameraX，必须降级到Camera1（不在本课程范围内）。

defaultConfig {
    minSdk = 21
}

2.4 AndroidManifest 权限声明

CameraX运行时需要以下权限（Android 10起存储权限可选，但相机权限必须声明）：

<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO"
    android:maxSdkVersion="29" />
<uses-feature android:name="android.hardware.camera" android:required="true" />
<uses-feature android:name="android.hardware.camera.autofocus" android:required="false" />

RECORD_AUDIO 仅在录制视频时需要；maxSdkVersion="29" 表示Android 10及以上系统不再需要显式此权限（改用麦克风独立权限）。uses-feature 声明用于Google Play过滤无相机设备。

2.5 运行时权限请求（Compose侧）

在Compose中使用 rememberLauncherForActivityResult 结合 ActivityResultContracts.RequestPermission() 请求CAMERA。以下是一个典型请求片段：

@Composable
fun CameraPermissionRequest(onGranted: () -> Unit) {
    val context = LocalContext.current
    val permission = android.Manifest.permission.CAMERA
    var permissionGranted by remember { mutableStateOf(false) }

    val launcher = rememberLauncherForActivityResult(
        contract = ActivityResultContracts.RequestPermission()
    ) { isGranted ->
        permissionGranted = isGranted
        if (isGranted) onGranted()
    }

    LaunchedEffect(Unit) {
        if (ContextCompat.checkSelfPermission(context, permission) ==
            PackageManager.PERMISSION_GRANTED) {
            permissionGranted = true
            onGranted()
        } else {
            launcher.launch(permission)
        }
    }
}

2.6 项目环境依赖流程总览

下面的SVG图展示了从项目创建到运行前需完成的环境配置步骤，以及各配置项之间的依赖关系：

2.7 常见配置错误与调试方法

• 错误：Unresolved reference: camera-bom — 检查项目settings.gradle.kts中是否配置了 google() 仓库，且mavenCentral也需包含。
• 错误：Your minSdkVersion is 19, but the library has a minSdkVersion of 21 — 提升minSdk到21或使用多flavor方案。
• 错误：Cannot inline bytecode built with JVM target 1.8 — Kotlin JVM target需设为17，在 compileOptions 和 kotlinOptions 中统一。
• 运行时权限弹窗不出现 — 真机请检查是否在设置中手动拒绝了权限；模拟器需在Extended Controls中开启Camera。