Capacitor 3 React App iOS14.5下navigator.mediaDevices为undefined问题求助

核心原因 #

Capacitor 3 对 WebView 的默认安全策略做了调整，必须先拿到原生层面的相机权限授权，WebView 才会暴露navigator.mediaDevices和navigator.getUserMedia相关 API，同时需要开启媒体播放相关配置才能正常触发权限弹窗和调用相机。

解决步骤 #

1. 补全 Info.plist 配置 #

你已经添加了相机使用说明，若同时需要用到麦克风可以补充对应配置：

<dict>
  ...
  <key>NSCameraUsageDescription</key>
  <string>To scan barcodes</string>
  <!-- 可选：需要麦克风时添加 -->
  <key>NSMicrophoneUsageDescription</key>
  <string>需要使用麦克风完成音视频录制</string>
</dict>

2. 修改 Capacitor 全局配置 #

在capacitor.config.ts（或capacitor.config.json）中添加 iOS 专属配置，开启媒体 inline 播放，禁用媒体播放用户交互限制：

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  // 其他原有配置
  ios: {
    allowsInlineMediaPlayback: true,
    mediaPlaybackRequiresUserAction: false,
  }
};

export default config;

配置修改后需要重新执行npx cap sync ios同步配置到原生项目。

3. 先调用原生权限 API 申请授权 #

不要直接调用 Web API 申请权限，先通过 Capacitor 官方权限插件申请原生层面的相机权限：

1. 首先安装权限插件：

npm install @capacitor/permissions
npx cap sync ios

2. 业务代码中先申请权限，再调用 Web 相机 API：

import { Permissions, PermissionType } from '@capacitor/permissions';

const initCamera = async () => {
  // 先申请原生相机权限
  const permRes = await Permissions.request({
    permissions: [PermissionType.Camera]
  });

  if (permRes.camera === 'granted') {
    // 原生权限授权通过后，Web API 才会正常暴露
    try {
      const stream = await navigator.mediaDevices.getUserMedia({
        video: {
          facingMode: 'environment'
        }
      });
      // 后续绑定 video 标签播放流即可
      const video = document.querySelector('video');
      video.srcObject = stream;
      await video.play();
    } catch (err) {
      console.error('调用相机失败', err);
    }
  } else {
    alert('请授予相机访问权限后重试');
  }
}

常见排查点 #

• 修改配置后必须卸载原有 App 重新安装，避免权限缓存导致不弹申请框
• 确保 Capacitor 版本不低于 3.2.0，早期 3.0 版本存在 WebRTC 相关兼容 bug
• 不要在未添加allow="camera"属性的 iframe 中调用相机相关 API
• iOS 模拟器相机功能有限，真机测试优先，若使用模拟器确保已经开启了模拟相机权限

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