在第三方库中集成 React Native Video：依赖声明、原生配置与插件体系实战指南

• 音视频
• 移动开发

本文面向需要在自研第三方库（如封装播放器组件、实现自定义 DRM、构建视频 SDK）中集成 React Native Video 的开发者，系统讲解 JS 层的依赖策略与导入方式、iOS 端 podspec 配置、Android 端 build.gradle 依赖声明，并结合仓库源码与插件文档说明底层原理与最佳实践。读完本文，你将能独立完成一个可被下游应用复用的视频能力库的集成与构建配置。

一、为什么第三方库的集成方式需要单独说明

React Native Video 既是一个直接面向业务应用的组件库，也是一个可以被其他 npm 库再次封装的底层能力提供方。与直接在 App 里使用不同，第三方库（Third-Party Library）在集成时有两条根本性的选择需要先想清楚：

1. 版本由谁决定——是库自己锁定某个版本的react-native-video，还是把版本选择权交给最终使用该库的 App；
2. 原生依赖如何衔接——库自身的*.podspec（iOS）与build.gradle（Android）需要声明哪些对react-native-video及其底层运行时（Nitro Modules、androidx.media3）的依赖。

官方文档 Use in Third Party Library 给出了最核心的配置骨架，本文在此基础上结合仓库源码（package.json、ReactNativeVideo.podspec、android/build.gradle）做纵深展开，让每一行配置都有据可查。

二、JS 层：选择 dependency 还是 peerDependency

2.1 两种策略的语义与适用场景

官方文档给出的核心建议非常直接：既可以把react-native-video作为普通依赖（dependency），也可以作为对等依赖（peerDependency）。

