React Native离线优先应用开发最优方案及数据存储选型咨询

针对离线保存图片、视频并联网自动上传的需求，核心思路是本地分层存储+上传队列管理+网络状态触发，下面分模块详细说明：

一、数据存储选型 #

1. 媒体文件存储（大文件） #

• react-native-fs：最常用的跨平台文件系统操作库，可直接读写应用私有持久化目录（如iOS的Documents、Android的files目录），性能稳定，适合存储大体积的图片/视频。能轻松实现文件复制、删除、路径管理，权限可控性强。
• expo-file-system：如果基于Expo开发，这个库API更简洁，和Expo生态（如expo-image-picker）集成顺畅，同样支持持久化存储和文件操作。
• MediaLibrary（Expo）/CameraRoll：仅适合访问用户系统相册中的媒体，不建议存储应用生成或下载的文件——系统相册权限限制多，删除操作会影响用户本地相册，可控性差。

2. 元数据存储（上传队列、文件状态） #

元数据需要记录文件路径、上传状态、重试次数、服务器参数等信息，选型如下：

• Realm：轻量级本地NoSQL数据库，支持复杂查询、事务操作，性能优异。适合管理大量上传队列数据，能快速筛选待上传/失败的文件，状态更新原子性强，避免数据不一致。
• SQLite：通过react-native-sqlite-storage或expo-sqlite使用，适合结构化数据场景（如需要按时间、媒体类型统计上传记录），查询灵活，但操作比Realm繁琐。
• AsyncStorage：仅适合小量元数据（如少量待上传文件的ID列表），存储容量有限，不适合大量队列数据，且仅支持字符串存储，需要手动序列化/反序列化JSON。

二、核心实现方案 #

1. 离线存储流程 #

用户离线时完成两步操作：

1. 将媒体文件复制到应用私有持久化目录（避免被系统自动清理）；
2. 在本地数据库中创建上传队列条目，记录文件路径、媒体类型、初始状态（pending）、创建时间等。

2. 联网上传策略 #

• 网络状态监听：用@react-native-community/netinfo或expo-network监听网络切换，当设备从离线转为在线时，自动触发上传队列处理。
• 上传队列管理：
  • 优先处理状态为pending或failed（重试次数未达上限）的文件；
  • 采用指数退避重试：失败后依次等待1s、2s、4s再重试，最多重试3次，超过则标记为failed，等待用户手动触发；
  • 上传成功后，立即更新数据库状态为success，并删除本地文件（或移至归档目录备份）；
• 后台上传：对于大文件（如视频），使用react-native-background-upload或Expo的expo-background-fetch实现后台上传，避免应用退到后台后上传中断。

3. 关键细节处理 #

• 权限适配：iOS需配置NSPhotoLibraryUsageDescription、NSDocumentDirectory权限；Android 13+需申请READ_MEDIA_IMAGES/READ_MEDIA_VIDEO，低版本需READ_EXTERNAL_STORAGE/WRITE_EXTERNAL_STORAGE；
• 路径兼容性：注意iOS和Android的目录差异，用库提供的常量（如RNFS.DocumentDirectoryPath）获取标准路径，避免硬编码；
• UI状态同步：用Redux/MobX等状态管理工具实时同步上传进度、失败状态，在UI上展示进度条、重试按钮等。

三、代码示例片段 #

保存离线媒体 #

import RNFS from 'react-native-fs';
import Realm from 'realm';

// 定义Realm模型
const UploadQueueSchema = {
  name: 'UploadQueue',
  properties: {
    id: 'string',
    localPath: 'string',
    mediaType: 'string', // image/video
    status: 'string', // pending/failed/success
    retryCount: 'int',
    createdAt: 'date'
  },
  primaryKey: 'id'
};

const realm = await Realm.open({ schema: [UploadQueueSchema] });

const saveMediaOffline = async (mediaUri, mediaType) => {
  const fileName = `${Date.now()}.${mediaType === 'image' ? 'jpg' : 'mp4'}`;
  const destPath = `${RNFS.DocumentDirectoryPath}/${fileName}`;
  
  try {
    // 复制文件到应用私有目录
    await RNFS.copyFile(mediaUri, destPath);
    // 写入上传队列
    await realm.write(() => {
      realm.create('UploadQueue', {
        id: Date.now().toString(),
        localPath: destPath,
        mediaType,
        status: 'pending',
        retryCount: 0,
        createdAt: new Date()
      });
    });
    return true;
  } catch (error) {
    console.error('离线保存失败:', error);
    return false;
  }
};

网络监听与上传处理 #

import NetInfo from '@react-native-community/netinfo';

// 监听网络状态
NetInfo.addEventListener(async (state) => {
  if (state.isConnected) {
    await processUploadQueue();
  }
});

const processUploadQueue = async () => {
  // 获取待上传的文件
  const pendingItems = realm.objects('UploadQueue').filtered('status IN {"pending", "failed"} AND retryCount < 3');
  
  for (const item of pendingItems) {
    try {
      // 构造FormData上传
      const formData = new FormData();
      formData.append('media', {
        uri: item.localPath,
        type: item.mediaType === 'image' ? 'image/jpeg' : 'video/mp4',
        name: item.localPath.split('/').pop()
      });
      
      const response = await fetch('https://your-api-domain.com/upload', {
        method: 'POST',
        body: formData,
        headers: {
          'Content-Type': 'multipart/form-data'
        }
      });
      
      if (response.ok) {
        // 上传成功：更新状态+删除本地文件
        await realm.write(() => {
          item.status = 'success';
        });
        await RNFS.unlink(item.localPath);
      } else {
        throw new Error('服务器返回错误');
      }
    } catch (error) {
      // 上传失败：更新重试次数和状态
      await realm.write(() => {
        item.retryCount += 1;
        item.status = item.retryCount >= 3 ? 'failed' : 'pending';
      });
    }
  }
};

内容的提问来源于stack exchange，提问作者Leul Ayalew