React Native Firebase App 包版本演进全解读：从 TurboModules 迁移到线程安全 Handle 注册表

移动开发后端【免费下载链接】react-native-firebase A well-tested feature-rich modular Firebase implementation for React Native. Supports both iOS Android platforms for all Firebase services.项目地址https://gitcode.com/gh_mirrors/re/react-native-firebase点击查看免费下载本文基于react-native-firebase/app包packages/app/CHANGELOG.md的完整变更记录系统梳理 App/Core 模块在 v23 至 v26 期间的重大架构演进新架构New Architecture下 Codegen TurboModules 的强制迁移、RNFBHandleMap线程安全注册表的引入、firebase-js-sdk 类型对齐的 TypeScript 重构以及贯穿多个版本的底层 SDK 版本同步策略。读者将从中掌握 App 包的核心能力边界、升级时的破坏性变更清单以及如何将变更记录与源码实现相互印证从而安全、平滑地升级你的 React Native Firebase 项目。一、App 包在 react-native-firebase 生态中的定位react-native-firebase/app是所有 react-native-firebase 模块的核心基础依赖Core 包。它负责 Firebase 应用的注册与生命周期管理、原生桥接的解析、事件总线的建立、全局日志与偏好设置等基础设施是所有其他模块Auth、Firestore、Messaging 等运行的先决条件。从当前仓库的 packages/app/package.json 可以看到其技术底座版本与依赖当前版本26.4.0运行时依赖firebaseJS SDK12.18.0SDK 版本矩阵sdkVersions字段iOSfirebase-ios-sdk12.18.0iOS 目标15.0macOS 目标10.15tvOS 目标15.0AndroidminSdk23、targetSdk/compileSdk34firebase-android-sdk34.18.0google-services 插件4.5.0模块化输出通过react-native-builder-bob同时产出 ESM 模块dist/module与 TypeScript 类型dist/typescriptExpo 支持peerDependencies 将expo 47.0.0设为可选配套app.plugin.js配置插件。这个底层 SDK 版本矩阵 JS 桥接层的双层结构正是理解 App 包 CHANGELOG 中大量 SDK 版本升级条目的钥匙每次adopt firebase-ios-sdk X / firebase-android-sdk Y / firebase-js-sdk Z的提交都是在同步更新这个矩阵同时调整桥接层以适配原生 API 变化。二、v26.0.0App 模块强制迁移到 TurboModules重大变更CHANGELOG 中最重要的里程碑是v26.0.0。它标记了多个破坏性变更其中与 App 包直接相关的两条是app:App/Core modules native bridge requires New Architecture.app, android:在 Android 上makePlayServicesAvailable此前即使 Play Services 可用性任务被取消或失败也会 resolve现在它可能 reject调用方必须处理 Promise rejection。v26.0.0 将RNFBAppModule与RNFBUtilsModule迁移到了 Codegen TurboModules并引入了统一的 resolver、懒加载 Proxy 包装、以及已提交的生成产物。这意味着App/Core 的原生桥接现在要求 React Native 的 New Architecture旧架构Old Architecture不再受支持升级 v26 前必须先确认项目已启用新架构同版本中 Auth、Database、Installations、Messaging、Phone Number Verification 也一并迁移到 TurboModules且 Messaging 同样要求新架构形成全模块级的架构统一。从源码可以验证这一迁移的落点。App 包的 TurboModule 规范定义在 packages/app/specs/NativeRNFBTurboApp.tsexport interface Spec extends TurboModule { getConstants(): { NATIVE_FIREBASE_APPS: ArrayNativeFirebaseApp; FIREBASE_RAW_JSON: string; }; initializeApp(options: Object, appConfig: Object): PromiseObject; setAutomaticDataCollectionEnabled(appName: string, enabled: boolean): void; deleteApp(appName: string): PromiseObject | null; // 事件订阅与监听器管理 eventsNotifyReady(ready: boolean): void; eventsGetListeners(): PromiseObject; eventsPing(eventName: string, eventBody: Object): PromiseObject; eventsAddListener(eventName: string): void; eventsRemoveListener(eventName: string, all: boolean): void; addListener(eventName: string): void; removeListeners(count: number): void; // 元数据 / JSON 配置 / 偏好设置 metaGetAll(): PromiseObject; jsonGetAll(): PromiseObject; preferencesSetBool(key: string, value: boolean): PromiseObject | null; preferencesSetString(key: string, value: string): PromiseObject | null; preferencesGetAll(): PromiseObject; preferencesClearAll(): PromiseObject | null; setLogLevel(logLevel: string): void; }这份 spec 完整揭示了 App 包原生层对外暴露的六大能力域应用初始化与销毁initializeApp返回PromiseObject注意 v21.14.0 起被注释为 Promise 返回类型、deleteApp自动数据采集开关setAutomaticDataCollectionEnabled(appName, enabled)事件总线eventsNotifyReady/eventsPing/eventsGetListeners/eventsAddListener/eventsRemoveListener配合 RN 标准的addListener/removeListeners是 App 包跨模块事件分发如 App 状态变化的基础元数据与配置读取metaGetAll读取原生 metajsonGetAll读取打包进应用的 Firebase 配置文件对应 Android 的google-services.json/ iOS 的GoogleService-Info.plist偏好设置preferencesSetBool/preferencesSetString/preferencesGetAll/preferencesClearAll提供了跨模块的轻量 key-value 持久化日志级别setLogLevel。对应的原生侧映射配置在 package.json 的codegenConfig中android.javaPackageName为io.invertase.firebase.appiOS 侧将NativeRNFBTurboApp与NativeRNFBTurboUtils分别映射到RNFBAppModule与RNFBUtilsModule并声明includesGeneratedCode: true生成代码随包提交。同样值得关注的是 v26.0.0 附带的一组稳定性修复它们直接对应 App 模块 TurboModules 化后的工程质量防止事件在旧 ReactContext 上丢失关联 issue #1127、#8374事件发射器不再把事件投递给过期的 ReactContext跨代generation overlap时加固 emitter 的 attach/emitmakeGooglePlayServicesAvailable改在主线程执行RNFBAppModule与RNFBUtilsModule统一迁移并配套 codegen 验证与 spec-native 一致性测试即仓库中的specNativeParityHelper与 TurboModule 契约测试体系性能改进降低 TurboModule resolver 的开销。升级建议从 v25 及更早版本升级到 v26 时先对照 docs/migrating-to-v26.mdx 检查新架构开关同时审查所有调用makePlayServicesAvailable的代码路径为其补充.catch处理因为取消或失败的可用性检查现在会以 Promise rejection 形式暴露。三、v26.4.0RNFBHandleMap线程安全 Handle 注册表最新版本v26.4.0引入了一项基础能力重构app:add RNFBHandleMap for thread-safe handle registries3.1 设计动机为什么需要线程安全的句柄注册表在 TurboModules 架构下RN 的 JS 线程与原生线程共享同一批资源句柄listener、query、transaction 等。此前各模块自行用 map 管理这些句柄时若缺乏统一且正确的并发控制容易出现重复注册导致覆盖、并发读写竞态、以及在持锁状态下调用 SDK 的cancel/remove造成死锁。RNFBHandleMap正是为解决这些痛点而设计的通用基础设施。CHANGELOG 显示它在本版本中已开始被database 模块采用use RNFBHandleMap for transaction and query maps并在 auth、app-check 等模块的 registry 中被同步演进。3.2 源码级 API 解析Android 端实现位于 packages/app/android/src/main/java/io/invertase/firebase/common/RNFBHandleMap.javaiOS 端为 packages/app/ios/RNFBApp/RNFBHandleMap.h 与 RNFBHandleMap.m。两个平台提供了语义完全对齐的方法集方法语义适用场景put(id, handle)唯一注册id 已被占用时抛出RNFBHandleCollisionExceptioniOS 返回 NO 并填充RNFBHandleMapErrorCollision错误期望幂等、必须暴露冲突的注册putIfAbsent(id, handle)仅在 id 空闲时写入first wins重复注册可容忍、先到先得putIfAbsentOrSame(id, handle)空闲则写入已占用但为同一实例时返回成功不同实例返回失败幂等重建场景putReplacing(id, handle)原子替换last wins返回旧值需要覆盖旧注册get(id)只读窥探不移除供仍注册状态下 emit使用事件派发take(id)移除并返回常规注销takeIf(id, predicate)在同一把锁内完成查找 条件判断 移除需要原子 check-and-take 的场景takeAll()快照全部值后清空模块销毁 / 全量注销3.3 两个值得注意的实现约束从源码注释中可以提炼出RNFBHandleMap最重要的两条设计约束这也是它区别于普通线程安全 Map的关键锁只移动指针绝不在锁内调用被存对象的方法。类注释明确写道The lock only moves pointers; this class never invokes methods on stored values (no SDK cancel/remove)。调用方必须take/takeAll取出对象后在锁外执行 SDK 的 cancel/remove避免持锁期间触发重入或长时间阻塞不要在 map 实例上同步。Android 使用私有lock对象private final Object lockiOS 使用synchronized(self.lock)调用方若对 map 实例本身做synchronized(this)或synchronized(handleMap)可能与其他监控器产生死锁。Android 端的冲突类型 RNFBHandleCollisionException.java 被刻意设计为受检异常extends Exception而非RuntimeException强制调用方显式处理句柄 id 已被占用这一分支因为该 Map不支持 upsert——需要替换时必须自行take后put。3.4 v26.4.0 同批次的稳定性修复v26.4.0 还捆绑了一组覆盖面很广的 Bug Fixes多数与 App 包对 Web 侧与 JS 层的健壮性加固有关Web/内存存储保留空的 memory storage 值preserve empty memory storage values、支持任意 web storage keys、保留 memidb 事件监听器preserve memidb event listeners、保留全局 logger 配置、保留 Web Promise 契约文件与数据解析完整解析 data URL payloadparse data URL payloads completely、拒绝 FileReader 启动失败reject FileReader startup failures、处理空 Android Firebase JSONhandle empty Android Firebase JSONAndroid 生命周期丢弃投递给已关闭事务执行器的任务discard tasks posted to shut-down transactional executors自定义认证域名Android 与 iOS 同步清理过期的 custom auth domainsstale custom auth domainsauth 模块以 JS app name 查询customAuthDomains命名健壮性隔离原生路由键isolate native routing keys、支持原型同名应用support prototype-named apps、让 debug 原生代理行为安全make debug native proxies behavior-safeExpo补充缺失的 Firebase 导入add missing Firebase imports。这些修复表明App 包在 v26 系列中不仅完成了架构迁移还着力打磨了 Web/内存存储层memidb、memory storage与 Expo 场景的边界行为——如果你在 Expo 或 Web 目标上使用 react-native-firebasev26.4.0 属于值得优先升级的修复版本。四、v25.0.0 与 TypeScript 重构向 firebase-js-sdk 类型对齐v25.0.0 是另一个对使用者有直接影响的版本。它的破坏性变更虽然主要集中在remote-config与storage模块但 CHANGELOG 中有一段话阐明了整个项目的长期目标对理解 App 包也有意义react-native-firebase 的目标是成为 firebase-js-sdk 的 drop-in replacement即插即用替代品在 JS 层面一直如此运作但 TypeScript 类型此前存在分歧。随着我们向 TypeScript 重构正在逐步修复这一点使 react-native-firebase 在功能与精确的 TypeScript 类型上都尽可能与 firebase-js-sdk 对齐。具体到 Remote Configv25.0.0 的变更包括模块化类型改用 Firebase JS SDK 命名LogLevel、FetchStatus、Value、RemoteConfigSettingsRemoteConfig.settings改用RemoteConfigSettings其中使用fetchTimeoutMillis取代旧的fetchTimeMillis模块化getAll()/getValue()返回 SDK 对齐类型Recordstring, Value与Value删除了一批 RNFB 特有的模块化辅助导出fetchTimeMillis()、settings()、lastFetchStatus()、fetch()、setConfigSettings()、setDefaults()、onConfigUpdated()统一改为从实例属性读取或使用fetchConfig(remoteConfig)、onConfigUpdate(remoteConfig, observer)移除废弃的RemoteConfigValue.value/.sourcegetter改用asString()与getSource()。这一类型对齐路线同样体现在仓库的测试体系中App 包存在专门的turboModuleSpecNativeParity.test.ts与iosTurboModuleConstantsReturnTypeParity.test.ts用于在 CI 中校验 TypeScript spec 与原生实现返回类型的一致性——即 v26.0.0 提到的spec-native parity tests。五、SDK 版本同步时间线底层依赖的演进脉络App 包 CHANGELOG 中占比最大的一类条目是底层 Firebase SDK 的版本同步。将其串联起来可以得到一条清晰的时间线以下版本均为 CHANGELOG 记录值实际以当前仓库 packages/app/package.json 的sdkVersions为准RNFB App 版本firebase-ios-sdkfirebase-android-sdkfirebase-js-sdk关键配套要求v23.0.012.0.034.0.012.0.0iOS 15、Xcode 16.2Node v20 且 ES2020Android minSdk 23移除 Dynamic Linksv23.6.012.5.0/12.6.034.6.012.6.0—v24.1.1回退到 12.10.0避免启动崩溃——回退策略示例v25.0.012.12.034.13.012.12.1 → 12.13.0Xcode 26.2 强制要求v26.1.012.17.034.16.012.17.0新增 SPM 依赖解析支持与 CocoaPods 并存v26.3.012.18.034.18.012.17.1—这份时间线揭示了几个值得注意的运维要点SDK 升级往往带有工具链硬性要求v23.0.0 要求 Xcode 16.2 与 Node 20v25.0.0 明确 firebase-ios-sdk 12.12.0 要求 Xcode 26.2。升级 App 包前务必先核对 CI 与本地构建环境是否满足这些工具链最低版本存在刻意回退v24.1.1 将 iOS SDK 回退到 12.10.0 以规避上游启动崩溃说明底层 SDK 升级并非总是向前兼容紧跟 CHANGELOG 中的回退与已知问题注释十分必要SPM 支持是 v26 系列的重要增量v26.1.0 引入 SPM 依赖解析issue #8933v26.2.0 又支持通过 Expo config plugin 关闭 SPM。如果你在 iOS 上使用 Swift Package Manager 而非 CocoaPods可参考 docs/ios-spm.mdx 与 okf-bundle/ios-spm-native-imports.md 了解其导入机制Version bump only条目CHANGELOG 中大量条目如 v26.3.2、v25.0.1、v23.7.0标注为 Version bump only for package react-native-firebase/app表示该版本仅为 monorepo 发布节奏产生的版本号提升App 包本身无代码变更可放心升级。六、破坏性变更速查升级前必读清单综合 v23 至 v26 的 CHANGELOG整理 App 包相关及强关联的破坏性变更清单如下v26.0.0 — App/Core 原生桥接要求 New Architecture旧架构不再支持需先启用 RN 新架构v26.0.0 —makePlayServicesAvailable可能 reject调用方需处理 Promise rejection此前取消/失败也会 resolvev23.0.0 — 平台与工具链最低要求提升iOS 15 / Xcode 16.2Node v20 与 ES2020Android minSdk 从 21 提升到 23v23.0.0 — Dynamic Links 模块移除Dynamic Links 相关 API 不再可用请规划迁移v25.0.0 — remote-config/storage 模块类型与 API 对齐 firebase-js-sdkfetch()、setDefaults()、onConfigUpdated()等模块化辅助 API 被移除改从实例属性读取或使用新的模块化函数v21.0.0 — Firebase iOS SDK 升到 v11与 v23/v25 的工具链要求叠加构成 iOS 侧升级的主成本。升级路径建议先读迁移文档docs/migrating-to-v23.mdx、docs/migrating-to-v24.mdx、docs/migrating-to-v25.mdx、docs/migrating-to-v26.mdx按工具链 → 架构开关 → API 替换 → 行为变更四步走并在升级后运行仓库自带的 spec-native 一致性测试体系验证桥接层行为。七、从 CHANGELOG 到源码阅读与验证方法对于希望深入验证 CHANGELOG 条目的开发者本仓库提供了完整的可追溯路径TurboModule 契约App 包的 TypeScript 规范在 packages/app/specs/NativeRNFBTurboApp.ts 与 NativeRNFBTurboUtils.ts对应的原生实现可查看packages/app/android/src/main/java/io/invertase/firebase/与packages/app/ios/RNFBApp/线程安全注册表RNFBHandleMap的 Android/iOS 实现与配套测试如RNFBHandleMapTest.java、RNFBHandleMapTests.m位于packages/app/android/src/test/与packages/app/ios/RNFBAppUnitTests/其消费方database 的事务/查询注册表可参考packages/database/下的RNFBDatabaseTransactionRegistry等类Web 侧能力App 包的 Web 桥接与内存存储实现集中在 packages/app/lib/internal/web/含 memidb 实现与RNFBAppModule.ts可用于验证 v26.4.0 中preserve memidb event listenerspreserve empty memory storage values等条目的具体逻辑版本与构建信息版本号与 SDK 矩阵定义在 packages/app/package.json 的sdkVersions与codegenConfig字段构建脚本通过genversion同步生成各平台版本常量。八、总结react-native-firebase/app的 CHANGELOG 不仅是一份变更流水账更是一部 App/Core 模块的架构演进史从 v23 确立 iOS 15 / Android minSdk 23 的新基线到 v25 全面向 firebase-js-sdk 对齐 TypeScript 类型再到 v26 完成 TurboModules 强制迁移并引入RNFBHandleMap这一线程安全的基础设施。对于使用者而言最有价值的动作是以 CHANGELOG 为索引用仓库源码做验证——每个版本条目都能在specs/、android/src/、ios/RNFBApp/与lib/internal/web/中找到对应实现从而在升级前准确评估破坏性变更的影响面在升级后快速定位行为差异。赞分享移动开发后端【免费下载链接】react-native-firebase A well-tested feature-rich modular Firebase implementation for React Native. Supports both iOS Android platforms for all Firebase services.项目地址https://gitcode.com/gh_mirrors/re/react-native-firebase点击查看免费下载相关推荐如何用 Origin Protocol 构建自己的去中心化电商 DApp完整开发者教程如何用 Origin Protocol 构建自己的去中心化电商 DApp完整开发者教程 想打造一个不依赖中心化服务器、数据归用户所有、交易由智能合约自动执行的移动开发后端Firebase In-App Messaging iOS SDK 版本演进全解读从 0.11.0 到 12.19.0 的关键变更与迁移实践Firebase In App Messaging iOS SDK 版本演进全解读从 0.11.0 到 12.19.0 的关键变更与迁移实践 Firebase移动开发后端认证鉴权Reflex v0.9.x 版本演进全解析从多应用注册上下文到 React Router 8 迁移Reflex v0.9.x 版本演进全解析从多应用注册上下文到 React Router 8 迁移 本指南基于 Reflex 开源仓库根目录的 CHANGEL后端前端Web框架上一篇LikeC4 React组件集成在React应用中嵌入动态架构图下一篇你的RTX 4090终于有用了保姆级教程5分钟在本地跑起Grok-1效果惊人创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考