在实际的 React Native 企业项目里接入 Firebird 数据库并不是一个特别冷门的需求。很多中小型 ERP、仓储、进销存系统长期使用 Firebird 作为底层数据库当管理层需要手机端查看库存、审批单据时App 端就必须面对“怎么连 Firebird”的问题。react-native-firebird 这类方案的核心思路就是通过原生桥接模块让 React Native 的 JavaScript 代码能够执行 Firebird 的 SQL 查询。这篇文章从 Firebird 的部署模式讲起分析直连与 API 代理两条路线的取舍然后以 Android 端最小桥接模块为例给出连接、查询、关闭连接的完整实现最后覆盖连接参数、结果映射、运行验证和常见问题排查。读完可以复现一个能连上 Firebird 的最小 React Native 示例也可以拿这套排查思路去解决启动白屏、中文乱码和连接超时。1. 先搞清楚 Firebird 为什么不能直接在 React Native 里用1.1 Firebird 数据库的基本定位Firebird 是一个开源的关系型数据库管理系统代码源自 InterBase。它的强项是体积小、部署轻、SQL 兼容性较好支持存储过程、触发器、事务、行级锁以及从 GBK、ISO8859_1 到 UTF8 的多种字符集。生产环境中它通常以服务端模式运行数据库文件由 firebird 守护进程管理应用通过 TCP 端口 3050 连接在嵌入式场景中应用进程可以直接打开数据库文件不需要独立服务。对移动端来说Firebird 的直接价值在于企业已有的数据都在 Firebird 里App 要访问这些数据就不能像新项目一样随意选型。先弄清楚 Firebird 的运行模式才能决定移动端架构走哪条路。1.2 React Native 运行时缺少 Firebird 客户端协议很多开发者会误以为在 JavaScript 里能写 MySQL 连接字符串Firebird 也应该可以。但 React Native 的运行环境和 Node.js 并不一样。React Native 的 JavaScript 引擎负责 UI 和业务逻辑它没有完整的阻塞式 Socket 客户端也没有现成的 Firebird 协议解析器Firebird 官方客户端是 C 语言库libfbclientJava 生态则有 Jaybird 这样的纯 Java JDBC 驱动。这两类库都无法直接作为 npm 包运行在 JS 层。要让 React Native 连上 Firebird必须经过原生桥接层。这个“必须经过原生层”的结论决定了整篇文章的走向Android 端要写 Java/KotliniOS 端要写 Swift/Objective-CJavaScript 端只负责定义接口和接收结果。1.3 三条技术路线直连、嵌入式与 API 代理开始写代码之前先明确业务场景因为不同场景对应的技术路线差别很大。方案客户端复杂度服务端要求数据同步适用场景直连原生模块高内网可达3050 端口开放无内网移动办公、原型验证嵌入式数据库高无需服务端需要手动同步离线场景、单机数据采集服务端 API 代理低需要额外服务端开发可选外网访问、多用户并发、生产系统直连方案适合学习验证能让你最快看到 SQL 查询结果API 代理才是多数生产项目的最终形态。后文先讲直连因为它的每一步链路都是可见的排查问题也更直观。2. 环境准备先确认版本、网络和测试数据2.1 基础环境清单开始前先确认本机环境避免把时间浪费在环境兼容性上。下面这张表是常见组合具体版本以官方文档为准。工具用途建议版本Node.js运行 React Native CLI18 LTS 或更高JDKAndroid 编译JDK 17Android StudioAndroid SDK 和模拟器最新稳定版XcodeiOS 编译随系统版本Firebird数据库服务或嵌入式库2.5 / 3.0 / 4.0 任选如果公司服务器上已经有 Firebird先确认版本因为 2.5 和 4.0 在字符集、SQL 语法上有差异Jaybird 版本也要匹配。如果还没有服务端在自己的开发机装一个最新稳定版即可。2.2 准备 Firebird 服务端和测试数据安装完成后用 isql 创建一个测试数据库。下面命令在 Linux 环境示意Windows 下路径和命令略有差异思路一样isql -user SYSDBA -password 你的密码进入 isql 后执行CREATE DATABASE /var/lib/firebird/3.0/data/demo.fdb; CREATE TABLE CUSTOMERS ( ID INTEGER NOT NULL PRIMARY KEY, NAME VARCHAR(100), CITY VARCHAR(50), CREATED_AT TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); INSERT INTO CUSTOMERS (ID, NAME, CITY) VALUES (1, 张三, 北京); INSERT INTO CUSTOMERS (ID, NAME, CITY) VALUES (2, 李四, 上海); COMMIT; QUIT;注意这里直接用了 UTF8 中文字符实际项目中还要确认数据库默认字符集。Firebird 数据库在创建时如果没有显式指定字符集默认可能是 NONE这时写入中文可能出现字符集不兼容错误。建议创建数据库时带上字符集CREATE DATABASE /var/lib/firebird/3.0/data/demo.fdb USER SYSDBA PASSWORD 你的密码 PAGE_SIZE 8192 DEFAULT CHARACTER SET UTF8;2.3 创建并验证 React Native 项目在接入 Firebird 之前先保证一个干净的 React Native 项目能跑起来npx react-native init RnFirebirdDemo cd RnFirebirdDemoAndroid 模拟器直接运行npx react-native run-android这一步能做到 App 正常启动说明 RN 环境、SDK、模拟器链路都是通的。如果这个基础项目都白屏应该先解决环境问题再叠加 Firebird 原生模块否则问题不好定位。注意不要跳过基础验证。很多原生模块集成失败最后追查下来是 RN 环境本身的问题。3. 最小可运行桥接Android 端用 Jaybird 实现连接与查询3.1 为什么 Android 端优先考虑 JaybirdJaybird 是 Firebird 官方 Java 生态的 JDBC 驱动纯 Java 实现。这意味着在 Android 原生模块里只需要把一个 jar 包放进工程用DriverManager.getConnection就能连接 Firebird不需要编译 C 库不需要处理 Android NDK 的架构适配。对比直接使用 libfbclient 的 JNI 封装Jaybird 的集成成本低很多适合作为第一版验证方案。Jaybird 的下载方式一般是 Maven 仓库。在 Android 工程中可以先把 jar 放到android/app/libs然后在android/app/build.gradle里加依赖dependencies { implementation files(libs/jaybird-4.0.5.jar) }版本号要以你实际下载的为准。如果使用新版 Jaybird注意它要求 Java 8 以上Android 端通常没问题。3.2 原生模块的 connect、query、close 实现在android/app/src/main/java/com/rnfirebird/目录下新建FirebirdModule.java。这个类继承ReactContextBaseJavaModule是 React Native 桥接的标准写法package com.rnfirebird; import com.facebook.react.bridge.Arguments; import com.facebook.react.bridge.Promise; import com.facebook.react.bridge.ReactApplicationContext; import com.facebook.react.bridge.ReactContextBaseJavaModule; import com.facebook.react.bridge.ReactMethod; import com.facebook.react.bridge.WritableArray; import com.facebook.react.bridge.WritableMap; import java.sql.Connection; import java.sql.DriverManager; import java.sql.ResultSet; import java.sql.ResultSetMetaData; import java.sql.Statement; import java.util.concurrent.ExecutorService; import java.util.concurrent.Executors; public class FirebirdModule extends ReactContextBaseJavaModule { private final ExecutorService executor Executors.newSingleThreadExecutor(); private Connection connection; public FirebirdModule(ReactApplicationContext reactContext) { super(reactContext); } Override public String getName() { return RNFirebird; } ReactMethod public void connect(String host, int port, String database, String user, String password, String charset, Promise promise) { executor.execute(() - { try { Class.forName(org.firebirdsql.jdbc.FBDriver); String url jdbc:firebirdsql:// host : port / database; if (charset ! null !charset.isEmpty()) { url url ?charSet charset; } connection DriverManager.getConnection(url, user, password); WritableMap result Arguments.createMap(); result.putBoolean(connected, true); promise.resolve(result); } catch (Exception e) { promise.reject(CONNECT_FAILED, e.getMessage(), e); } }); } ReactMethod public void query(String sql, Promise promise) { executor.execute(() - { if (connection null) { promise.reject(NOT_CONNECTED, 请先调用 connect); return; } try (Statement stmt connection.createStatement(); ResultSet rs stmt.executeQuery(sql)) { ResultSetMetaData metaData rs.getMetaData(); int columnCount metaData.getColumnCount(); WritableArray rows Arguments.createArray(); while (rs.next()) { WritableMap row Arguments.createMap(); for (int i 1; i columnCount; i) { String columnName metaData.getColumnLabel(i); Object value rs.getObject(i); putValue(row, columnName, value); } rows.pushMap(row); } promise.resolve(rows); } catch (Exception e) { promise.reject(QUERY_FAILED, e.getMessage(), e); } }); } ReactMethod public void close(Promise promise) { executor.execute(() - { try { if (connection ! null !connection.isClosed()) { connection.close(); } connection null; promise.resolve(true); } catch (Exception e) { promise.reject(CLOSE_FAILED, e.getMessage(), e); } }); } private void putValue(WritableMap map, String key, Object value) { if (value null) { map.putNull(key); } else if (value instanceof String) { map.putString(key, (String) value); } else if (value instanceof Number) { map.putDouble(key, ((Number) value).doubleValue()); } else if (value instanceof Boolean) { map.putBoolean(key, (Boolean) value); } else { map.putString(key, value.toString()); } } }这段代码有三个关键点。第一所有数据库操作都放在ExecutorService里执行避免阻塞 React Native 的 UI 线程。第二Promise是异步回调机制JS 层调用后不会卡住界面。第三putValue把 JDBC 的Object类型转成 React Native 能识别的WritableMap类型这是结果映射的核心。3.3 注册模块到 React Native 工程新建FirebirdPackage.javapackage com.rnfirebird; import com.facebook.react.ReactPackage; import com.facebook.react.bridge.NativeModule; import com.facebook.react.bridge.ReactApplicationContext; import com.facebook.react.uimanager.ViewManager; import java.util.ArrayList; import java.util.Collections; import java.util.List; public class FirebirdPackage implements ReactPackage { Override public ListNativeModule createNativeModules(ReactApplicationContext reactContext) { ListNativeModule modules new ArrayList(); modules.add(new FirebirdModule(reactContext)); return modules; } Override public ListViewManager createViewManagers(ReactApplicationContext reactContext) { return Collections.emptyList(); } }然后在MainApplication.java的getPackages里注册Override protected ListReactPackage getPackages() { ListReactPackage packages new PackageList(this).getPackages(); packages.add(new FirebirdPackage()); return packages; }如果你的 React Native 版本较新使用的是 Turbo Module 架构注册方式会不同但桥接的思路不变。建议先按传统 Bridge 方式跑通再根据项目实际架构迁移。4. iOS 桥接思路与 JavaScript 接口统一4.1 iOS 端依赖 libfbclient 的成本Android 端用 Jaybird 是纯 Java集成成本低。iOS 端则要面对 Firebird 官方 C 客户端库。你把libfbclient.dylib或.a文件引入 Xcode 工程后还需要解决符号链接、头文件路径、架构切片arm64、模拟器 x86_64等问题。这也是为什么很多团队在 iOS 端选择让原生模块通过 URLConnection 访问一个 API 代理而不是直连 Firebird。如果坚持原生直连需要确认几个前置条件本机能拿到 libfbclient 库、能正确配置 header search path、能处理模拟器和真机的架构差异。这一套在 CI 环境里非常容易出错建议在文档里保留一份明确的编译步骤。4.2 Swift 桥接模块的最小写法假设你已经把 Firebird 客户端库接入 Xcode 工程Swift 桥接模块大概长这样import Foundation import React objc(FirebirdModule) class FirebirdModule: NSObject { private var connection: OpaquePointer? objc func connect( _ host: String, port: NSNumber, database: String, user: String, password: String, charset: String, resolve: escaping RCTPromiseResolveBlock, reject: escaping RCTPromiseRejectBlock ) { // 使用 libfbclient 的 isc_attach_database 建立连接 // 这里省略 C API 的具体调用实际项目需要引入头文件并处理错误码 resolve([connected: true]) } objc func query( _ sql: String, resolve: escaping RCTPromiseResolveBlock, reject: escaping RCTPromiseRejectBlock ) { // 执行 SQL把结果数组转成字典数组再通过 resolve 返回 } objc static func requiresMainQueueSetup() - Bool { return false } }上面这段代码是示意不是完整可编译版本。真实项目中isc_attach_database的参数处理、错误码转义、XSQLDA结果绑定都有一大段样板代码。这就是为什么很多开源库选择在 iOS 端直接用 C 封装一层而不是在 Swift 层写完整逻辑。4.3 JavaScript 层封装通用 API无论 Android 还是 iOSJS 层调用接口应该保持完全一致。新建firebird.jsimport { NativeModules } from react-native; const { RNFirebird } NativeModules; export const connect (options) { return RNFirebird.connect( options.host, options.port, options.database, options.user, options.password, options.charset || UTF8 ); }; export const query (sql) { return RNFirebird.query(sql); }; export const close () { return RNFirebird.close(); };JS 层只做参数透传和返回结果处理。连接管理、SQL 执行、异常处理都在原生层完成这样两端行为一致也方便以后换成 API 代理时只改这一层。注意不要在 JS 层用setTimeout模拟异步数据库连接是原生资源生命周期必须由原生层管理。5. 连接参数、结果映射与运行验证5.1 连接参数速查表连接 Firebird 时以下几个参数会决定能否连通、能否正确处理中文参数说明常见值默认值hostFirebird 服务器地址192.168.1.10localhostportFirebird 服务端口30503050database数据库文件绝对路径或别名/var/lib/firebird/data/demo.fdb无user数据库用户SYSDBA无password用户密码安装时设置无charset客户端字符集UTF8NONEcharset这个参数最容易被忽略。Firebird 服务端字符集、数据库默认字符集、客户端连接字符集三者必须统一否则中文会乱码甚至写入时报字符串截断错误。5.2 查询结果从 ResultSet 到 JS 对象的映射原生层拿到ResultSet后需要把每一行转成一个WritableMap再把所有行放进WritableArray。JS 层接收到的是一组 JSON 对象例如[ { ID: 1, NAME: 张三, CITY: 北京 }, { ID: 2, NAME: 李四, CITY: 上海 } ]需要注意JDBC 的getObject对TIMESTAMP类型可能返回java.sql.Timestamp在putValue里会被当作 Object 调用toString()最终变成一串字符串。如果业务层需要时间戳的数值要在原生层做类型转换不能指望 JS 层自动解析。5.3 完整调用示例与预期输出在 React Native 的 App.js 里这样调用import React, { useEffect } from react; import { View, Text, Button } from react-native; import { connect, query, close } from ./firebird; function App() { const loadData async () { try { await connect({ host: 192.168.1.10, port: 3050, database: /var/lib/firebird/3.0/data/demo.fdb, user: SYSDBA, password: 你的密码, charset: UTF8 }); const rows await query(SELECT ID, NAME, CITY FROM CUSTOMERS); console.log(查询结果, JSON.stringify(rows)); await close(); } catch (e) { console.error(错误码, e.code, 错误信息, e.message); } }; return ( View Button title查询客户数据 onPress{loadData} / Text打开 Metro 日志查看结果/Text /View ); } export default App;启动后点击按钮Metro 控制台应该输出类似下面的内容查询结果 [{ID:1,NAME:张三,CITY:北京},{ID:2,NAME:李四,CITY:上海}]能输出这行 JSON说明从 React Native 到原生模块再到 Firebird 的整条链路已经打通。6. 常见问题排查白屏、超时、乱码与库链接6.1 按什么顺序排查接入 Firebird 桥接后如果出现问题不要一头扎进数据库代码里。按照下面的优先级排查基础 RN 项目是否能正常启动。原生模块是否成功注册JS 层能否找到RNFirebird。连接参数是否填对尤其是 host 和端口。网络和防火墙是否放行。字符集配置是否统一。原生库是否链接成功架构是否匹配。日志里是否出现明确异常。这个顺序能覆盖大多数问题。下面几个常见场景单独展开。6.2 React Native 启动白屏检查路径启动白屏是集成原生模块后很常见的问题。它通常不是 Firebird 代码本身的问题而是原生工程没有正确加载或 JS 崩溃。按以下路径检查Metro 是否在运行。npx react-native start没启动时App 会一直白屏。查看 Metro 终端日志是否有红色报错。Android 上执行adb logcat | grep AndroidRuntime看是否有ClassNotFoundException或NativeModule注册失败。检查MainApplication.java里的getPackages是否真的把FirebirdPackage加进去了。如果最近改过原生代码需要重新编译不能只刷新 JS。问题现象常见原因检查方式处理建议启动后无限白屏Metro 未启动看 Metro 终端重新执行npx react-native start白屏并在日志里出现模块找不到原生模块未注册adb logcat检查getPackages和包名白屏但 JS 能加载原生库崩溃导致主进程退出adb logcat AndroidRuntime查看崩溃栈定位到原生层6.3 连接超时和拒绝连接连接超时通常不是代码问题而是网络链路问题。先做两步验证。ping 192.168.1.10 telnet 192.168.1.10 3050telnet 能通说明端口可达。如果 ping 通但 telnet 不通检查服务端防火墙是否放行 3050 端口。如果是 Android 模拟器访问宿主机host 不要写localhost应该写宿主机局域网 IP 或10.0.2.2模拟器访问宿主机专用地址。6.4 中文乱码与字符集不一致Firebird 中文乱码常见原因数据库创建时没有指定字符集默认是 NONE。连接 URL 没有带charSetUTF8。表和字段的字符集与服务端不一致。检查方式SELECT RDB$CHARACTER_SET_NAME FROM RDB$DATABASE;如果显示 NONE最好重建数据库或调整字段字符集。代码层面统一 UTF8String url jdbc:firebirdsql:// host : port / database ?charSetUTF8;6.5 原生库链接失败或架构不匹配如果使用 libfbclient 而不是 Jaybird在 iOS 真机和模拟器之间切换时经常遇到Undefined symbols for architecture x86_64这是因为.a静态库只包含 arm64 切片没有 x86_64。解决方案是重新编译库加入两个架构的切片或者用 Xcode 的EXCLUDED_ARCHS排除不需要的架构。Android 端如果使用 NDK 引入 C 库同样要处理 armeabi-v7a、arm64-v8a、x86 的差异。7. 生产环境建议从直连走向 API 代理7.1 直连方案的几个风险直连方案在验证阶段很好用但放到生产环境要评估四个风险数据库账号密码存放在客户端反编译后可以直接提取。Firebird 的 3050 端口暴露到公网后会面对暴力破解。客户端直连数据库时无法做细粒度的接口权限控制。最重要的是所有客户端共享同一个数据库账号出现问题无法审计到具体用户。7.2 推荐的生产架构API 代理 连接池更稳妥的方式是让 React Native 通过 HTTPS 访问自己的后端 API由后端服务统一连接 Firebird。后端可以使用 Java Jaybird也可以使用 Python、Node.js 等语言
