iOS 打包后使用 `react-native-video` 播放视频时出现崩溃如何排查问题

iOS 打包后使用 react-native-video 播放视频时出现崩溃，虽然“视频资源未正确打包”是可能原因之一，但结合常见实践和底层机制，更可能是原生依赖未正确链接或资源路径引用错误所致。以下是系统性排查方向和解决方案：

---

⚠️ 一、核心原因分析

1. 原生模块未正确集成（最常见）

   1. iOS 原生依赖缺失：react-native-video 需要原生端（Objective-C/Swift）的 RCTVideo 模块支持。若打包时未正确链接该模块，调用视频功能会直接崩溃。

   2. Podfile 配置错误：若使用 CocoaPods 管理依赖，需确保 Podfile 包含以下配置，否则 RCTVideo 不会被编译进应用：

      • pod 'react-native-video', path: '../node_modules/react-native-video'
        

      •     

2. 视频资源未打入 Bundle（需验证）

   1. 视频文件（如 MP4）需放在项目目录（如 ./assets/videos/），并通过 Metro 打包命令生成离线资源包：

      • react-native bundle --entry-file index.js --platform ios --dev false --bundle-output ./ios/main.jsbundle --assets-dest ./ios
        

      • 检查生成后的 ./ios 目录是否包含视频文件（位于 assets/../ 路径下）。

      • 若视频未出现在 assets 中，需检查：

        • 文件路径在 JS 代码中是否正确引用（如 require('./assets/video.mp4')）；

        • Metro 配置（metro.config.js）是否包含 assetExts: ['mp4', ...] 扩展名支持 。

3. 版本兼容性问题

   1. react-native-video 与 React Native 版本可能存在冲突（如 RN 0.60+ 需使用 react-native-video@5.x+）。

   2. 检查 package.json 中依赖版本，并尝试锁定版本：

      • "react-native-video": "5.2.1"
        

   3. 执行 yarn install --force 或重新链接库（npx react-native unlink react-native-video && npx react-native link）。

4. 线程或内存问题（较隐蔽）

   1. 视频解码消耗大量资源，可能因主线程阻塞或内存溢出崩溃。

   2. 在 Xcode 中开启 Debug > View Debugging → Rendering → Color Offscreen-Rendered 检查渲染性能。

---

🔍 二、关键排查步骤

1. 检查原生模块是否生效

   1. 在 Xcode 中打开项目，检查：

      • Libraries 目录下是否存在 RCTVideo.xcodeproj（若无，需手动链接）；

      • Build Phases > Link Binary With Libraries 是否包含 libRCTVideo.a。

2. 验证资源打包结果

   1. 解压生成的 .ipa 文件，检查 Payload/YourApp.app/assets/ 下是否存在视频文件。

   2. 若视频缺失，在 metro.config.js 中添加：

      • module.exports = {
          resolver: {
            assetExts: ['mp4', 'mov', ...] // 补充视频格式
          }
        };
        

3. 查看崩溃日志定位根源

   1. 通过 Xcode → Window → Devices and Simulators → View Device Logs 获取崩溃堆栈。

   2. 关键错误示例：

      • Undefined symbol: _OBJC_CLASS_$_RCTVideo → 原生模块未链接；

      • Could not load video at path: ... → 资源路径错误；

      • EXC_BAD_ACCESS → 内存问题（如视频尺寸过大）。

4. 测试基础功能

   1. 尝试播放远程视频（如 source={{uri: "https://example.com/video.mp4"}}），若可播放则问题在本地资源打包；若仍崩溃，问题在原生层 。

---

✅ 三、解决方案

1. 重新集成原生模块

   1. # 清除缓存并重装依赖
      cd ios && pod deintegrate && pod install --repo-update
      

2. 修复资源引用路径

   1. JS 代码中使用确定路径（避免动态拼接）：

      • <Video source={require('./assets/video.mp4')} />
        

3. 降级或更新库版本

   1. # 尝试稳定版本
      yarn add [email protected]
      

4. 优化内存管理

   1. 为视频组件添加 onError 回调捕获错误：

      • <Video onError={e => console.log("Video Error", e.error)} />
        

---

📊 iOS 视频资源支持参考表

项目	要求
支持格式	MP4、MOV（H.264 编码最佳）
资源路径	必须通过 require() 引入，直接使用 "./assets/video.mp4" 路径无效
Metro 配置	需在 metro.config.js 中扩展 assetExts 字段
Xcode 检查项	确认视频文件在 Copy Bundle Resources 列表中

若按上述步骤仍未解决，提供崩溃日志截图或文本，可进一步分析原生层错误（如 GPU 驱动兼容性问题）。大部分类似问题通过重新链接原生模块或修正资源路径即可解决 。