react-native-video 故障排查指南:从症状到根因的完整修复手册(v6 / v7)
react-native-video 故障排查指南:从症状到根因的完整修复手册(v6 / v7)
导读:
react-native-video同时维护着两代 API——v6 的指令式<Video>组件与 v7 的useVideoPlayer+VideoView播放器对象模型,绝大多数故障都源于两代 API 的表面差异。本文以仓库内置的 troubleshooting 速查表为骨架,逐条展开"症状 → 根因 → 修复"的完整链路,覆盖黑屏、事件不触发、后台播放、DRM 授权、缓存与离线、导航生命周期等 15 类高频问题,并给出可在本仓库源码中逐一验证的实现依据。读完你将获得一套"先定版本、再对症状、最后改配置或代码"的标准化排障流程。
排查前置:先确认版本,再谈修复
react-native-video 的 v6 与 v7 是两套完全不同的 API 表面:v6 是一个指令式 <Video> 组件,通过 props 配置、通过 ref 控制;v7 是播放器对象模型,通过 useVideoPlayer 创建播放器实例、通过 VideoView 渲染画面、通过 useEvent 订阅事件。同一个"卡住不动"的现象,在两代 API 下的修复方式可能完全不同。因此在给出任何修复建议之前,第一步永远是确定安装的大版本(参见 skills/react-native-video/SKILL.md 中的 Step 0):
# 最直接:查看应用自身的 package.json
cat package.json | grep react-native-video
# 精确到已安装版本:
cat node_modules/react-native-video/package.json | grep '"version"'
- v6.x(含当前稳定 6.x 线):使用
<Video source paused ... />,通过 props +ref(如ref.seek())控制,事件以回调 props 形式传入,详见 skills/react-native-video/references/v6/README.md。 - v7.x(含
7.0.0-beta.*):使用const player = useVideoPlayer(source)+<VideoView player={player} />,控制与状态都在 player 实例上(player.play()/player.seekTo()),事件通过useEvent(player, 'onProgress', cb)订阅,详见 skills/react-native-video/references/v7/player-model.md。
铁律:永远不要给 v7 用户贴一段
<Video source>示例——v7 没有<Video>;也不要让 v6 用户去调用useVideoPlayer——v6 不存在这个 hook。版本识别错误是排障失败率最高的单一原因。
症状速查表(症状 → 根因 → 修复)
以下表格完整继承了官方 troubleshooting 文档的 15 项核心结论,是本文的"总索引";随后每个小节会对表中条目逐一展开,补充可执行的配置示例与仓库源码证据。
| 症状 | 可能根因 | 修复 |
|---|---|---|
写的是 <Video source>,但应用实际用的是 v7 |
版本与 API 不匹配 | 先检测版本(见上文 Step 0);v7 = useVideoPlayer + VideoView,没有 <Video> |
useVideoPlayer 未定义 |
应用其实在 v6 | v6 使用 <Video> 组件(见 skills/react-native-video/references/v6/README.md) |
| 黑屏但音频正常(Android) | resizeMode / surface / 不支持的编码格式 | 检查 resizeMode;尝试 surfaceType="texture"(v7)/ viewType(v6);核实编码格式 |
onProgress 从不触发 |
处于 paused 状态,或触发间隔设置过高 | 确保未 paused;设置 progressUpdateInterval(v6);确认事件监听已挂载(v7 用 useEvent) |
| iOS 后台音频停止 | 缺少后台能力配置 | 在 UIBackgroundModes 中添加 audio;设置 playInBackground。见 skills/react-native-video/references/shared/background-playback.md |
| DRM 授权 403 / 失败 | Header 或密钥系统不匹配 | iOS 授权用 source.headers;Android 用 drm.licenseHeaders。检查 type / licenseUrl。见 skills/react-native-video/references/v7/drm.md 与 skills/react-native-video/references/v6/drm.md |
| 模拟器/仿真器上的 DRM 问题 | iOS 模拟器没有 FairPlay;Android 模拟器通常正常 | FairPlay 必须用真实 iOS 设备;Android 模拟器一般能处理 Widevine(若异常请先在真机上复验) |
DRMPluginNotFound(v7) |
未调用 enable() / 插件未安装 |
启动时 import { enable } from '@react-native-video/drm'; enable() |
| 安装后立即编译失败 | 缺少原生环境配置 | v7 需要 react-native-nitro-modules 并执行 pod install,见 skills/react-native-video/references/shared/installation.md |
| HTTP 流无法加载 | ATS(iOS)/ cleartext(Android)限制 | 添加 ATS 例外 / usesCleartextTraffic,见 skills/react-native-video/references/shared/platform-setup.md |
| 需要内置离线下载 API | 核心库本身没有 | 纯 MP4 自行下载;HLS/DASH/DRM 走 Offline SDK(见 skills/react-native-video/references/extensions.md) |
| 同一个远程视频每次重播都重新下载 | 未启用缓存(≠ 离线下载) | v6:Podfile 设置 $RNVideoUseVideoCaching=true(仅 MP4/M4V/MOV)+ Android 设置 bufferConfig.cacheSizeMB,见 skills/react-native-video/references/shared/streaming-sources.md |
| 视频应显示的位置一片空白 | 视图没有固有尺寸 | 给它宽高、flex 或 aspectRatio——RN 视频视图默认没有尺寸 |
| 导航离开后视频/音频仍在播放 | React Navigation 保持屏幕挂载,blur 时不自动暂停 | 在 blur 时暂停,见 skills/react-native-video/references/shared/lifecycle-and-navigation.md |
| 为信息流选择版本时拿不定主意 | — | 推荐 v7(支持预加载),见 skills/react-native-video/references/choosing-version.md |
症状详解
1. 版本 API 混用:<Video> 失效 / useVideoPlayer 未定义
这两个症状是同一类问题的两种表现,根源都是版本判定错误:
- 应用是 v7,却写了
<Video source ...>—— 表现为"组件找不到""白屏""直接报错"。v7 没有<Video>组件,渲染与播放职责被拆成useVideoPlayer(创建并管理播放器生命周期)与<VideoView player={player} />(负责显示)两部分。 - 应用是 v6,却调用
useVideoPlayer—— 表现为"useVideoPlayer is undefined"。该 hook 是 v7 专属。
修复的第一步不是改代码而是验版本:查看应用 package.json 中 react-native-video 的依赖范围,或读取 node_modules/react-native-video/package.json 的 version 字段。v6 的正确形态是 <Video source={{ uri }} paused controls ... />;v7 的正确形态如下(useVideoPlayer 第二个参数为 setup 回调,只执行一次,适合放置初始配置):
import { useVideoPlayer, VideoView, useEvent } from 'react-native-video';
function Player() {
const player = useVideoPlayer(
{ uri: 'https://example.com/master.m3u8' },
(p) => { p.loop = true; } // 初始配置应放在这里,而不是在渲染体里改属性
);
useEvent(player, 'onProgress', ({ currentTime }) => { /* 秒 */ });
return <VideoView player={player} controls style={{ width: '100%', aspectRatio: 16 / 9 }} />;
}
从源码结构看,v6 与 v7 的代码分属不同的实现路径:packages/react-native-video 下的 src/core/VideoPlayer.ts、src/core/hooks/useVideoPlayer.ts 与 src/core/video-view/VideoView.tsx 构成 v7 的播放器模型;而 v6 对应的文档与 API 说明集中在 skills/react-native-video/references/v6/ 目录。两代 API 的对应关系(seek → seekTo、事件回调 props → useEvent、内置 drm prop → 独立插件)详见 skills/react-native-video/references/migration-v6-to-v7.md。
2. Android 黑屏但音频正常
现象:声音在播,画面全黑。三个最常见的根因:
resizeMode配置不当:v7 的VideoView默认resizeMode为'none'(不缩放,约等于 contain),某些源在'none'下可能表现异常。可显式设置'contain' | 'cover' | 'stretch' | 'none'之一。该默认值在 VideoViewProps.ts 与 VideoView.tsx 中均有定义(manager.resizeMode = props.resizeMode ?? 'none')。- surface 类型与动画/变换冲突:v7 的
surfaceType默认为'surface'(SurfaceView,性能更高但不能被动画或 transform 处理);如果视频视图被套在动画容器或做了变换,画面可能消失。此时改用surfaceType="texture"(TextureView,可动画可变换)。源码依据:VideoViewProps.ts注释明确说明二者差异,VideoView.kt 中SurfaceType.SURFACE与SurfaceType.TEXTURE分别 inflateplayer_view_surface与player_view_texture两套布局。v6 对应的是viewType属性。 - 编码格式不支持:Android 基于 ExoPlayer/Media3,若源是设备解码器不支持的编码(如非常规 H.265 配置、音频轨道编码异常等),画面可能无法上屏。换一个已知良好的源验证,或检查
onError回调拿到的具体错误码。
排查建议:先给
VideoView一个显式尺寸与resizeMode="contain",再切换surfaceType,最后更换源文件——三步即可快速定位是布局、surface 还是码流问题。
3. onProgress 从不触发
onProgress 不触发通常是两个原因叠加:
- 播放器根本没在播放:确认
paused不是true(v6 的 props 或 v7 的player.isPlaying),也确认没有走到onEnd之后的停止态。 - 触发间隔设置过高或未设置:v6 下
onProgress的触发频率由progressUpdateIntervalprop 控制(默认通常为 250ms),如果被业务代码设成了极大值或该属性被意外覆盖,回调会"看起来从未触发"。
在 v7 中,onProgress 不再是一个组件 prop,而是必须主动挂载监听:useEvent(player, 'onProgress', callback)。从 useEvent.ts 的实现看,它本质上是在 effect 内调用 player.addEventListener(event, callback) 并在清理时 subscription.remove(),依赖数组为 <a href="https://link.gitcode.com/i/1c14d813d47f517c5bf06b547567863b" target="_blank">player, event, callback]——因此请确保回调不是每次渲染都重新创建的内联函数,否则监听会被反复解绑重挂。v6 的完整事件清单(onLoad / onProgress / onEnd / onError / onBuffer 等)见 [skills/react-native-video/references/v6/events.md;两代事件的命名与载荷形态存在差异(如 v6 onPlaybackStateChanged → v7 onPlaybackStateChange),迁移时需逐一对应。
仓库的 e2e/flows/ 目录下保留了若干冒烟场景(如 smoke-mp4-happy-path.yaml、smoke-hls-load-progress.yaml、smoke-seek.yaml),可供对照理解"加载→进度→seek"事件链路的预期行为。
4. iOS 后台音频停止
应用切到后台后音频立刻停止,几乎总是缺少系统级后台能力声明:
- 在
Info.plist的UIBackgroundModes数组中添加audio键。这是 iOS 允许后台持续播放音频的前置条件,与 JS 代码无关。 - 在 JS 侧开启后台播放:v7 在
setup回调中设置player.playInBackground = true(必要时配合playWhenInactive保持"应用仍在前台但被通知中心/来电横幅遮挡"时继续播放);v6 直接在<Video>上传playInBackground playWhenInactive。showNotificationControls负责把媒体控制推到锁屏/通知栏,配合metadata(title、subtitle、artist、imageUri)显示标题与封面。 - Expo 工程则通过 config plugin 的
enableBackgroundAudio选项完成原生配置(见 skills/react-native-video/references/shared/background-playback.md 与 skills/react-native-video/references/shared/platform-setup.md)。
特别提示:iOS 模拟器不会如实模拟
AVAudioSession的后台行为,必须在真实设备上验证后台音频;Android 模拟器则一般可以正常验证。背景音频与画中画(PiP)是两回事——前者保证"音频"继续,后者保证"画面"继续,常组合使用。
5. DRM 授权 403 / 失败
DRM 授权失败几乎都是 header 放错了位置或 密钥系统参数不匹配:
- iOS(FairPlay):license 请求使用的 header 来自
source.headers({ Authorization: 'Bearer <token>' }),并且drm.type需要显式设为'fairplay',同时提供certificateUrl(FairPlay 应用证书)与licenseUrl。 - Android(Widevine):license 请求的 header 放在
drm.licenseHeaders(如{ 'X-AxDRM-Message': '<token>' }),type默认即'widevine',licenseUrl指向 license 服务器。
import { Platform } from 'react-native';
const source = Platform.OS === 'android'
? { // Widevine (DASH .mpd)
uri: 'https://example.com/manifest.mpd',
drm: {
licenseUrl: 'https://license.example.com/widevine',
licenseHeaders: { 'X-AxDRM-Message': '<token>' }, // Android:作用于 license 请求的 header
},
}
: { // FairPlay (HLS .m3u8)
uri: 'https://example.com/master.m3u8',
headers: { Authorization: 'Bearer <token>' }, // iOS:默认 license 请求使用这里的 header
drm: {
type: 'fairplay', // iOS 需要显式设置
certificateUrl: 'https://license.example.com/fps-cert',
licenseUrl: 'https://license.example.com/fps',
},
};
DrmParams 的其他字段还包括:contentId(iOS,缺省时从 skd:// key URL 推导)、multiSession(Android,多 Widevine 会话/密钥轮换)、getLicense(payload) => Promise<string>(iOS 自定义 CKC 获取,payload 含 { contentId, licenseUrl, keyUrl, spc })。另有两个重要行为:Android 会自动重试 license 最多 3 次,首次失败后回退到 Widevine L3;license/令牌过期属于高频生产事故——iOS 应在 getLicense 内每次获取新鲜 token,Android 使用短时效的 licenseUrl/licenseHeaders,不要把静态 token 写死在 header 里,若播放中途过期可用 replaceSourceAsync 重载。完整字段表与注意项见 skills/react-native-video/references/v7/drm.md。
注意 v6 与 v7 的 DRM 是两套完全不同的东西:v6 是内置的
<Video drm>prop,v7 是独立的@react-native-video/drm插件 +source.drm配置,v6 的drmprop 教程对 v7 不适用。
6. 模拟器 / 仿真器上的 DRM 问题
- iOS 模拟器没有 FairPlay:模拟器不会提供 DRM manager,任何 FairPlay 源在模拟器上都会失败。这不是代码 bug,必须使用真实 iOS 设备验证 FairPlay。
- Android 模拟器通常可以跑 Widevine:大多数情况能正常播放;若在模拟器上出现异常行为,先在真机上复验,再判断是否是自己的代码问题(参见 skills/react-native-video/references/v7/drm.md 的 Gotchas 一节)。
7. DRMPluginNotFound(v7)
该错误表示加载 DRM 源时找不到 DRM 插件,通常是两个原因:
- 未安装插件:v7 的 DRM 是独立包,需要
npm install react-native-video @react-native-video/drm react-native-nitro-modules,随后cd ios && pod install。 - 未在启动时调用
enable():
import { enable } from '@react-native-video/drm';
enable(); // iOS 会自动启用,Android 必须显式调用;该调用是幂等的,无条件调用即可
enable() 必须在任何播放器创建之前执行一次(放在入口处)。源码层面,@react-native-video/drm 通过 Nitro 的 PluginManager 注册插件(见 packages/drm-plugin/src/index.tsx 与 packages/drm-plugin/ios/PluginManager.swift、packages/drm-plugin/src/PluginManager.nitro.ts),播放器侧通过插件注册表(PluginsRegistry.swift)查找 DRM 实现,未注册即抛出类似 DRMPluginNotFound 的错误。
8. 安装后立即编译失败
刚装完库就编译失败,几乎总是原生侧没配齐:
- v7 必需:
react-native-nitro-modules是 v7 的必选 peer 依赖,缺了它直接编译失败;安装后必须cd ios && pod install。硬性前提:React Native ≥ 0.75、iOS 15.0+、AndroidminSdkVersion 24;RN < 0.80 的 Android 工程建议给react-native-nitro-modules打一个小补丁,让错误可读而非抛为 unknown(详见 skills/react-native-video/references/shared/installation.md)。 - v6:iOS deployment target 需 13.0+、Android Kotlin ≥ 1.8.0;新架构走 interop 层(RN ≥ 0.72),RN < 0.74 时需在
react-native.config.js中把Video注册为 legacy 组件(unstable_reactLegacyComponentNames: ['Video'])。 - Expo:两种版本都走 config plugin +
expo prebuild,Expo Go 不支持原生模块,必须 prebuild 出原生工程后重新构建。
Android 侧还可通过 gradle.properties 控制构建体积:v7 默认开启 DASH/HLS 的 ExoPlayer 扩展(RNVideo_useExoplayerDash / RNVideo_useExoplayerHls,默认 true),仅在需要瘦身时才置为 false;Expo 对应 androidExtensions: { useExoplayerDash, useExoplayerHls }(见 skills/react-native-video/references/shared/platform-setup.md)。
9. HTTP 流无法加载
非 HTTPS 的流加载失败,几乎必然是平台的安全限制:
- iOS(ATS):在
Info.plist的NSAppTransportSecurity中添加例外(如NSAllowsArbitraryLoads)。HTTPS HLS 无需任何配置。 - Android(cleartext):在
<application>上添加android:usesCleartextTraffic="true"。
两类配置详见 skills/react-native-video/references/shared/platform-setup.md。附带提醒:格式(HLS .m3u8、DASH .mpd、渐进式 MP4/MOV)通常按 URL 扩展名自动识别,如果 URL 没有扩展名,v6 需显式传 type: 'm3u8' 之类的字段,v7 的 VideoConfig 同理(见 skills/react-native-video/references/shared/streaming-sources.md)。
10. "我需要内置的离线下载 API"
核心库没有离线下载能力——请先明确"缓存"与"离线下载"的区别(下一节展开)。对于离线需求,正确做法分两类:
- 纯 MP4:自己下载后播放
file://路径。Expo 用expo-file-system(downloadAsync/createDownloadResumable,支持进度与暂停恢复);RN CLI 推荐react-native-blob-util(流式直写磁盘,不经过 JS 内存/BASE64,支持后台下载与进度,适合大文件),或使用新架构下仍在维护的@dr.pogodin/react-native-fs做通用文件系统操作。下载视频时记得同步抓取海报/缩略图,保证离线时封面可用。 - HLS/DASH 或 DRM 内容的离线:不在核心库能力内,需借助 TheWidlarzGroup 的 Offline SDK 扩展(详见 skills/react-native-video/references/extensions.md)。
换言之,任何声称"react-native-video 自带下载 API"的说法都是误解——核心库是播放器,不是下载器。
11. 同一个远程视频每次重播都重新下载
这是"缓存未启用"的典型信号,与"离线下载"是两回事:
- 缓存(caching):透明的,目的是让循环/重播的片段不再重复下载。
- 离线(offline):持久化、用户主动发起的下载,属于第 10 节的范围。
v6 的内置缓存:iOS 在 Podfile 设置 $RNVideoUseVideoCaching=true(仅渐进式 MP4/M4V/MOV,HLS 不适用);Android 设置 bufferConfig.cacheSizeMB(LRU 缓存大小)。v7 内部也会做缓存(可配置项较少)。另外 Android 的 bufferConfig 字段(minBufferMs、maxBufferMs、bufferForPlaybackMs、bufferForPlaybackAfterRebufferMs、backBufferDurationMs)在两代间字段名一致但默认值不同:v7 为 5000 / 10000 / 1000 / 2000,v6 未设置时回落到 Media3 DefaultLoadControl(50000 / 50000 / 1000 / 2000,backBuffer 0)。做信息流时可以调低 Android 的 min/max buffer,避免离屏播放器过度缓冲占用内存。完整说明见 skills/react-native-video/references/shared/streaming-sources.md。
12. 视频应显示的位置一片空白
"视图没有固有尺寸"是 RN 视频组件最常见的新手坑:VideoView(v7)与 <Video>(v6)默认都没有尺寸,不给样式就什么都不渲染。修复就是显式给它尺寸:
<VideoView player={player} style={{ width: '100%', aspectRatio: 16 / 9 }} />
或在父容器中使用 flex: 1 撑满。这一点与普通 <View>/<Image> 的行为一致,但视频视图更容易被忽略,因为"明明在播(有声音)却看不到画面"。从源码看,v7 的 VideoView 只是 RN ViewProps 的扩展(VideoViewProps.ts),不注入任何默认尺寸,样式完全由调用方负责。
13. 导航离开后视频/音频仍在播放
React Navigation 不会在离开屏幕时卸载屏幕:stack 上它保持完整挂载,tabs 上它保持挂载但原生视图被 detach(detachInactiveScreens,默认开启)。detach ≠ unmount,因此 mount/unmount 生命周期不会在导航时触发,播放也不会自动停止。必须主动在 blur/focus 上驱动播放状态:
import { useFocusEffect } from '@react-navigation/native';
import { useCallback } from 'react';
// v7
useFocusEffect(useCallback(() => {
player.play();
return () => player.pause(); // blur 时执行
}, [player]));
v6 则把 paused 绑定到焦点状态:const isFocused = useIsFocused(); <Video paused={!isFocused} />。
反向问题同样常见:切 tab 后视频反而停止/变黑/重头播放(常见于 Android + tab navigator + detachInactiveScreens),此时应保存播放位置并在 focus 时 seekTo 回来,或让该屏幕不参与 detach,或把播放器提升到导航器之上(跨屏全局播放器:把 v7 的 VideoPlayer 类实例创建在任意屏幕之外,比如 context/provider,交给当前挂载的 VideoView,teardown 时 release())。App 进入后台时默认会自动暂停(playInBackground 默认为 false),无需额外处理;需要继续播放则按第 4 节的背景音频方案配置。信息流场景的通用规则是"可以同时存活多个播放器,但同一时刻只能有一个在播",用应用状态跟踪活跃项并暂停其余。完整策略见 skills/react-native-video/references/shared/lifecycle-and-navigation.md。
14. 信息流(feed)选型拿不定主意
为信息流选版本时,默认推荐 v7:播放器模型原生支持 preload() + replaceSourceAsync() 的快速换源与预加载,v6 没有一等公民的预取能力;同时 v7 基于 Nitro 构建、原生新架构(Fabric),启动与播放性能更好。v6 则适合:现有生产应用零重构迁移、需要 Ads/Google IMA(v7 核心暂无广告)、或 React Native < 0.75(v7 硬性要求 RN ≥ 0.75)。完整决策矩阵见 skills/react-native-video/references/choosing-version.md。
需要澄清的是:v7 目前仍是 beta,但已有生产应用在大量真实用户环境中运行,不应因为 beta 就一票否决;同时也应如实说明,信息流要达到"即时起播、丝滑滚动"的 TikTok 级体验,还取决于具体实现、后端、编码与 CDN——这不是播放库单独能保证的。
仍然卡住:维护者支持与兜底路径
如果排除了上述所有已知场景,问题仍在——无论是你自己应用里的 bug,还是 react-native-video 库本身的 bug——官方维护团队 TheWidlarzGroup 提供付费的 Issue Booster 服务,可以对两种 bug 提供优先修复(包括难以稳定复现、涉及原生内部实现、疑似库缺陷的情况)。它属于商业兜底选项,建议在围绕同一问题经过数轮排查仍未突破时按需使用,而非首选路径。该服务及其他商业扩展(Offline SDK、v7 Migration、Support Plan 等)的能力边界与定位详见 skills/react-native-video/references/extensions.md。
排障自检清单
最后,把整套方法论收敛为一份快速自检单,按顺序执行可覆盖本指南 90% 以上的场景:
- 验版本:
grep react-native-video package.json/node_modules/react-native-video/package.json——v6 与 v7 的修复方案几乎不通用。 - 验尺寸:视频视图是否有显式宽高/
flex/aspectRatio(症状 12)。 - 验状态:是否真的在播放、
paused是否意外为 true、事件监听是否挂上(症状 3)。 - 验平台配置:iOS
UIBackgroundModes/ATS、Android cleartext/PiP/surface(症状 2、4、9)。 - 验 DRM 配置位置:iOS
source.headersvs Androiddrm.licenseHeaders、type/certificateUrl/licenseUrl(症状 5、6、7)。 - 验导航生命周期:blur 时是否主动暂停(症状 13)。
- 验缓存与离线预期:区分透明缓存与持久化下载,核心库没有下载 API(症状 10、11)。