CameraX API全版本预览无显示问题排查求助

从日志核心错误TimeoutException: Cannot complete surfaceList within 5000可知，CameraX无法在规定时间内完成预览Surface的配置，导致预览无法正常启动。以下是针对性的解决步骤：

1. 确认PreviewView的布局有效性 #

确保布局中的PreviewView（即你代码中的viewFinder）有明确的尺寸约束，避免出现尺寸为0或无法测量的情况：

<!-- 示例布局，保证PreviewView占满父容器 -->
<androidx.camera.view.PreviewView
    android:id="@+id/viewFinder"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:layout_constraintTop_toTopOf="parent"
    app:layout_constraintBottom_toBottomOf="parent"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintEnd_toEndOf="parent" />

2. 确保相机权限已正确申请 #

在AndroidManifest.xml中声明必要权限：

<uses-permission android:name="android.permission.CAMERA" />
<uses-feature android:name="android.hardware.camera" />
<uses-feature android:name="android.hardware.camera.autofocus" />

在代码中动态申请权限，仅当权限通过后再启动相机：

private const val REQUEST_CAMERA_PERMISSION = 100

private fun checkCameraPermission() {
    if (ContextCompat.checkSelfPermission(this, Manifest.permission.CAMERA)
        != PackageManager.PERMISSION_GRANTED) {
        ActivityCompat.requestPermissions(
            this,
            arrayOf(Manifest.permission.CAMERA),
            REQUEST_CAMERA_PERMISSION
        )
    } else {
        startCamera()
    }
}

override fun onRequestPermissionsResult(
    requestCode: Int,
    permissions: Array<out String>,
    grantResults: IntArray
) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults)
    if (requestCode == REQUEST_CAMERA_PERMISSION) {
        if (grantResults.isNotEmpty() && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
            startCamera()
        } else {
            // 处理权限被拒绝的逻辑
        }
    }
}

3. 为Preview添加明确的配置参数 #

默认配置可能与设备不兼容，尝试指定目标宽高比或分辨率：

val preview = Preview.Builder()
    .setTargetAspectRatio(AspectRatio.RATIO_16_9) // 根据布局选择适配比例
    .setTargetResolution(Size(1920, 1080)) // 可选，设置具体分辨率
    .build()
    .also {
        it.setSurfaceProvider(binding.viewFinder.surfaceProvider)
    }

4. 调整相机启动的生命周期时机 #

避免在onCreate中过早启动相机，建议在onResume中执行，确保View已完成测量：

override fun onResume() {
    super.onResume()
    if (ContextCompat.checkSelfPermission(this, Manifest.permission.CAMERA)
        == PackageManager.PERMISSION_GRANTED) {
        startCamera()
    }
}

5. 检查设备相机占用状态 #

确保没有其他应用或后台进程占用前置相机（日志中id=1为前置相机），可尝试重启设备后再测试。

6. 统一CameraX依赖版本 #

确保所有CameraX组件使用同一稳定版本（当前最新稳定版为1.3.0）：

dependencies {
    implementation "androidx.camera:camera-core:1.3.0"
    implementation "androidx.camera:camera-camera2:1.3.0"
    implementation "androidx.camera:camera-lifecycle:1.3.0"
    implementation "androidx.camera:camera-view:1.3.0"
}

内容的提问来源于stack exchange，提问作者Saya