原生模块开发：跨平台团队的“国际协作手册”

可视化演示

展示React Native桥接架构三层通信、线程模型任务分发与事件发射Promise回调机制，支持模式切换。

原生模块概览

想象你是一家跨国公司的总部协调员。公司有两个本地办公室：一个在柏林（Android），一个在东京（iOS）。总部用的官方语言是 JavaScript，但柏林办公室内部用 Java/Kotlin 交流，东京办公室用 Swift/Objective-C 交流。总部想让他们执行某个任务（比如“读取手机电池电量”），不能直接对柏林同事说德语——总部不会说德语。这时候，就需要一本“协作手册”来规定：总部用英文下达标准的任务单，柏林办公室用德语执行后，把结果翻译成英文交回总部。在 React Native 的世界里，这本“协作手册”就是原生模块（Native Module）。

原生模块解决的正是 React Native 的能力边界问题。React Native 的 JavaScript 层能处理 UI 逻辑、业务状态，但遇到操作系统级别的功能——调用摄像头、读取通讯录、访问传感器——就鞭长莫及了。原因是 JavaScript 运行在受限的 JavaScriptCore（或 Hermes）引擎中，无法直接访问操作系统 API。原生模块就像在总部指挥中心和本地团队之间建立的一条专属热线，把原生的“本地能力”以 JavaScript 函数的形式暴露给 RN 代码调用。

原生模块的开发思路是双平台各自实现、JS 侧统一调用。也就是说，Android 团队用 Kotlin 写一套逻辑，iOS 团队用 Swift 写一套逻辑，两套逻辑完成同样的“任务”，但都在各自的办公室里用各自的语言干活。对于 JS 总部的指挥官来说，他只需要记住一个统一的 JavaScript API 名字，不需要关心底层是 Android 还是 iOS。这种“一个接口、双端实现”的模式，正是跨平台开发的精髓——总部只认手册上的标准流程，柏林和东京各自用自己的方式完成。

Android实现

让我们把镜头切到柏林的 Android 办公室。总部发来了一份任务单：“请实现一个模块，能够获取设备型号和电池电量。”柏林团队需要做的是：用他们的母语 Kotlin（或 Java）创建一个“本地团队”——准确地说，是一个继承自 ReactContextBaseJavaModule 的类。这个基类就像是柏林办公室的统一制服，穿上它，团队成员才能被总部识别。

第一步是重写 getName() 方法，这个方法返回一个字符串，就是这本协作手册里“柏林团队”的代号。总部将来调用时，就用这个名字来定位到柏林团队。比如返回 "DeviceInfo"，那么 JS 侧通过 NativeModules.DeviceInfo 就能找到它。这就像办公室门口的铭牌，让总部派来的信使一眼就能找到正确的门。

第二步是声明具体的方法，并用 @ReactMethod 注解标记。这个注解就是盖章——表示“这个方法可以接受总部的远程指令”。没有盖这个章的方法，即使写在类里，总部也无权调用。看一个典型例子：

需要注意的是参数类型。JS 侧传递过来的参数，在 Android 端被映射为标准的 Java/Kotlin 类型：Boolean、Double、String、ReadableMap（对应 JS 对象）、ReadableArray（对应 JS 数组）。如果你在 JS 侧传入了一个数字数组，在 Kotlin 侧收到的就是一个 ReadableArray。这就是手册里的“翻译规则”——总部语言中的每个词，柏林团队都规定了对应的德语词，不能随便翻译。

