1. 问题现象与初步排查58同城App作为国内头部生活服务平台其相机功能在二手房拍摄、求职简历上传等核心场景中扮演重要角色。近期我们收到用户反馈部分Android设备在调用App内相机时出现黑屏现象具体表现为点击拍照按钮后相机预览界面全黑无任何错误提示或崩溃日志设备返回键可正常退出相机界面问题集中在Android 9-11系统的小米、OPPO中端机型第一反应检查清单确认Camera权限是否正常获取AndroidManifest声明 运行时申请验证Camera.open()是否抛出异常检查SurfaceView/TextureView的预览尺寸设置测试系统原生相机应用是否正常工作实际排查中发现黑屏设备的系统相机功能正常且我们的App在首次安装时已正确获取CAMERA权限。这提示问题可能出在相机参数配置环节。2. 相机初始化流程深度解析2.1 标准Camera2 API调用链现代Android应用应使用Camera2 APIandroid.hardware.camera2而非已废弃的Camera API。完整调用流程如下// 1. 获取CameraManager服务 CameraManager manager (CameraManager) context.getSystemService(Context.CAMERA_SERVICE); // 2. 遍历可用摄像头前置/后置 String[] cameraIds manager.getCameraIdList(); String backCameraId cameraIds[0]; // 通常0为后置 // 3. 打开摄像头 manager.openCamera(backCameraId, new CameraDevice.StateCallback() { Override public void onOpened(NonNull CameraDevice camera) { // 4. 创建CaptureRequest.Builder CaptureRequest.Builder builder camera.createCaptureRequest(CameraDevice.TEMPLATE_PREVIEW); // 5. 设置预览Surface builder.addTarget(previewSurface); // 6. 创建CameraCaptureSession camera.createCaptureSession(Arrays.asList(previewSurface), new CameraCaptureSession.StateCallback() { Override public void onConfigured(NonNull CameraCaptureSession session) { // 7. 开始连续预览 session.setRepeatingRequest(builder.build(), null, null); } }, null); } }, null);2.2 黑屏问题的关键断点通过添加日志埋点我们发现黑屏设备在onConfigured回调后没有触发预览帧数据。这通常意味着Surface未就绪传递给createCaptureSession的Surface可能尚未完成初始化分辨率不兼容请求的预览尺寸与设备支持尺寸不匹配HAL层异常Camera Hardware Abstraction Layer存在兼容性问题3. 设备兼容性深度适配方案3.1 动态分辨率适配策略不同厂商设备支持的预览尺寸差异巨大。正确做法是// 获取设备支持的输出尺寸 StreamConfigurationMap map characteristics.get( CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP); Size[] previewSizes map.getOutputSizes(SurfaceTexture.class); // 选择最接近屏幕比例且不超过1920x1080的尺寸 Size optimalSize chooseOptimalSize(previewSizes, screenWidth, screenHeight, MAX_PREVIEW_WIDTH);常见坑点部分设备如小米Note 3对16:9以外的比例支持不佳超高分辨率如4K可能导致内存溢出SurfaceTexture的GL环境需要在UI线程初始化3.2 厂商特定Workaround针对问题机型我们实现了以下适配方案延迟初始化策略// 在SurfaceTexture可用后延迟100ms再创建Session surfaceTexture.setOnFrameAvailableListener(st - { handler.postDelayed(() - initCameraSession(), 100); });备用分辨率回退 当首选分辨率预览失败时自动尝试以下备选方案1280x720 (720P)1920x1080 (1080P)设备原生传感器分辨率厂商白名单机制// 针对已知问题机型启用特殊处理 if (Build.MANUFACTURER.equalsIgnoreCase(xiaomi) Build.MODEL.contains(Redmi Note)) { enableXiaomiWorkaround(); }4. 高级诊断与日志收集4.1 Camera2特性检查清单在初始化前应验证设备能力CameraCharacteristics characteristics manager.getCameraCharacteristics(cameraId); // 检查硬件支持级别 Integer hardwareLevel characteristics.get( CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL); if (hardwareLevel INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY) { // 需要降级到Camera API } // 检查是否支持自动对焦 int[] afModes characteristics.get( CameraCharacteristics.CONTROL_AF_AVAILABLE_MODES); boolean hasAutoFocus Arrays.stream(afModes) .anyMatch(mode - mode ! CONTROL_AF_MODE_OFF);4.2 关键性能指标监控通过CameraCaptureSession.CaptureCallback收集new CameraCaptureSession.CaptureCallback() { Override public void onCaptureStarted(...) { // 记录帧开始时间 } Override public void onCaptureCompleted(...) { // 计算帧处理耗时 } }异常情况处理连续3帧超时100ms触发降级策略持续丢帧自动降低分辨率硬件错误重启Camera实例5. 实战优化成果经过上述改进后58同城App相机模块的关键指标提升指标优化前优化后启动成功率82.3%99.6%首帧渲染时间1200ms450msOOM崩溃率0.15%0.02%用户投诉量/周573核心经验总结永远不要假设Camera API的行为一致性Surface生命周期比想象中复杂建议添加状态机控制厂商定制ROM可能修改HAL层默认行为在低端设备上30fps比60fps更稳定6. 延伸问题排查指南当遇到相机黑屏时建议按以下步骤排查基础检查确认AndroidManifest包含uses-permission android:nameandroid.permission.CAMERA /验证ContextCompat.checkSelfPermission()返回PERMISSION_GRANTED检查packageManager.hasSystemFeature(PackageManager.FEATURE_CAMERA_ANY)深度诊断# 通过ADB获取Camera服务日志 adb shell dumpsys media.camera厂商调试模式小米开发者选项→开启相机日志OPPO拨号盘输入*#800#→Camera测试替代方案验证// 尝试第三方相机库如CameraView implementation com.otaliastudios:cameraview:2.7.2在低光环境下建议额外检查是否启用了自动夜景模式导致处理延迟手动设置合理的ISO和曝光补偿值添加预览帧超时监控如3秒无数据则重启相机
Android相机黑屏问题排查与优化实践
1. 问题现象与初步排查58同城App作为国内头部生活服务平台其相机功能在二手房拍摄、求职简历上传等核心场景中扮演重要角色。近期我们收到用户反馈部分Android设备在调用App内相机时出现黑屏现象具体表现为点击拍照按钮后相机预览界面全黑无任何错误提示或崩溃日志设备返回键可正常退出相机界面问题集中在Android 9-11系统的小米、OPPO中端机型第一反应检查清单确认Camera权限是否正常获取AndroidManifest声明 运行时申请验证Camera.open()是否抛出异常检查SurfaceView/TextureView的预览尺寸设置测试系统原生相机应用是否正常工作实际排查中发现黑屏设备的系统相机功能正常且我们的App在首次安装时已正确获取CAMERA权限。这提示问题可能出在相机参数配置环节。2. 相机初始化流程深度解析2.1 标准Camera2 API调用链现代Android应用应使用Camera2 APIandroid.hardware.camera2而非已废弃的Camera API。完整调用流程如下// 1. 获取CameraManager服务 CameraManager manager (CameraManager) context.getSystemService(Context.CAMERA_SERVICE); // 2. 遍历可用摄像头前置/后置 String[] cameraIds manager.getCameraIdList(); String backCameraId cameraIds[0]; // 通常0为后置 // 3. 打开摄像头 manager.openCamera(backCameraId, new CameraDevice.StateCallback() { Override public void onOpened(NonNull CameraDevice camera) { // 4. 创建CaptureRequest.Builder CaptureRequest.Builder builder camera.createCaptureRequest(CameraDevice.TEMPLATE_PREVIEW); // 5. 设置预览Surface builder.addTarget(previewSurface); // 6. 创建CameraCaptureSession camera.createCaptureSession(Arrays.asList(previewSurface), new CameraCaptureSession.StateCallback() { Override public void onConfigured(NonNull CameraCaptureSession session) { // 7. 开始连续预览 session.setRepeatingRequest(builder.build(), null, null); } }, null); } }, null);2.2 黑屏问题的关键断点通过添加日志埋点我们发现黑屏设备在onConfigured回调后没有触发预览帧数据。这通常意味着Surface未就绪传递给createCaptureSession的Surface可能尚未完成初始化分辨率不兼容请求的预览尺寸与设备支持尺寸不匹配HAL层异常Camera Hardware Abstraction Layer存在兼容性问题3. 设备兼容性深度适配方案3.1 动态分辨率适配策略不同厂商设备支持的预览尺寸差异巨大。正确做法是// 获取设备支持的输出尺寸 StreamConfigurationMap map characteristics.get( CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP); Size[] previewSizes map.getOutputSizes(SurfaceTexture.class); // 选择最接近屏幕比例且不超过1920x1080的尺寸 Size optimalSize chooseOptimalSize(previewSizes, screenWidth, screenHeight, MAX_PREVIEW_WIDTH);常见坑点部分设备如小米Note 3对16:9以外的比例支持不佳超高分辨率如4K可能导致内存溢出SurfaceTexture的GL环境需要在UI线程初始化3.2 厂商特定Workaround针对问题机型我们实现了以下适配方案延迟初始化策略// 在SurfaceTexture可用后延迟100ms再创建Session surfaceTexture.setOnFrameAvailableListener(st - { handler.postDelayed(() - initCameraSession(), 100); });备用分辨率回退 当首选分辨率预览失败时自动尝试以下备选方案1280x720 (720P)1920x1080 (1080P)设备原生传感器分辨率厂商白名单机制// 针对已知问题机型启用特殊处理 if (Build.MANUFACTURER.equalsIgnoreCase(xiaomi) Build.MODEL.contains(Redmi Note)) { enableXiaomiWorkaround(); }4. 高级诊断与日志收集4.1 Camera2特性检查清单在初始化前应验证设备能力CameraCharacteristics characteristics manager.getCameraCharacteristics(cameraId); // 检查硬件支持级别 Integer hardwareLevel characteristics.get( CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL); if (hardwareLevel INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY) { // 需要降级到Camera API } // 检查是否支持自动对焦 int[] afModes characteristics.get( CameraCharacteristics.CONTROL_AF_AVAILABLE_MODES); boolean hasAutoFocus Arrays.stream(afModes) .anyMatch(mode - mode ! CONTROL_AF_MODE_OFF);4.2 关键性能指标监控通过CameraCaptureSession.CaptureCallback收集new CameraCaptureSession.CaptureCallback() { Override public void onCaptureStarted(...) { // 记录帧开始时间 } Override public void onCaptureCompleted(...) { // 计算帧处理耗时 } }异常情况处理连续3帧超时100ms触发降级策略持续丢帧自动降低分辨率硬件错误重启Camera实例5. 实战优化成果经过上述改进后58同城App相机模块的关键指标提升指标优化前优化后启动成功率82.3%99.6%首帧渲染时间1200ms450msOOM崩溃率0.15%0.02%用户投诉量/周573核心经验总结永远不要假设Camera API的行为一致性Surface生命周期比想象中复杂建议添加状态机控制厂商定制ROM可能修改HAL层默认行为在低端设备上30fps比60fps更稳定6. 延伸问题排查指南当遇到相机黑屏时建议按以下步骤排查基础检查确认AndroidManifest包含uses-permission android:nameandroid.permission.CAMERA /验证ContextCompat.checkSelfPermission()返回PERMISSION_GRANTED检查packageManager.hasSystemFeature(PackageManager.FEATURE_CAMERA_ANY)深度诊断# 通过ADB获取Camera服务日志 adb shell dumpsys media.camera厂商调试模式小米开发者选项→开启相机日志OPPO拨号盘输入*#800#→Camera测试替代方案验证// 尝试第三方相机库如CameraView implementation com.otaliastudios:cameraview:2.7.2在低光环境下建议额外检查是否启用了自动夜景模式导致处理延迟手动设置合理的ISO和曝光补偿值添加预览帧超时监控如3秒无数据则重启相机
