React Native Firebase v22 迁移指南：从命名空间 API 到模块化 API

React Native Firebase v22 迁移指南：从命名空间 API 到模块化 API

前言

React Native Firebase 是一个广受欢迎的 React Native 模块，它为开发者提供了完整的 Firebase 功能支持。随着 v22 版本的发布，项目将全面转向模块化 API 架构，这与 Firebase JavaScript SDK 的最新架构保持一致。本文将详细介绍如何从旧版命名空间 API 迁移到新的模块化 API。

为什么要迁移到模块化 API？

模块化 API 是 Firebase 官方推荐的现代编程方式，它具有以下优势：

1. 更好的 Tree Shaking：只导入实际使用的功能，减少包体积
2. 更清晰的代码结构：每个功能都有明确的导入路径
3. 与 Web SDK 一致性：保持与 Firebase Web SDK 相同的开发体验
4. 更好的类型支持：TypeScript 类型推断更准确

准备工作

关闭警告日志

在迁移过程中，你可能会看到大量关于命名空间 API 弃用的警告日志。可以通过以下方式关闭这些警告：

globalThis.RNFB_SILENCE_MODULAR_DEPRECATION_WARNINGS = true;

建议在 Firebase 初始化之前设置此全局变量。

启用严格模式（可选）

如果你想快速定位所有仍在使用的命名空间 API，可以启用严格模式：

globalThis.RNFB_MODULAR_DEPRECATION_STRICT_MODE = true;

启用后，任何命名空间 API 的使用都会抛出 JavaScript 错误，通过堆栈跟踪可以快速定位问题代码。

迁移方法论

迁移过程遵循以下通用步骤：

1. 确定当前使用的命名空间 API 对应的模块化 API 函数
2. 从相应模块导入新的 API 函数
3. 重构调用方式：从通过 firebase 模块访问 API 改为直接使用模块化函数

这个过程是机械式的，可以逐个 API 逐步迁移。

实战示例：Firestore 迁移

旧版命名空间 API（已弃用）

import firestore from '@react-native-firebase/firestore';

const db = firestore();

const querySnapshot = await db.collection('cities').where('capital', '==', true).get();

querySnapshot.forEach(doc => {
  console.log(doc.id, ' => ', doc.data());
});

新版模块化 API

import { collection, query, where, getDocs, getFirestore } from '@react-native-firebase/firestore';

const db = getFirestore();

const q = query(collection(db, 'cities'), where('capital', '==', true));

const querySnapshot = await getDocs(q);

querySnapshot.forEach(doc => {
  console.log(doc.id, ' => ', doc.data());
});

主要变化：

1. 使用 getFirestore() 替代 firestore()
2. 使用 collection() 函数替代 .collection() 方法
3. 使用 query() 和 where() 组合查询条件
4. 使用 getDocs() 替代 .get() 方法

各模块迁移参考

虽然具体 API 有所不同，但所有模块的迁移模式都类似。以下是一些常见模块的迁移方向：

认证 (Auth)

• 使用 getAuth() 替代 auth()
• 使用模块化函数如 signInWithEmailAndPassword() 替代方法调用

实时数据库 (RTDB)

• 使用 getDatabase() 替代 database()
• 使用 ref() 和 get() 等函数替代链式调用

云存储 (Storage)

• 使用 getStorage() 替代 storage()
• 使用 ref() 和 uploadBytes() 等函数替代方法调用

远程配置 (Remote Config)

• 使用 getRemoteConfig() 替代 remoteConfig()
• 使用 fetchAndActivate() 等函数替代方法调用

迁移建议

1. 逐步迁移：不必一次性完成所有迁移，可以按功能模块逐步进行
2. 利用类型提示：如果使用 TypeScript，IDE 的类型提示会帮助你找到正确的导入路径
3. 参考官方文档：虽然 React Native Firebase 有特定实现，但大部分 API 与 Web SDK 文档一致
4. 测试验证：迁移后务必进行全面测试，确保功能正常

结语

迁移到模块化 API 是 React Native Firebase 发展的必然方向，虽然需要一些适应，但最终会带来更好的开发体验和应用性能。本文提供的指南和示例应该能帮助你顺利完成 v22 版本的迁移工作。如果在迁移过程中遇到特定问题，建议查阅对应模块的详细文档或类型定义。