React Native开发Meta Quest应用遇@reactvision/react-viro黑屏问题求助

问题概况 #

使用@reactvision/react-viro（原Viro分支维护版）开发Meta Quest AR/VR应用时，Android 14设备及Meta Quest 3均出现黑屏现象；官方启动模板也卡在加载界面。AR模式下onInitialized回调返回state=1（对应ViroTrackingStateConstants.TRACKING_UNAVAILABLE，AR相机位置不可用）、reason=1（追踪状态无限制）。尝试过viroreact-oculus项目，但缺乏可用文档支持。

排查修复步骤 #

1. 补全权限配置 #

确保AndroidManifest.xml中添加完整的AR/相机权限，Android 14需额外添加通知权限：

<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<uses-feature android:name="android.hardware.camera.ar" android:required="true" />

同时主动在代码中请求权限，避免依赖库自动请求的延迟：

import { PermissionsAndroid, useEffect } from 'react-native';

const requestPermissions = async () => {
  const result = await PermissionsAndroid.requestMultiple([
    PermissionsAndroid.PERMISSIONS.CAMERA,
    PermissionsAndroid.PERMISSIONS.POST_NOTIFICATIONS,
  ]);
  return result[PermissionsAndroid.PERMISSIONS.CAMERA] === 'granted';
};

// 组件挂载时执行权限请求
useEffect(() => {
  requestPermissions();
}, []);

2. 校验包版本兼容性 #

旧版本@reactvision/react-viro可能未适配Android 14和Meta Quest 3，先尝试升级到最新稳定版：

npm install @reactvision/react-viro@latest

若最新版仍有问题，可回退到已知兼容的版本（如2.23.0，需自行验证适配性）。

3. Meta Quest 专属配置 #

• 确认Quest 3已开启开发者模式，USB连接电脑时选择「文件传输」模式，避免ADB连接异常；
• 在AndroidManifest.xml中添加Oculus识别meta-data，确保系统识别为VR/AR应用：

<meta-data android:name="com.oculus.vr.focusaware" android:value="true" />
<meta-data android:name="com.samsung.android.vr.application.mode" android:value="vr_only" />

• 开启Quest设备空间感知功能：设置 > 系统 > 空间感知，确保「空间锚点」「环境理解」处于启用状态。

4. 处理追踪初始化异常 #

回调返回TRACKING_UNAVAILABLE但reason为无限制，大概率是相机初始化延迟或环境问题：

• 避免在过暗/过亮、无纹理的环境测试，确保周围有可识别的物体表面；
• 添加重试逻辑，延迟后重新尝试追踪初始化：

function onInitialized(state, reason) {
  console.log("onInitialized", state, reason);
  if (state === ViroTrackingStateConstants.TRACKING_UNAVAILABLE) {
    setTimeout(() => {
      setText("Retrying tracking...");
      // 若ViroARSceneNavigator提供重启方法可直接调用，否则可触发组件重新渲染
    }, 2000);
  } else if (state === ViroTrackingStateConstants.TRACKING_NORMAL) {
    setText("Hello World!");
  }
}

5. 查看原生日志定位根源 #

通过ADB拉取原生层日志，排查相机或AR服务的初始化错误：

adb logcat | grep Viro
adb logcat | grep ARCore

若日志出现ARCore not installed或Camera initialization failed，需确保Quest设备预装ARCore服务，Android 14设备可从应用商店手动安装。

6. 临时替代方案 #

若@reactvision/react-viro问题无法快速解决，可尝试官方维护的react-native-oculus库，直接对接Meta Quest的VR/AR能力，文档支持更完善：

npm install react-native-oculus

注意：该库仅支持Meta设备，无跨平台兼容性。

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