如何在React Native Expo应用中启用Firebase Firestore离线持久化？

1. 显式启用离线持久化 #

尽管官方文档说明Android/iOS默认开启Firestore离线持久化，但Expo环境中可能需要手动触发。修改你的Firestore初始化代码，添加持久化启用逻辑：

import { initializeApp } from "firebase/app";
import { getFirestore, enablePersistence } from "firebase/firestore";

import { firebaseConfig } from "./config";

const app = initializeApp(firebaseConfig);
const db = getFirestore(app);

// 启用离线持久化并捕获异常
enablePersistence(db)
  .catch((err) => {
    if (err.code === 'failed-precondition') {
      console.log('持久化失败：应用存在多实例冲突');
    } else if (err.code === 'unimplemented') {
      console.log('当前环境不支持离线持久化');
    }
  });

export { db };

2. 确保数据已被缓存 #

Firestore仅缓存成功获取过的数据，如果在线时仅通过getDoc获取单个文档，那么getDocsFromCache查询整个集合会因无缓存数据返回空。

• 单文档离线访问：在线时必须调用过getDoc获取目标文档，离线时再次调用getDoc会自动读取缓存。
• 集合离线访问：在线时必须调用过getDocs查询目标集合，Firestore才会缓存集合数据，离线时getDocsFromCache才能生效。

修改你的数据获取方法，增加缓存降级逻辑：

import { db } from "../index";
import {
  collection,
  doc,
  getDoc,
  getDocs,
  getDocsFromCache,
} from "firebase/firestore";

export const firestoreService = {
  get: async <T>(collectionName: string, id: string): Promise<T | null> => {
    const docSnap = await getDoc(doc(db, collectionName, id));
    return docSnap.exists() ? (docSnap.data() as T) : null;
  },

  getAll: async <T>(collectionName: string): Promise<T[]> => {
    try {
      // 优先从缓存读取
      const querySnapshot = await getDocsFromCache(collection(db, collectionName));
      return querySnapshot.docs.map(doc => ({ id: doc.id, ...doc.data() } as T));
    } catch (err) {
      // 缓存读取失败时，在线获取并缓存数据
      const querySnapshot = await getDocs(collection(db, collectionName));
      return querySnapshot.docs.map(doc => ({ id: doc.id, ...doc.data() } as T));
    }
  },
};

3. 配置Expo文件系统权限 #

Firestore需要文件系统权限存储离线缓存，在app.json或app.config.js中添加权限配置：

{
  "expo": {
    "ios": {
      "infoPlist": {
        "NSFileProtectionKey": "NSFileProtectionNone"
      }
    },
    "android": {
      "permissions": ["READ_EXTERNAL_STORAGE", "WRITE_EXTERNAL_STORAGE"]
    }
  }
}

4. 修正离线测试流程 #

确保缓存被正确写入：

• 在线状态下，必须成功调用过目标数据的获取方法（如get或getAll），等待数据加载完成。
• 完全关闭应用（而非后台挂起），开启飞行模式后重新打开应用，验证数据显示。

5. 排查缓存失效原因 #

如果以上步骤无效，检查以下情况：

• 是否有代码调用clearPersistence()清空了离线缓存。
• 设备是否禁用了应用的存储权限，导致Firestore无法写入缓存文件。

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