class DeviceInfoModule(reactContext: ReactApplicationContext) :     ReactContextBaseJavaModule(reactContext) {        override fun getName() = "DeviceInfo"        @ReactMethod    fun getBatteryLevel(promise: Promise) {        // 获取电池电量的原生代码        val level = getBatteryLevelFromSystem()        if (level != -1) {            promise.resolve(level)        } else {            promise.reject("ERROR", "无法读取电量")        }    }}

iOS实现

镜头转向东京的 iOS 办公室。东京团队接到的是同一份任务单，但他们用 Swift 来完成。在 iOS 的世界里，一个原生模块需要遵循 RCTBridgeModule 协议——这相当于东京办公室的“员工身份认证”。任何想要接收总部指令的类，都必须先签署这份协议，表明“我愿意遵守总部协作手册的规则”。

Swift 中实现原生模块的关键在于暴露给 Objective-C 运行时。由于 React Native 的桥接层是 Objective-C 写的，Swift 类需要通过 @objc 关键字将自己的方法和属性暴露给 Objective-C 运行时查看。类还要提供一个返回模块名的静态方法 moduleName()，这个方法的返回值就是 iOS 侧注册到总部的模块代号。这类似于柏林办公室的 getName()。

方法的导出使用 @objc 加 RCT_EXTERN_METHODS 宏（在 Objective-C 中）或在 Swift 中通过 @objc 标记方法并用 RCT_EXPORT_METHOD 宏导出。在 Swift 中通常这样写：

在 iOS 中，方法的回调方式有两种：一种是使用 RCTResponseSenderBlock（传统的回调函数方式），另一种是使用 RCTPromiseResolveBlock 和 RCTPromiseRejectBlock（Promise 方式）。现代 RN 开发中，Promise 方式更推荐，因为它在 JS 侧天然支持 async/await 语法，代码更简洁易读。

iOS 端的注意点是 Swift 与 Objective-C 的互操作。React Native 的模块系统底层用 Objective-C 的运行时动态查找方法，所以 Swift 中每一个要导出给 JS 的方法都必须标记 @objc，且方法签名必须符合桥接层的要求。如果方法签名写错了，桥接层找不到对应的方法，JS 侧调用就会直接报错——就像东京团队的门牌号写错了，总部的信使在楼里转了一圈也找不到人。

@objc(DeviceInfoModule)class DeviceInfoModule: NSObject, RCTBridgeModule {    static func moduleName() -> String! {    return "DeviceInfo"  }    @objc func getBatteryLevel(_ resolve: RCTPromiseResolveBlock,                             rejecter reject: RCTPromiseRejectBlock) {    let level = UIDevice.current.batteryLevel    if level >= 0 {      resolve(level)    } else {      reject(NSError(domain: "DeviceInfo", code: -1,                      userInfo: [NSLocalizedDescriptionKey: "无法读取电量"]))    }  }}

注册与导出

柏林和东京的团队都建设好了，但总部还需要一本完整的“通讯录”——所有团队的门牌号、专长领域、可接任务的清单。这就是模块的注册（Registration）环节。没有完成注册的模块，即使类写得再完美，总部也调用不到——就像团队没在总部人力系统备案，总部根本不知道有这个团队存在。

Android 端的注册流程是这样的：需要创建一个 ReactPackage 的实现类，在 createNativeModules() 方法中返回你的模块实例列表，然后用 addPackage() 方法把这个包添加到 MainApplication 的 getPackages() 列表中。代码看起来像这样：

iOS 端的注册相对简单。在 Objective-C 中，使用 RCT_EXPORT_MODULE() 宏就能完成注册；如果用 Swift，则通过 RCTBridgeModule 协议 + moduleName() 方法自动完成。iOS 还有一种导出控件的方法，但那是 View 相关的内容，我们这里只关注模块方法。

导出方法时需要注意的是参数类型的一一对应。JS 侧的方法参数与原生方法参数必须按顺序匹配——如果 JS 侧调用 getBatteryLevel()（无参数），但原生侧定义了 getBatteryLevel(promise: Promise)，桥接层仍然能找到方法，因为 Promise 是最后自动注入的；但如果 JS 侧传入 (string, number)，原生侧期望 (Double, String)，类型不匹配就会导致调用失败。这就好比总部发来的任务单上写着“用德语回复”，但柏林团队用日语回复——两边都懵了。

还有一个常见陷阱：Android 中导出方法时不要使用 Boolean 以外的 Java 包装类作为简单参数类型（如 Integer、Float），桥接层对基本类型映射最稳定。同时，方法的返回值必须为 void，结果必须通过回调或 Promise 返回——JS 和原生之间是异步通信，原生方法无法同步返回结果。这就像总部下达任务后不能站在门口等结果，而是先回办公室，等柏林团队完成后通过信使把结果送回总部。

class DeviceInfoPackage : ReactPackage {  override fun createNativeModules(reactContext: ReactApplicationContext):       List<NativeModule> = listOf(DeviceInfoModule(reactContext))    override fun createViewManagers(reactContext: ReactApplicationContext):       List<ViewManager<*, *>> = emptyList()}

线程与回调

现在，总部发出了调用指令，柏林团队和东京团队开始行动了。这时就涉及一个关键问题：任务在哪个“工作台”上执行？ React Native 的线程模型可以用一个三层办公室结构来理解：最顶层是 JS 线程（总部办公室），中间层是原生模块线程池（各团队的公共工作区），底层是 UI 主线程（团队的“客户接待室”）。

默认情况下，Android 的原生模块方法会在一个独立的原生线程池中执行，iOS 的方法会在桥接层分配的队列中执行——它们都不在主线程上。这样做的好处是：耗时操作（比如文件读取、网络请求）不会阻塞 UI。但坏处是：如果你在原生方法中直接操作 UI（比如弹一个 Toast 或者更新 View），就必须切换到主线程。Android 上使用 reactContext.runOnUiQueueThread()，iOS 上使用 DispatchQueue.main.async。

线程管理中最核心的概念是Promise 回调。总部（JS 侧）发出调用后不会干等着，而是留下一个“回执”——Promise。原生侧完成计算后，通过调用 promise.resolve(result) 或 promise.reject(error) 来回传结果。这个回传是异步的，总部收到后继续执行后续逻辑。JS 侧这样调用：

回调结果传递的过程中，需要注意两点。第一，回调可能从任意线程发出（执行任务的线程）；第二，JS 侧收到回调后会回到 JS 线程继续执行，这个过程由桥接层自动处理。但如果你在原生侧把一个耗时操作放到了后台线程，然后在这个后台线程里调用 resolve，这个 Promise 的“回传信使”会自动把结果带到 JS 线程——你不需要手动处理线程切换。

一个常见的问题是：在 Android 的原生方法中，如果你在后台线程执行完任务后，还想弹出 UI 提示（比如 Toast），就必须回到 UI 线程。RN 提供了专门的 API，Android 端可以直接使用 reactContext.getCurrentActivity()?.runOnUiThread { ... }。iOS 端在后台队列执行完任务后，如果要在主线程更新 UI，也需要手动切换到主队列。记住这个原则：耗时操作后台跑，UI 操作主线程，回调通过 Promise 异步送达。

const level = await NativeModules.DeviceInfo.getBatteryLevel();console.log('电池电量', level);

事件发射机制

前面讲的都是总部主动打电话给本地团队，那如果本地团队想主动向总部报告消息呢？比如电池电量下降到了 20%，或者用户截了一张图——这些是原生侧主动发生的事件，JS 总部并不知情。这时候就需要事件发射机制（Events）。这就好像东京办公室的传感器监测到了台风，需要主动向总部发警报——不需要总部先来问“今天天气怎么样”。

在 Android 端，事件发射通过 reactContext.getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java) 获取事件发射器，然后调用 emit(eventName, params) 发送事件。在 iOS 端则通过 self.bridge.eventDispatcher() 或 self sendEvent(withName:body:) 发送。两端的事件名必须一致，这样 JS 侧监听时才能用同一个名字。

JS 侧的监听方式如下：

这里最大的坑是生命周期管理。如果你在组件中注册了事件监听，但在组件卸载时没有移除监听，就会造成内存泄漏——JS 侧还保留着对原生事件的引用，原生侧反复发射事件，导致无用的回调不断触发。正确做法是：在 useEffect 的清理函数中调用 subscription.remove()，或者用 emitter.removeAllListeners('onBatteryLow')。

事件发射的另一个要点是跨平台统一。Android 的事件发射器和 iOS 的事件发射器在 JS 侧都归结为同一个 NativeEventEmitter API，你只需要在 JS 侧创建一个 emitter 实例，然后监听特定的事件名即可。事件名在两端的原生代码中必须完全一致——如果 Android 端发的是 "onBatteryLow"，iOS 端发的也是 "onBatteryLow"，JS 侧就能用同一个监听器处理两个平台的事件。这就好比柏林和东京虽然用不同的语言汇报，但汇报的标题栏都统一用英文填写，总部才能统一处理。

import { NativeEventEmitter, NativeModules } from 'react-native'; const { DeviceInfo } = NativeModules;const emitter = new NativeEventEmitter(DeviceInfo); const subscription = emitter.addListener('onBatteryLow', (data) => {  console.log('电量低！', data.level);}); // 不再需要时，记得移除监听subscription.remove();

优化与内存管理

最后，我们来聊聊让协作手册更高效的优化技巧。原生模块的每一次 JS 与原生之间的通信，都要经过桥接层的序列化、传输、反序列化——就像总部和本地团队之间每次通信都要派一个信使，信使来回跑是要耗费时间和体力的。如果总部每隔 100 毫秒就派一个信使去问“电池电量是多少”，不仅信使累垮，连总部和本地团队的工作效率都会下降。

第一项优化：减少桥接调用频率。 将频繁的小调用合并为一次大的调用。比如游戏应用中需要监听陀螺仪的连续数据，如果每帧都通过桥接传一次数据，性能会很差；更好的做法是原生侧积累 10 帧的数据后一次传给 JS。就像总部不要求柏林团队“每完成一个小任务就汇报一次”，而是“每完成一个阶段再统一汇报”。

第二项优化：合理管理监听器资源。 原生侧在 onCatalystInstanceDestroy（Android）或 invalidate（iOS）时，要清理所有注册的监听器和事件发射器。Android 端有专门的 onHostDestroy 回调，可以在 Activity 销毁时释放资源。这就像办公室下班时要关灯断电，不然一晚上电都白白浪费。

第三项优化：注意大对象和引用的释放。 不要让原生侧持有 JS 侧传递的大对象（如 ReadableMap、ReadableArray）的引用，因为 JS 侧的对象在原生侧引用后，JS 的垃圾回收无法回收它，会导致内存泄漏。正确的做法是：用完后立即置空引用，或者只提取需要的字段后丢弃原始对象。另外，Promise 回调对象不要长期持有——一旦 resolve 或 reject 之后，应该立刻释放引用，否则回调闭包持有的上下文不会被回收。

内存问题最典型的场景是：在原生模块中启动了一个长期运行的后台任务（比如位置监听），任务持有模块实例的引用，模块又持有 ReactContext 的引用，导致整个 Activity 无法被回收。这种问题在 Android 上尤其常见。解决办法是在模块的 invalidate() 方法中停止任务、清除监听器、释放引用。

AI 应用场景

Python 演示

import jsonimport threadingimport timefrom collections import defaultdict  class Promise:    """模拟 RN 的 Promise 回调对象"""    def __init__(self):        self._resolve = None        self._reject = None     def then(self, resolve, reject=None):        self._resolve = resolve        self._reject = reject        return self     def resolve(self, value):        if self._resolve:            self._resolve(value)     def reject(self, error):        if self._reject:            self._reject(error)  class NativeModuleBase:    """模拟原生模块基类（类似 ReactContextBaseJavaModule）"""    module_name = "BaseModule"     def getName(self):        return self.module_name  class AndroidDeviceModule(NativeModuleBase):    """模拟 Android 端原生模块（Kotlin 实现）"""    module_name = "DeviceInfo"     def __init__(self):        self._listeners = []     def getBatteryLevel(self, promise):        # 模拟异步获取电量        def _task():            time.sleep(0.1)            promise.resolve(85)        threading.Thread(target=_task).start()     def startBatteryMonitor(self, event_emitter):        # 模拟持续发射事件        def _monitor():            for i in range(3):                time.sleep(0.5)                event_emitter.emit("onBatteryChange",                                   {"level": 85 - i * 5})        threading.Thread(target=_monitor).start()  class IOSDeviceModule(NativeModuleBase):    """模拟 iOS 端原生模块（Swift 实现）"""    module_name = "DeviceInfo"     def getBatteryLevel(self, promise):        promise.resolve(88)  class Bridge:    """模拟桥接层：模块注册 + 方法分发 + 事件发射"""    def __init__(self):        self._modules = {}        self._event_listeners = defaultdict(list)        self._platform_impl = {}     def registerModule(self, module, platform):        self._modules[module.getName()] = module        self._platform_impl[module.getName()] = platform     def call(self, module_name, method_name, *args):        module = self._modules.get(module_name)        if not module:            raise RuntimeError(f"模块 {module_name} 未注册")        fn = getattr(module, method_name, None)        if not fn:            raise RuntimeError(f"方法 {method_name} 不存在")        promise = Promise()        last_arg = args[-1] if args else None        if isinstance(last_arg, Promise):            fn(*args[:-1], promise)        else:            fn(promise)        return promise     def emit(self, event_name, payload):        for cb in self._event_listeners[event_name]:            cb(payload)     def addListener(self, event_name, callback):        self._event_listeners[event_name].append(callback)     def removeListeners(self, event_name):        self._event_listeners[event_name].clear()  def main():    bridge = Bridge()     # 按平台注册模块（双平台同界面，同逻辑）    bridge.registerModule(AndroidDeviceModule(), "android")    bridge.registerModule(IOSDeviceModule(), "ios")     # JS 侧调用获取电量（走 Android 实现）    def on_resolve(value):        print(f"[JS] 收到电量: {value}%")    promise = bridge.call("DeviceInfo", "getBatteryLevel")    promise.then(on_resolve)     # JS 侧监听电池变化事件    bridge.addListener("onBatteryChange", lambda data:                       print(f"[JS] 事件: 电量变为 {data['level']}%"))     # 启动 Android 端的持续事件发射    android_module = bridge._modules["DeviceInfo"]    android_module.startBatteryMonitor(bridge)     # 让异步任务完成    time.sleep(2)    print("[JS] 移除事件监听")    bridge.removeListeners("onBatteryChange")  if __name__ == "__main__":    main()

1. promise.resolve(85)模拟原生侧异步任务完成后，通过 Promise 将结果回传给 JS 侧。
2. bridge.registerModule(AndroidDeviceModule(), "android")模拟按平台注册原生模块，实现“一个接口、双端实现”。
3. bridge.emit("onBatteryChange", {"level": ...})模拟原生侧主动发事件，JS 侧通过监听器接收。
4. module.getName()模拟原生模块返回名称，供桥接层索引调用。
5. event_emitter.emit()对应 RN 中 RCTDeviceEventEmitter 的事件发射机制。
6. bridge.addListener()对应 JS 侧 NativeEventEmitter.addListener() 注册监听。
7. getattr(module, method_name, None)模拟桥接层的动态方法查找与分发。
8. bridge.removeListeners()模拟组件卸载时移除监听，防止内存泄漏。

常见误区

面试题