{ "dependencies": { "react-native-video": "latest" } // OR "peerDependencies": { "react-native-video": "*" } }

两种写法的取舍逻辑如下：

从仓库的react-native-video自身声明也能看到对等依赖的实践：在 packages/react-native-video/package.json 中，react-native-nitro-modules被声明为">=0.35.0"的 peerDependency，同时@videojs/react（Web 端实现）以 dependency 引入。这说明一个成熟库往往会混合使用两种策略：对与自身强绑定、存在版本匹配要求的运行时（Nitro Modules）使用 peerDependency 限定下限；对可选/平台相关实现使用 dependency。

2.2 导入与基本使用

声明依赖后即可在第三方库的源码中直接导入。官方文档给出了最简用法：

import { VideoPlayer } from 'react-native-video'; const player = new VideoPlayer({ uri: 'https://www.example.com/video.mp4' }); player.play();

这个VideoPlayer是 v7（Nitro 架构）下的核心 API，与 v6 时代的<Video />组件是两套模型。查看仓库的导出入口 packages/react-native-video/src/index.tsx 可以看到，库同时导出了VideoPlayer、VideoView、useVideoPlayer、useEvent以及大量类型（VideoConfig、VideoSource、VideoPlayerStatus、ResizeMode等），第三方库既可以面向命令式播放器封装，也可以面向声明式组件封装。

关于new VideoPlayer(...)的底层行为，VideoPlayer.ts 的构造函数展示了完整链路：

constructor(source: VideoSource | VideoConfig | VideoPlayerSource) { const hybridSource = createSource(source); const player = createPlayer(hybridSource); // Initialize events super(player.eventEmitter); this._player = player; }

也就是说，new VideoPlayer({ uri: ... })会先后经过createSource（构建原生源对象）与createPlayer（通过 Nitro 工厂创建原生混合对象）两步，最终拿到一个真正承载原生播放能力的实例——这就是为什么官方示例里player.play()可以直接触发原生播放。在第三方库中封装时，建议将这段逻辑收敛到一个你自己暴露的高层 API 后面，例如createPlayer(uri): Promise<VideoPlayer>，以隔离对react-native-video的直接依赖。

三、iOS 原生层：在*.podspec中声明依赖

iOS 端集成时，需要在第三方库自己的 podspec 里声明对ReactNativeVideo的依赖：

Pod::Spec.new do |s| // ... s.dependency 'ReactNativeVideo' end

3.1 pod 名称与源码组成的验证

ReactNativeVideo正是该库 iOS 侧的真实 pod 名，见 ReactNativeVideo.podspec 中的s.name = "ReactNativeVideo"。从该文件的s.source_files可以看出库的 iOS 源码分三大块，这也对应着第三方库在使用时可能接触到的层级：

• ios/Core/**：核心库文件（VideoManager、VideoError、播放器观察者、Now Playing 管理等）；
• ios/Hybrids/**：Nitro Hybrid 对象（HybridVideoPlayer、HybridVideoPlayerSource、事件发射器、视图管理器）；
• ios/View/**：视频视图组件（Fabric 与 Paper 两套实现按新/旧架构互斥编译）。

另外注意 podspec 中有ENV["USE_FRAMEWORKS"]的处理分支——当下游以use_frameworks!方式集成时，podspec 会额外补上React-Core、React-jsinspector等依赖。如果你的第三方库面向这类工程，需要在集成文档中向消费者说明这一前提。

3.2 参考：官方 DRM 插件的依赖写法

仓库中的官方插件 packages/drm-plugin/ReactNativeVideoDrm.podspec 就是"第三方库在 podspec 中依赖 ReactNativeVideo"的现实范本：

s.dependency 'React-jsi' s.dependency 'React-callinvoker' s.dependency 'ReactNativeVideo'

它的 iOS 源码（ios/DRMManager/DRMManager.swift、DRMManager+AVContentKeySessionDelegate.swift、DRMPlugin.swift等）正是在ReactNativeVideo提供的插件协议之上扩展 DRM 能力。因此，你的第三方库若需要注册插件（如自定义 DRM、源处理、缓存控制），iOS 侧只需s.dependency 'ReactNativeVideo'，剩下的通过插件协议即可接入。

四、Android 原生层：在build.gradle中声明依赖

Android 侧官方文档给出了明确的依赖清单：

// ... dependencies { // ... implementation project(':react-native-video') implementation project(':react-native-nitro-modules') implementation "androidx.media3:media3-common:1.4.1" implementation "androidx.media3:media3-exoplayer:1.4.1" }

4.1 为什么需要这三个层面的依赖

对照仓库的 android/build.gradle（其自身dependencies块），可以逐项理解它们的作用：

• :react-native-video：提供播放器与视图的 Android 实现（ExoPlayer 封装、Nitro Hybrid 对象、Fabric/Paper 视图）；
• :react-native-nitro-modules：Nitro 运行时，负责 JS 与原生之间的混合对象桥接。react-native-video自己在 package.json 中声明了peerDependencies["react-native-nitro-modules"] = ">=0.35.0"，你的库与其强绑定是合理的；
• androidx.media3:*：ExoPlayer 的媒体能力基座。第三方库如果要直接操作NativeVideoPlayer的底层播放行为、自定义MediaSource/DataSource（例如通过插件方法getMediaDataSourceFactory、getMediaSourceFactory），就必须直接依赖 media3 的相关模块，因为此时你访问到的是 media3 的类型（DataSource.Factory、MediaSource.Factory、MediaItem.Builder）。

4.2 media3 版本的协调

官方文档示例使用1.4.1，而仓库 android/build.gradle 中 media3 相关依赖（media3-exoplayer、media3-common、media3-ui、media3-datasource、media3-datasource-okhttp、media3-session以及可选的media3-exoplayer-dash/media3-exoplayer-hls）都统一通过getExtOrDefault("media3Version")读取版本号。这提示第三方库在声明 media3 依赖时，应与消费方工程中react-native-video实际使用的 media3 版本保持一致，避免出现运行时NoSuchMethodError之类的版本错位问题；同时也不要忘记react-native的 React 组件依赖本身（仓库中以implementation "com.facebook.react:react-native:+"声明）。

4.3 可选的 DASH / HLS 模块

仓库的 build.gradle 通过RNVideo_useExoplayerDash/RNVideo_useExoplayerHls属性（gradle.properties）控制是否引入media3-exoplayer-dash与media3-exoplayer-hls，并在关闭时用src/stubs/dash、src/stubs/hls下的 stub 类占位。如果你的第三方库要支持 DASH/HLS 流，需要确保消费方工程开启了对应开关或直接补充这两个模块依赖。

五、原生层集成与插件体系的衔接

之所以第三方库集成方式被收录在 docs/docs/plugins 目录下，是因为原生层的集成几乎都是为了注册插件。插件体系允许你在原生代码中：

• 在播放器/视频视图创建与销毁时挂接生命周期（onPlayerCreated、onPlayerDestroyed、onVideoViewCreated、onVideoViewDestroyed）；
• 在播放前改写视频源（overrideSource）；
• 提供自定义 DRM 管理器（getDRMManager）；
• Android 上覆盖 ExoPlayer 的DataSource.Factory、MediaSource.Factory、MediaItem.Builder，并控制缓存（shouldDisableCache）。

插件机制的架构与详细 API 可参考仓库内的配套文档：插件系统概览、插件接口参考、插件使用示例、插件注册表。

一个典型的集成闭环是：你的库在 JS 层通过 dependency/peerDependency 声明对react-native-video的依赖并导出自己的高层 API；在 iOS 的 podspec 中s.dependency 'ReactNativeVideo'；在 Android 的 build.gradle 中挂上:react-native-video、:react-native-nitro-modules与 media3 依赖；随后在你的原生代码里继承ReactNativeVideoPlugin（Kotlin/Swift），插件会在实例化时自动注册（见 插件接口参考 中PluginsRegistry.shared.register(...)的说明）。

六、最佳实践与常见注意事项

1. 优先考虑 peerDependency 提供灵活性：如果对 API 没有版本强依赖，把react-native-video放进peerDependencies可以避免最终 App 中出现两个版本并存的播放器实例，这是官方文档推荐的首选路径。
2. 不要忘记 Nitro Modules 的版本约束：react-native-videov7 基于 Nitro 架构，要求react-native-nitro-modules >= 0.35.0（见 package.json）。若你的库使用peerDependencies，建议同样声明该运行时依赖，把版本冲突问题在安装阶段就暴露出来。
3. Android 依赖尽量跟随主库的 media3 版本：第三方库与react-native-video共享同一份 media3 类路径，版本不一致极易引发编译期类型缺失或运行期链接错误。
4. 导出入口以src/index.tsx为基准：JS 侧可导入的内容（VideoPlayer、VideoView、类型、hooks）都在 src/index.tsx 中统一导出，封装库前先浏览该文件确认 API 面。
5. 生命周期资源清理：播放器创建后要记得在合适时机调用release()释放原生资源（VideoPlayer.ts 中release()会销毁原生播放器并延迟 5 秒清理引用，避免释放瞬间的迟到事件造成崩溃）。第三方库封装时应当把释放逻辑暴露给消费方，或在宿主组件卸载时自动执行。
6. DRM 支持现状：根据 插件使用示例 中的警告，getDRMManager目前在 React Native Video 中尚未实现、调用不会生效，因此第三方库若规划 DRM 能力，需关注官方后续版本的插件接口进展，或参考 packages/drm-plugin 的架构自行扩展。

七、总结

在第三方库中集成 React Native Video 的要点可以归纳为一句话：JS 层用 dependency/peerDependency 解决版本策略，原生层用 podspec 与 build.gradle 解决平台依赖，再通过插件协议接入播放器生命周期与源处理能力。本文给出的所有配置都与仓库源码一一对应（package.json、ReactNativeVideo.podspec、android/build.gradle、src/index.tsx），按此配置即可构建出一个可发布、可复用、能被下游 App 无缝消费的视频能力库。

• 音视频
• 移动开发