做RN开发，只要涉及音视频播放，几乎绕不开react-native-video这个库。我最早接触它还是0.x版本，那时候Android和iOS两边还要写不少平台差异代码，现在API已经统一得很舒服了。不过正因为这个库功能多、配置项复杂，网上能查到的资料又大多停留在“怎么播出一个mp4”的层面，真正遇到问题的时候还是得自己一点点踩坑。
这篇文章不是官方文档的翻译版，而是我这几年在多个实际项目里用react-native-video攒下来的经验总结。从最基础的接入配置，到性能调优、后台播放、缓存策略，再到各种奇葩问题的排查思路，我会按实际开发中会遇到的顺序一层层拆开讲，尽量把“为什么这么做”也说清楚。
1. 为什么视频组件要选react-native-video
1.1 它到底解决了什么问题
如果你只是在App里塞一个简单的宣传视频，用WebView嵌入网页播放器也行，但一旦涉及列表播放、横竖屏切换、后台续播、音视频分离控制这些需求，WebView方案就会变得非常痛苦。react-native-video的核心价值在于，它把Android和iOS两套完全不同的原生播放器能力封装成了统一的JS接口。
本质上它做了一件事：你在JS层写的代码会被映射成Android的ExoPlayer和iOS的AVPlayer。这意味着两边的能力差异被抹平了，你不需要分别维护两套播放逻辑。而且它对VideoSource、缓冲策略、字幕轨道、音频路由这些底层的处理都做了抽象，用起来确实省心很多。
1.2 和其他方案相比的取舍
我在项目里对比过几个方向：
- 纯WebView方案：做成HTML5播放器，优点是跨平台一致性好、迭代不需要发版，缺点是在列表滚动场景下内存开销大，而且全屏体验、亮度和音量控制都被浏览器层限制住了，很难做到原生级顺滑。
- 自研原生播放器：每个端写一个桥接模块，技术上完全可控，但要维护两套代码，还要自己处理生命周期、网络状态、缓存清理，交付周期会被拉长很多。
- react-native-video：社区活跃度高、API覆盖面广，性能上因为是直接跑原生播放器，所以视频解码效率、播放流畅度都很有保障。缺点也有，就是配置项较多，新手容易在参数上犯迷糊。
从实际交付角度来说，只要不是对播放器底层有极其特殊的定制需求，react-native-video都是性价比最高的选项。它在npm上的周下载量一直排在前列，而且GitHub的issue响应速度在RN生态里算快的，遇到问题基本都能找到解决方案。
2. 接入前的必要准备与版本匹配
2.1 RN版本和依赖版本怎么配对
这是很多人第一步就踩坑的地方。RN生态的版本兼容性是个老大难问题，react-native-video也不例外。我的习惯是先去GitHub仓库的Release页面看它支持的RN版本范围，再去package.json里确认peerDependencies。简单来说，新版react-native-video（5.x之后）对RN 0.60+支持都很完整，如果你还在用0.59或更老的版本，建议先升级RN版本，否则会碰到编译通不过的问题。
从6.x版本开始，它加大了Android侧的改造力度，全面转向Kotlin和AndroidX。如果你的项目还没有迁移到AndroidX，需要先跑一遍jetifier。这里有个经验：不要盲目升级到最新版，除非你的业务确实需要新特性。只要当前版本能满足需求、构建正常、线上没有崩溃，就让它稳定跑着，升级前一定要看CHANGELOG里有没有breaking changes。
2.2 安装和原生配置的细节
安装命令很简单，但配置里有些细节容易被忽略：
npm install react-native-video如果是iOS，还需要执行：
cd ios && pod installAndroid端如果是老版本RN，可能要手动在MainApplication里注册包名，但现在的自动链接机制已经替你处理好了。iOS端需要注意，Info.plist里要增加App Transport Security的配置，否则HTTP协议的视频地址会被系统拦下来：
<key>NSAppTransportSecurity</key> <dict> <key>NSAllowsArbitraryLoads</key> <true/> </dict>但是，如果你只是调试阶段这么设没问题，上架App Store时最好还是用HTTPS的源，或者对特定域名做例外处理。审核对ATS的检查很严格，直接在Info.plist里全局开启ArbitraryLoads容易被拒。
Android端还有一个容易踩的坑：如果你的视频流是明文的http地址，需要在AndroidManifest.xml里加上：
<uses-permission android:name="android.permission.INTERNET" />并且确认application节点下没有把usesCleartextTraffic设为false。否则会看到视频一直处于加载中状态，不报错也不出画面，查半天发现是流量被系统拦了。
3. 核心用法与API拆解
3.1 最基础的播放器示例
先看一个最简的使用方式：
import Video from 'react-native-video'; const Player = () => { return ( <Video source={{ uri: 'https://example.com/video.mp4' }} style={{ width: '100%', height: 300 }} resizeMode="contain" controls /> ); };这段代码已经能让一个本地或网络视频正常播放了。但实际项目中基本不会停留在这一步，因为只写这些参数，你会遇到很多问题——比如音频焦点冲突、视频加载失败没提示、退出页面后播放还在继续。
3.2 核心属性逐个拆解
react-native-video的API设计是把所有播放器行为都暴露成props，理解清楚这些属性才是用好它的前提。我挑几个最重要的说。
source
source不只是传一个uri字符串，它支持更细的对象结构：
source={{ uri: 'https://example.com/video.m3u8', type: 'm3u8', headers: { Authorization: 'Bearer xxx', }, }}很多人在做鉴权视频流时不知道headers怎么传，这个字段就是用来解决带token的视频请求的。另外，本地视频文件可以直接用require语法：
source={require('./assets/video.mp4')}Android端对打包进apk的视频格式有要求，某些专有编码格式（比如特定码率的wmv）可能播不了，MP4和HLS基本都能正常播放。
resizeMode
这个属性控制视频画面如何适配播放器容器，选项有contain、cover、stretch和none。区别是：
- contain：保持宽高比，完整显示视频画面，上下或左右会有黑边
- cover：保持宽高比，填满整个容器，超出部分会被裁掉
- stretch：拉伸填满容器，画面可能会变形
- none：原始尺寸，不做适配
列表页的短视频推荐用cover，因为卡片尺寸统一，画面铺满更好看。详情页通常用contain，保证完整看到视频内容。
controls
controls设为true会显示系统自带的控制条，包括播放暂停按钮、进度条、时间显示。iOS和Android的默认控制条样式不一样，如果你需要统一的UI风格，可以把它关掉，自己用播放暂停按钮加Slider实现，这在直播和短视频场景里很常见。
paused、repeat、muted
这三个是最常用的状态控制属性。paused控制播放暂停，repeat控制是否循环，muted控制静音。短视频场景下，列表中的视频通常会设成muted且autoplay，这样用户滑动的时候能看到画面动，但不会被声音打扰，等点击进入详情页再打开声音。
3.3 回调事件能拿到什么
react-native-video提供了不少事件回调，要在实际业务中充分用起来：
- onLoad：视频元数据加载完成后触发，能拿到duration、naturalSize、width和height，适合加载成功后更新进度条总时长
- onProgress：播放过程中持续触发，返回currentTime和playableDuration，可以用来更新进度UI，也能做播放埋点
- onEnd：播完触发，适合做列表自动播放下一个
- onError：加载或播放失败时触发，错误对象里有error.errorString和error.errorCode，方便区分网络错误还是解码错误
- onBuffer：缓冲开始触发，配合isBuffering状态可以展示loading动画
- onPlaybackRateChange：播放速率变化触发，可以用来判断是否因为网络原因降速了
有个小坑是onProgress的触发频率在不同平台上不一致，iOS大概是每500ms一次，Android会根据播放器的刷新率来，如果你用它做精确的进度条拖动，需要做一层防抖处理。
3.4 播放器实例方法
通过ref可以调用播放器实例的方法，比如seek和dismissFullscreen。seek是高频操作，但它有几个注意点：
const playerRef = useRef(null); const jumpTo = (time) => { playerRef.current.seek(time); };连续快速拖动进度条时，seek的调用会被原生播放器合并或延迟处理，所以UI上要先做本地乐观更新，再等onSeek事件确认。否则手势一快，进度条就会跳来跳去。
4. 进阶场景与性能调优
4.1 列表页滑动播放的优化思路
短视频App那种滑动一个播一个的效果是很多项目的刚需。直接用FlatList渲染多个Video组件会非常卡，因为每个播放器都独立解码，内存占用也会飙升。
我的做法是只保留当前播放的Item挂载Video组件，其余Item用一个纯图片封面占位。具体可以用FlatList的viewabilityConfig + onViewableItemsChanged来监听当前可见item。等当前item完全进入可视区域且滚动停止了，再把Video组件渲染出来，同时设置paused为false；一旦滑出视野，就卸载播放器并重置paused为true。
这里还有一个经常被忽略的问题：Android的SurfaceView和TextureView在列表滚动时的性能差异很大。SurfaceView的渲染效率更高，但层级控制有限制；TextureView支持动画和变形，但性能和内存开销都更大。react-native-video默认会根据场景自动选择，但如果你的页面发生闪黑，可以手动设置renderToHardwareTextureAndroid试试。
4.2 后台播放与音频焦点管理
如果你的产品需要播放背景音乐类的视频，比如在线课程、播客之类的场景，要开启后台播放能力。
iOS端实现相对简单，在Info.plist里开启Background Modes的Audio选项：
<key>UIBackgroundModes</key> <array> <string>audio</string> </array>Android端要麻烦一些，系统对后台播放有限制，尤其是在8.0以上版本。你需要在前台服务中运行播放器，或者使用媒体会话服务。目前react-native-video对后台播放的支持已经比较完善了，但要注意你还需要在Android端开启前台服务权限：
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />还有一个关键点是音频焦点。如果用户在播放视频时来了电话、或者切到别的音乐App，你的播放器应该自动暂停。react-native-video提供了audioFocusProps相关配置，Android端可以通过设置audioManager的音频焦点策略来响应系统打断。这块如果不做，会出现“视频声音和电话通话声音同时放出来”的尴尬情况。
4.3 缓存与离线播放策略
缓存是个永远绕不开的话题。react-native-video本身不提供缓存能力，它是直接透传给原生播放器的。所以要么依赖播放器底层自带的缓存策略，要么自己接一层缓存。
iOS的AVPlayer对HLS的缓存支持比较底层的，系统默认会缓存一部分分段数据，但你不能直接控制缓存文件大小和清理策略。Android的ExoPlayer则提供了非常强的自定义缓存能力，可以通过SimpleCache来指定缓存目录和大小。
如果你需要跨平台的统一缓存行为，可以考虑接一个中间层，比如用react-native-video配合本地代理服务器思路：视频源地址先经过本地代理，代理把数据流写入本地磁盘缓存，再转发给播放器。这个方案的优点是播放器不需要做任何改动，缺点是代理服务器的性能和稳定性会影响播放体验。我在一个离线下载项目里用过这个方案，实现下来最大的体会是：缓存的key设计要提前规划好，我建议用视频id加清晰度来拼，否则同一个视频不同清晰度会互相覆盖。
4.4 直播流与低延迟场景
如果想播放直播流，react-native-video对HLS和RTMP的支持覆盖得比较全。HLS直播流通常直接传m3u8地址就行，延迟受切片大小影响。RTMP流在iOS上原生AVPlayer不支持，需要额外封装，Android端ExoPlayer可以直接播。
延迟优化这块，iOS的AVPlayer有一个属性可以设置AVPlayerItem的preferredForwardBufferDuration，react-native-video暴露了bufferConfig的配置入口：
bufferConfig={{ minBufferMs: 15000, maxBufferMs: 50000, bufferForPlaybackMs: 2500, bufferForPlaybackAfterRebufferMs: 5000, }}直播场景想降低延迟，要把minBufferMs和bufferForPlaybackMs调小，但调太小会导致卡顿变多，需要根据实际网络情况平衡。我一般先设置minBufferMs为1000-3000，再观察播放稳定性逐步微调。
低延迟的另一个手段是使用LL-HLS（Low-Latency HLS），它通过缩短切片时长和预加载机制把延迟压到2秒以内，但要求播放器和CDN都支持这套协议。iOS 15以上的系统对LL-HLS支持不错，Android的ExoPlayer新版也支持了。如果你的业务对实时性要求很高（互动直播、连麦场景），建议评估一下这个方向。
5. 常见问题与排查技巧实录
5.1 iOS视频黑屏但有声音
这是出现频率最高的问题之一。表现是能听到声音，但画面全黑。排查路径我一般这样走：
先确认视频编码格式。AVPlayer对H.264和H.265的支持没问题，但如果视频是VP9编码，iOS原生播放器是不支持的，就会黑屏。建议用工具查看视频的编码信息，如果发现是VP9，转成H.264就好了。
再检查resizeMode和容器样式。有时候播放器容器高度为0或被其他View盖住了，也会表现成黑屏。Debug时可以在播放器上临时加一个明亮背景色，如果背景色能透出来，说明是渲染层级的问题。
还有一种可能是iOS 14以上的系统对本地网络权限的限制。如果视频地址是局域网内IP，需要在Info.plist里添加NSLocalNetworkUsageDescription描述，否则请求会被静默拦截。
5.2 Android首帧加载白屏
Android端往往会在视频开始播放前出现一段白屏时间，尤其在大视频文件上明显。这其实是SurfaceView创建和视频解码初始化耗时导致的，可以这么优化：
- 视频封面图直接铺在Video组件底下（绝对定位），播放器透明盖在上面，首帧渲染之前用户看到的是封面而不是白屏
- 通过onLoadStart和onLoad事件，在视频真正加载完成前展示loading动画
- 对正在播放的视频关闭动画渲染优化，比如不要同时套多层Animated.View，Android上会加剧首帧延迟
ExoPlayer还有一个预加载的能力，可以在用户还没点进详情页前就提前初始化播放器并加载部分数据。但要注意控制预加载次数，否则用户滑过很多视频时，网络请求会同时发起很多，反而拖慢后面的真实播放。
5.3 播放过程中内存持续增长
如果页面反复进出视频详情，或者列表里连续播放多个视频，会有内存增长的问题。这通常不是react-native-video的锅，而是播放器实例没有被正确销毁。一个常见的反面案例是：从详情页返回时，页面组件被卸载了，但播放器还在后台运行，没有调用release。
解决方案是在页面unmount时做清理：
useEffect(() => { return () => { playerRef.current?.release(); }; }, []);另外，Android的ExoPlayer对纹理缓存和Surface资源的释放有一定延迟，如果短时间内在不同页面创建很多播放器实例，最好做一个全局的播放器单例管理，避免反复创建销毁。简单做法是写一个播放器管理类，负责创建、暂停、释放和复用实例。
5.4 网络视频加载失败的错误区分
onError回调拿到的错误信息要会看。iOS的AVPlayer错误通常是Error Domain=AVFoundationErrorDomain，后面跟错误码和描述信息。Android的ExoPlayer错误则会有ExoPlaybackException，里面区分了SourceException、RendererException等不同类型。
重点区分两类错误：网络层错误和解码层错误。网络层错误一般是timeout、404、403，解决方向是检查地址和网络权限；解码层错误发生在视频数据已经下载完成但无法渲染，解决方向是检查编码格式和设备兼容性。区分这两类，能帮你少走很多弯路。我一般在onError里上报错误码到日志系统，再结合播放时的网络状态一起排查。
5.5 播放器和页面导航的冲突
在React Navigation的页面栈里，从A页推到B页，A页的视频还在播放，这是很常见的需求遗漏。可以在A页的useFocusEffect或blur事件里暂停播放：
useEffect(() => { const unsubscribe = navigation.addListener('blur', () => { playerRef.current?.setNativeProps({ paused: true }); }); return unsubscribe; }, [navigation]);还有一个细节：iOS上从全屏播放返回时，偶尔会出现页面方向没恢复的问题。需要在播放器退出全屏的回调里，手动调用屏幕方向锁定逻辑。
5.6 多个视频同时播放的声音混音
有些业务场景会在同一页面放多个视频（比如画中画），如果没做处理，声音会混在一起。react-native-video提供了audioOutput的属性配置，可以控制音频输出路由。更通用的做法是，在播放新视频时把其他播放器的muted设为true，只保留当前视频的声音。Android端音频焦点也可以约束这一点，抢到焦点的才允许发声。
6. 实际项目中的一些探索
6.1 新架构下的兼容性观察
RN的新架构（Fabric和TurboModule）这几年开始被越来越多团队采用。react-native-video从6.x版本开始逐步适配新架构，但在切换时还是要注意一些问题。我的一个建议是，在升级之前先在测试分支上完整跑一遍视频功能矩阵，包括播放暂停、进度拖动、清晰度切换、后台续播等场景，把回归测试做完再切主分支。
新架构下桥接层的调用方式有变化，如果遇到视频组件闪退，可以先去仓库issue里搜一下是不是已知问题。社区对新架构的支持力度在加大，但毕竟涉及原生层的播放器封装，适配节奏会慢一些。
6.2 视频滤镜和特效的定制实践
看到有人问react-native-video能不能加滤镜，比如美颜、调色、转场特效。如果你的业务需要这类能力，只靠react-native-video是不够的，它定位是播放器，不是视频编辑器。
有一个方向是把播放器渲染的帧拿到GPU上再做一次处理。Android上可以通过TextureView配合OpenGL ES做二次渲染，iOS上可以用AVPlayerItemVideoOutput拿到CMSampleBuffer再交给Metal处理。但这么做的工程量不小，而且性能损耗明显，尤其在高分辨率视频上。
更务实的做法是，如果滤镜是实时效果预览，可以先用原生相机或视频编辑SDK处理好，再播放处理后的视频；如果是播放时叠加贴纸、文字之类，可以用RN的View层级盖在播放器上面，这种做法性能和实现成本都可控。
6.3 音频路由和耳机插拔的处理
播放视频时用户插拔耳机会影响音频输出。系统默认行为是插上耳机走耳机，拔掉耳机走外放。react-native-video对这条链路的处理比较透明，但如果你的播放器需要感知耳机状态来调整UI（比如显示“当前为耳机模式”），就需要通过原生事件监听来做。
iOS可以观察AVAudioSession的routeChange通知，Android可以监听ACTION_AUDIO_BECOMING_NOISY。拿到事件后，通过DeviceEventEmitter广播给JS层，再更新界面。
6.4 播放数据的埋点与分析
视频的播放数据是产品运营的生命线。我在项目里会做一套完整的播放埋点，核心事件包括：播放开始、播放结束、播放进度（每25%、50%、75%上报）、暂停、异常中断、卡顿次数。
对于卡顿数据，我用onBuffer和onPlaybackRateChange配合判断。onBuffer触发记一次缓冲开始，onProgress恢复推进记一次缓冲结束，统计缓冲时长和次数。还有一个指标是播放器缓冲率，定义为缓冲总时长除以有效播放时长，用于评估不同CDN节点的质量。
埋点方案用RN侧的网络请求上报就行，但要注意不要把埋点请求阻塞在播放器主线程上，否则会有卡顿风险。
6.5 离线缓存到本地相册
有些业务需要让用户把视频存到本地相册，react-native-video本身不提供这个能力，需要单独下载视频文件再保存。可以用react-native-fs把视频流下载到临时目录，再调用原生相册API保存。Android 10以后的系统对相册写入权限管控很严，用MediaStore的API需要适配不同的targetSdkVersion，这块很容易踩坑。
还有版权问题，如果你的视频内容涉及付费版权，保存到相册的能力要慎重开放，尽量做服务端授权校验。
7. 一些想分享的体会
react-native-video用久了你会发现，大部分"诡异"的问题最后都能归因到几个基础点上：编码格式、网络状态、生命周期管理、原生权限。它能做的很多，但也不是银弹，遇到播放器行为和预期不一致时，先确认基础因素，再深挖源码。
最后分享一个排查小技巧：当你怀疑是视频源的问题，先用系统浏览器直接播放这个地址验证一遍，再用原生Demo工程播放，最后再回到RN层。层层剥离，能快速锁定问题出在哪一环。另外，GitHub仓库的issue区是个宝藏，很多别人遇到过的问题和你一模一样，善用搜索能省下大量时间。
