uniapp扫一扫在真机调试时无法调起摄像头？

Question

在使用 UniApp 开发扫码功能时，常见问题为真机调试时无法调起摄像头。该问题通常由权限配置缺失或平台差异导致。Android 和 iOS 需在 manifest 中正确声明相机权限，H5 端需启用 HTTPS 支持。此外，真机联调时若未开启 USB 调试或未信任设备，也可能导致调用失败。建议检查 `uni.scanCode()` 是否在安全域名下调用，并确认基座是否包含摄像头模块。自定义组件遮挡或页面层级异常也会阻止摄像头启动，需排查界面结构。

Answer 1

一、问题现象与初步排查

在使用 UniApp 开发扫码功能时，开发者常遇到真机调试无法调起摄像头的问题。该现象在 Android 和 iOS 平台表现不一致，H5 端则可能完全无响应。初步判断通常围绕以下几点展开：

• 是否已正确申请相机权限
• uni.scanCode() 是否被用户手势触发（如点击事件）
• H5 页面是否运行在 HTTPS 安全上下文中
• 真机是否开启 USB 调试模式并被电脑识别
• 设备是否信任当前开发主机（尤其 iOS）

这些问题构成了问题排查的起点，需逐一验证。

二、平台差异与权限配置深度解析

不同平台对相机访问的安全策略存在显著差异，必须分别处理：

平台	权限声明位置	所需权限项	特殊要求
Android	manifest.json → app-plus → permissions	"android.permission.CAMERA"	部分厂商 ROM 需手动授权
iOS	manifest.json → app-plus → usageDescription	NSCameraUsageDescription	描述语不能为空
H5	服务器配置	HTTPS + Secure Context	HTTP 下禁止调用媒体设备

三、代码实现与调用上下文检查

即使权限完备，调用方式不当仍会导致失败。以下是推荐的调用范式：

// 正确示例：确保在用户交互中调用
handleScan() {
  uni.scanCode({
    success: (res) => {
      console.log('扫码结果:', res.result);
    },
    fail: (err) => {
      console.error('扫码失败:', err);
      // 常见错误码分析见下文
    }
  });
}

注意：uni.scanCode() 必须由用户主动操作（如 tap）触发，不能在页面 onLoad 或异步回调中自动执行，否则会被浏览器或原生系统拦截。

四、基座构建与模块集成验证

使用 HBuilderX 运行至真机时，默认使用“标准基座”，但某些功能模块（如二维码扫描）可能未包含。需确认自定义基座是否集成了摄像头支持：

1. 打开 HBuilderX → 发行 → 原生 App-云打包
2. 勾选“自定义基座”并启用“二维码扫描”模块
3. 重新编译安装测试包
4. 若为离线打包，需确认 SDK 中已引入 UniScanner 组件

缺失模块将导致 scanCode 接口静默失败。

五、界面层级与组件遮挡分析

自定义组件或 CSS 层级异常可能导致摄像头预览层被遮挡或无法渲染。常见场景包括：

• 使用了 cover-view 或 map 等原生组件覆盖按钮
• z-index 设置混乱导致点击穿透失效
• 页面结构嵌套过深，影响事件冒泡

可通过以下流程图定位渲染问题：

graph TD A[点击扫码按钮] --> B{是否触发 handleScan?} B -- 是 --> C[调用 uni.scanCode()] C -- 成功 --> D[打开摄像头] C -- 失败 --> E[检查控制台错误] E -- "NotAllowedError" --> F[检查权限/HTTPS] E -- "NotReadableError" --> G[检查设备占用或基座模块] B -- 否 --> H[排查组件遮挡或事件绑定]

六、跨平台兼容性与安全域名策略

对于 H5 端，必须满足现代浏览器的安全策略：

• 站点需部署在 HTTPS 协议下
• 域名需加入 manifest 的“安全域名”列表
• 避免在 iframe 中调用摄像头（受 X-Frame-Options 限制）

在 manifest.json 中配置如下：

{
  "h5": {
    "security": {
      "domain": [
        "https://yourdomain.com"
      ]
    }
  }
}

未配置将导致 NotAllowedError 异常。

七、真机联调环境准备清单

为确保真机调试顺畅，建议按以下清单逐项核对：

项目	Android	iOS
USB 调试	✔ 开启	—
设备信任	—	✔ 电脑已信任
开发者模式	✔ 启用	✔ 已签名
网络连通性	✔ 与 PC 同网段	✔ USB 共享已建立

遗漏任一环节均可能导致调试通道中断。