uniapp 扫码黑屏

问题描述

在 UniApp 开发中，调用扫码功能时出现黑屏现象，可能由设备权限、API 调用方式或环境配置问题导致。以下是常见原因及解决方法。

检查相机权限

确保应用已获取相机权限。在 manifest.json 中配置权限声明，Android 需添加以下代码：

"permission": {
  "android.permission.CAMERA": {
    "description": "用于扫码功能"
  }
}

iOS 需在 manifest.json 的 ios 节点下配置隐私描述：

"ios": {
  "privacyDescription": {
    "NSCameraUsageDescription": "需要相机权限以完成扫码"
  }
}

调用扫码 API 的正确方式

使用 uni.scanCode 时需注意回调处理。示例代码：

uni.scanCode({
  success: (res) => {
    console.log('扫码结果:', res.result);
  },
  fail: (err) => {
    console.error('扫码失败:', err);
  }
});

若未正确处理回调，可能导致界面无响应或黑屏。

检查运行环境

H5 环境限制：H5 端扫码依赖浏览器或 WebView 的相机支持，部分浏览器可能无法调用。建议在真机或原生平台（Android/iOS）测试。

调试工具问题：部分模拟器或开发工具可能不支持相机功能。尝试使用真机调试。

检查原生平台配置

Android：确认 AndroidManifest.xml 已包含相机权限（通常 UniApp 自动生成，但需检查是否被覆盖）。

iOS：确保 Xcode 工程中 Info.plist 包含 NSCameraUsageDescription 字段，否则审核可能被拒或功能异常。

处理黑屏的备选方案

若问题仍未解决，可尝试以下替代方案：

• 使用第三方扫码插件（如 uni-app 官方推荐的插件）。
• 检查项目依赖版本，确保 HBuilderX 和 uni-app SDK 为最新版本。

日志与错误捕获

通过 uni.getSystemInfo 获取设备信息，确认相机是否可用：

uni.getSystemInfo({
  success: (res) => {
    console.log('设备信息:', res);
  }
});

捕获扫码错误时，区分具体原因（如权限拒绝或硬件不支持）。

通过逐步排查权限、API 调用、环境兼容性及原生配置，可解决大部分扫码黑屏问题。