本文详解在裸 React Native 项目中集成 expo-av 实现视频本地缓存的完整方案，涵盖路径处理、文件写入、URI 适配及常见兼容性问题（如 react-native-fs 路径不被 expo-av 识别），并提供可直接运行的优化代码与关键注意事项。
本文详解在裸 react native 项目中集成 `expo-av` 实现视频本地缓存的完整方案，涵盖路径处理、文件写入、uri 适配及常见兼容性问题（如 `react-native-fs` 路径不被 `expo-av` 识别），并提供可直接运行的优化代码与关键注意事项。
在 React Native 中缓存视频以提升离线播放体验和减少重复网络请求，是媒体类应用的刚需。但开发者常遇到一个典型陷阱：react-native-fs 写入的本地文件路径（如 /Users/.../Documents/video.mp4）无法被 expo-av 的 <Video> 组件直接识别——这是因为 expo-av 在 iOS 和 Android 上对本地文件 URI 有严格格式要求，仅支持 file:// 协议且需经系统路径规范化处理，而裸 RN 项目中 RNFS.DocumentDirectoryPath 返回的路径未自动补全协议前缀，也未做平台适配。
✅ 正确做法：使用 file:// + 规范化路径
expo-av 要求 source.uri 必须是合法的 file:// URI。你需要：
- 确保路径以 file:// 开头（iOS/Android 均需）；
- 使用 RNFS 提供的 pathToUri() 工具方法（推荐）或手动拼接；
- 避免直接拼接字符串（如 ${cachePath}/${filename}），因其在 iOS 上可能缺少 file:// 且路径分隔符不兼容。
以下是经过实测的优化实现：
import React, { useState, useEffect } from 'react';
import { View } from 'react-native';
import { Video } from 'expo-av';
import * as RNFS from 'react-native-fs';
const App = ({ videoUrl }: { videoUrl: string }) => {
const [videoUri, setVideoUri] = useState<string | null>(null);
useEffect(() => {
downloadAndCacheVideo(videoUrl);
}, [videoUrl]);
const downloadAndCacheVideo = async (url: string) => {
try {
const filename = url.substring(url.lastIndexOf('/') + 1) || `cached_${Date.now()}.mp4`;
const cacheDir = RNFS.DocumentDirectoryPath;
const localPath = `${cacheDir}/${filename}`;
// 检查是否已存在
const exists = await RNFS.exists(localPath);
if (exists) {
// ✅ 关键：使用 RNFS.pathToUri() 生成标准 file:// URI
const uri = RNFS.pathToUri(localPath);
setVideoUri(uri);
return;
}
// 下载并写入（流式写入更安全，避免大文件内存溢出）
const response = await fetch(url);
const blob = await response.blob();
const reader = new FileReader();
reader.readAsArrayBuffer(blob);
reader.onloadend = async () => {
const buffer = Buffer.from(reader.result as ArrayBuffer);
await RNFS.writeFile(localPath, buffer, 'binary');
const uri = RNFS.pathToUri(localPath);
setVideoUri(uri);
};
} catch (err) {
console.error('视频缓存失败:', err);
}
};
return (
<View style={{ flex: 1 }}>
{videoUri ? (
<Video
source={{ uri: videoUri }}
resizeMode="cover"
shouldPlay
isMuted={false}
isLooping
style={{ width: '100%', height: '100%' }}
/>
) : (
<View style={{ flex: 1, backgroundColor: '#f0f0f0', justifyContent: 'center', alignItems: 'center' }}>
<Text>正在缓存视频...</Text>
</View>
)}
</View>
);
};
export default App;⚠️ 关键注意事项
- 不要用 fetch().blob() 直接传给 RNFS.writeFile：blob 对象在某些 RN 版本中无法被正确序列化，务必通过 FileReader 转为 ArrayBuffer 后用 Buffer.from() 构造二进制数据；
- iOS 沙盒路径限制：RNFS.DocumentDirectoryPath 是安全的，但切勿使用 CachesDirectoryPath（可能被系统清理）或自定义绝对路径；
- expo-av 与 react-native-video 的差异：后者内部做了更多路径兼容层，而 expo-av 更严格遵循原生媒体 API 规范，因此必须提供标准 file:// URI；
- 服务端优化建议（进阶）：若可控后端，应启用 ETag + If-None-Match 缓存协商机制，避免重复下载未变更视频（如答案中所述），大幅降低带宽消耗。
✅ 总结
缓存视频的核心在于：路径生成 → 标准化 URI → 安全写入 → 正确加载。跳过 RNFS.pathToUri() 或手动拼接路径是绝大多数失败的根源。配合流式读写与错误兜底，即可在裸 RN + expo-av 环境中稳定实现高性能视频缓存。
