React Native iOS端3D模型无法加载问题求助（expo-three、react-fiber-three）

Expo-three 相关配置修复 #

• 资源路径与声明：iOS对本地资源的读取规则比Android严格，务必把3D模型文件（.glb/.gltf等）放在assets子目录下，同时在app.json的expo.assets数组里声明该路径：

  "assets": ["./assets/models/"]
  

  加载模型时必须通过Asset.fromModule获取正确的资源引用，不要直接写相对路径，示例：

  const asset = Asset.fromModule(require('./assets/models/your-model.glb'));
  await asset.downloadAsync();
  

• 版本兼容性：检查expo-three和当前Expo SDK的版本是否匹配，比如SDK 50对应expo-three@^8.0.0，版本不兼容很容易导致iOS端渲染失效。
• 权限配置：如果用到AR相关功能，必须在Info.plist中添加相机权限描述：

  <key>NSCameraUsageDescription</key>
  <string>需要相机权限来显示3D模型</string>
  

React-three-fiber（你提到的react-fiber-three应为笔误）iOS适配 #

• 依赖安装与Pod配置：确保已经安装react-native-webgl和@react-three/fiber/native，安装完成后进入ios目录执行pod install，检查Podfile.lock确认相关依赖已成功引入。
• 模型格式优化：iOS对压缩后的gltf模型支持有限，建议用未压缩的.glb格式，或者用glTF-Pipeline工具将模型转换为iOS兼容的版本。
• 容器尺寸设置：给Canvas组件明确设置宽高样式，避免因容器尺寸为0导致渲染空白：

  <Canvas style={{ flex: 1, width: '100%', height: '100%' }}>
    <primitive object={yourModel} />
  </Canvas>
  

通用排查技巧 #

• 查看Xcode日志：连接iOS设备或模拟器，打开Xcode的控制台，里面会显示模型加载失败的具体错误（比如文件找不到、格式解析错误），这是定位问题最快的方式。
• 测试基础渲染：先渲染一个简单的几何体（比如<Box />），确认渲染环境正常后再替换成目标模型，排除模型本身的问题。
• 清除缓存：执行expo r -c清除Expo缓存，iOS端删除应用后重新安装，避免旧资源缓存干扰。

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