企业官网建设流程全解析

做跨平台开发时间长了，你迟早会撞上一面墙：JS/TS 层写不出系统级的能力。不管你是用 React Native、Flutter 还是 uni-app，凡是涉及 Android/iOS 系统专属接口——读电池电量、识别 NFC 标签、接入硬件扫码枪、调用系统分享面板——纯业务层基本碰不到。这时候，Native Modules（原生模块）就是打破边界的那把锤子。

这篇文章我会用一套完整的双端实战代码，带你从零写一个原生模块：从 Android Kotlin 到 iOS Swift，从桥接原理到调试避坑，把常见报错和性能红线一并说清楚。适合已经能跑通 Hello World，但没正经写过原生模块的跨端开发者。

1. 为什么需要原生模块：必须打破的四种边界

1.1 跨平台框架封不住的场景

很多人误以为跨平台框架“什么都能干”，真到了生产环境你会发现自己太乐观。我整理了一下这几年实际遇到过的场景，凡是必须上原生模块的，基本跑不出这四类：

第一类是系统状态读取。比如业务需要展示电池电量、当前网络类型（Wi-Fi 还是蜂窝）、设备型号、内存占用。这些数据都在系统底层，JS 层没有入口，只能通过原生代码拿。

第二类是硬件外设交互。蓝牙 BLE 扫码枪、身份证读卡器、POS 收银机、NFC 标签、甚至是接了个串口设备。硬件厂商给的 SDK 大多是 Java/Kotlin 或 Objective-C/Swift 的，跨平台框架不可能帮你封装好，必须你手动包一层原生模块。

第三类是系统级 UI 能力。Android 的 App Shortcuts、iOS 的 Share Sheet、两个平台各有各的桌面小组件，这类系统 UI 组件跨平台框架覆盖得很浅，尤其是 iOS 的某些系统弹窗，只能原生弹。

第四类是性能敏感的算法逻辑。比如大图压缩、音视频处理、加解密运算，这些在 JS 层跑又慢又容易卡 UI，放到原生层做，性能差距是肉眼可见的。我做过一个视频拼接需求，JS 层实现要 8 秒，原生写 1 秒不到就出来了。

1.2 三种主流框架的原生模块写法

既然确定要打破边界，先看看你手头框架的“原生扩展口”长什么样。现在主流的三套跨平台方案，底子完全不同：

光看通信方式就能理解，React Native 是“消息桥”思路，JS 把方法名和参数打包扔给原生，原生执行完再扔回来；Flutter 是“通道”思路，一条双向管道直接传二进制数据；uni-app 则在框架层自己封了一层事件系统。

这里我不打算拉踩框架，三个我都用过的结论是：只要基础概念通了，换框架只是换 API 壳子。这篇文章以 React Native 为主演示，原因是它的“Native Modules”概念在社区里沉淀最久、资料最多、报错也最经典。看完这套，你切换到 Flutter 或 uni-app 时，理解成本会低很多。

1.3 该不该自研：第三方库和自研的选择

碰到需要原生能力的需求，第一反应是去 npm 搜现成库，这没错，但要注意两个坑：

一个坑是维护断档。很多原生库作者更新到一半就不维护了，RN 从 0.59 升到 0.63，配套的定位库还是用的老 API，Android 端在其他机型上闪退，你只能 fork 源码自己改。

另一个坑是定制困难。你需要的不是“读取电量”这么简单，而是“低电量时弹一个自定义样式的提示框”，第三方库给不了这个灵活性，自己写一个 20 行的原生模块搞定，为什么要被别人的 API 限制？

我的建议很务实：底层系统能力优先自己封装原生模块，业务功能优先找现成库。这样既保证硬件层的稳健性和可定制性，又不重复造轮子。

2. 原生模块的桥接原理：消息怎么穿过边界

2.1 桥接层的核心数据结构

在 React Native 里，JS 和原生之间没有共享内存，双方靠一条异步消息通道通信。这条通道上流通的数据，必须是可序列化的，这就是为什么你没法把一个 JavaScript 函数直接传给原生，也没法把一个原生对象原封不动抛给 JS。

桥接消息的基本格式可以理解成一个类似 JSON 的结构：

{ "type": "method_call", "module": "SystemInfoModule", "method": "getBatteryLevel", "args": { "avatarBase64": "..." }, "callbackId": 1024 }

原生端收到这条消息后，根据 module 和 method 找到对应的方法执行，结果再打包成一条类似结构扔回来，JS 端通过 callbackId 识别这是哪一次调用的返回。

这个机制看起来简单，但它决定了几个硬性约束：参数必须是简单的 JSON 支持的类型（字符串、数字、布尔、数组、对象），返回也必须是可序列化的。如果你想把一个 Bitmap 或 C++ 指针传回 JS，对不起，必须先转换成 Base64 字符串或二进制数据。

2.2 同步与异步：别在桥上调 UI

RN 支持同步常量和异步方法两种通信模式：

同步常量（constantsToExport）是在模块初始化时就打入 JS 端的，适合放那种不变或很少变的信息，比如 SDK 版本号、设备初始状态。但注意，同步方法（sync method）在新架构里是非常受限的，它会阻塞 JS 主线程，能不用就不用。

异步方法是主力。我在 Android 端用 Promise 返回结果，在 iOS 端用 resolve/reject 闭包返回。这两者的本质都一样：JS 端调用原生方法后，不用傻等，原生算完了会把结果推回来，JS 端用 then/catch 接住。

为什么要设计成异步？还是那句话，桥是异步消息通道，你不可能让 JS thread 卡在那边等原生处理完。再一个，原生方法里经常要跑耗时逻辑（读文件、扫描蓝牙、网络请求），异步天然适合这些场景。

提示：在原生方法里千万不要直接操作 UI。Android 端如果从模块工作线程更新页面，会直接抛 CalledFromWrongThreadException；iOS 端虽然不崩，但界面会莫名其妙不刷新。正确做法是把 UI 操作切到主线程，Android 用reactContext.runOnUiQueueThread，iOS 用DispatchQueue.main.async。

2.3 线程模型：谁在跑你的原生代码

这个我必须单独拎出来说，十个人写原生模块，八个人在这里栽过跟头。

Android 端，@ReactMethod注解的方法默认执行在 React Native 的 Native Modules 线程池（一个后台线程），不是主线程。所以你在里面做耗时操作没问题，但如果你在里面调了 Toast 或者在方法里用了 SharedPreferences，没问题；如果你碰了 View，或者依赖了主线程才能用的对象，就会出问题。

iOS 端，模块方法默认在自定义串行队列上执行，也不在主线程。和 Android 一个道理，耗时逻辑可以放这里，但 UI 刷新必须丢回主线程。

我常用的分工方式是这样的：

• 原生模块内部自行维护耗时任务，比如网络请求、数据库读写，放后台队列跑；
• 只把结果以及需要展示数据的时机通过回调抛给 JS 层，由 RN 决定如何渲染；
• 如果原生代码要弹原生的 UI（比如 Android Toast、iOS 原生弹窗），必须切主线程。

3. Android 端实战：Kotlin 手写系统信息模块

3.1 环境准备：先把 Android Studio 基础工程跑通

Java/Kotlin 这边，第一步就是把 Android SDK 装好、Android Studio 装好。这里我多说一句那些装到一半发现“SDK 组件选不了、装不了”的情况，通常就是两个原因：一个是 Android Studio 没给当前项目配置好 SDK 路径，另一个是网络问题导致 SDK Manager 拉不下来组件。

Android Studio 新版里，SDK 路径可以在 Settings -> Languages & Frameworks -> Android SDK 里配置。如果发现 SDK Manager 里某些 API Level 的组件灰色不可勾选，先检查你装的是不是 Open JDK 版本过老，或者把项目用的 compileSdkVersion 调低一档试试。

环境就绪后，用 Android Studio 打开 RN 项目根目录下的 android 文件夹，等 Gradle 同步完成，这一步耗时看网速，耐心点多等几分钟。同步完成后，在 app/src/main/java 包路径下新建一个NativeModulesPackage.kt和SystemInfoModule.kt，这就是我们要写的核心文件。

3.2 手写 SystemInfoModule：读电池、网络与设备型号

我先展示一个完整的 Kotlin 原生模块，功能有三个：当前设备型号、电池剩余电量、当前网络类型。别嫌这几个功能简单，它们涵盖了原生模块最典型的使用姿势——返回 String、返回 Double、回调带参数。

package com.example.nativemodules import android.content.Context import android.content.Intent import android.content.IntentFilter import android.net.ConnectivityManager import android.net.NetworkCapabilities import android.os.BatteryManager import android.os.Build import com.facebook.react.bridge.* class SystemInfoModule(reactContext: ReactApplicationContext) : ReactContextBaseJavaModule(reactContext) { private val appContext: Context = reactContext.applicationContext override fun getName(): String = "SystemInfoModule" // 同步导出：模块加载时自动注入 JS 端 override fun getConstants(): Map<String, Any> { return mapOf( "initialModel" to Build.MODEL, "moduleVersion" to "1.0.0" ) } // 电池电量，通过 Promise 异步返回 @ReactMethod fun getBatteryLevel(promise: Promise) { try { val batteryManager = appContext.getSystemService(Context.BATTERY_SERVICE) as BatteryManager val level = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) { batteryManager.getIntProperty(BatteryManager.BATTERY_PROPERTY_CAPACITY) } else { val intent = appContext.registerReceiver( null, IntentFilter(Intent.ACTION_BATTERY_CHANGED) ) val levelRaw = intent?.getIntExtra(BatteryManager.EXTRA_LEVEL, -1) ?: -1 val scale = intent?.getIntExtra(BatteryManager.EXTRA_SCALE, -1) ?: -1 if (levelRaw > 0 && scale > 0) levelRaw * 100 / scale else -1 } if (level >= 0) promise.resolve(level) else promise.reject("NO_BATTERY", "无法获取电量") } catch (e: Exception) { promise.reject("BATTERY_ERROR", e.message, e) } } // 网络类型，返回字符串 @ReactMethod fun getNetworkType(promise: Promise) { try { val cm = appContext.getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager val networkType = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) { cm.getNetworkCapabilities(cm.activeNetwork)?.let { caps -> when { caps.hasTransport(NetworkCapabilities.NET_CAPABILITY_WIFI) -> "wifi" caps.hasTransport(NetworkCapabilities.NET_CAPABILITY_CELLULAR) -> "cellular" else -> "unknown" } } ?: "none" } else { @Suppress("DEPRECATION") when (cm.activeNetworkInfo?.type) { ConnectivityManager.TYPE_WIFI -> "wifi" ConnectivityManager.TYPE_MOBILE -> "cellular" else -> "unknown" } } promise.resolve(networkType) } catch (e: Exception) { promise.reject("NETWORK_ERROR", e.message, e) } } }

几个细节说一下：

getName()返回的字符串，就是 JS 端NativeModules.SystemInfoModule的命名依据，必须和构造函数里的类名对应上。getConstants()对应 React Native 旧版里的constantsToExport，在 Kotlin 代码里我们直接覆写这个函数，它返回的 map 会被打进 JS 端作为模块的静态属性。

getBatteryLevel里我做了 API Level 的判断，Lollipop（21）以上的设备用 BatteryManager 的属性读取，老设备回退到检查ACTION_BATTERY_CHANGED广播。生产环境里总有跑了多年的老机型，兼容性处理必须写，不要只看你自己测试机的表现。

3.3 在应用入口注册 Package

模块类写好了还不够，你得让 RN 运行时知道这个模块存在。新建一个NativeModulesPackage.kt：

package com.example.nativemodules import com.facebook.react.ReactPackage import com.facebook.react.bridge.NativeModule import com.facebook.react.bridge.ReactApplicationContext import com.facebook.react.uimanager.ViewManager class NativeModulesPackage : ReactPackage { override fun createNativeModules(reactContext: ReactApplicationContext): List<NativeModule> { return listOf(SystemInfoModule(reactContext)) } override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> { return emptyList() } }

然后打开 MainApplication.kt，在getPackages()里加上自定义 Package：

override fun getPackages(): List<ReactPackage> { val packages = PackageList(this).packages packages.add(NativeModulesPackage()) return packages }

如果你的项目是 2023 年之后升级到 RN 0.73+ 的新架构，注册 TurboModule 的方式略有不同，但旧架构的写法在bridgeless模式下通常也兼容。稳妥起见，README 里把两种模式怎么切写清楚，方便团队协作时少踩坑。

注意：改完 MainApplication.kt 之后，一定要完全停止 Metro 和 App 进程，重新react-native run-android。原生代码不像 JS 有 Hot Reload，改完必须重新编译，这是新手最常问的“为什么我改了没反应”。

3.4 JS 端验证调用

模块编译通过、App 正常启动后，在 RN 业务代码里就能直接调了：

import { NativeModules } from 'react-native'; const { SystemInfoModule } = NativeModules; async function fetchSystemInfo() { try { console.log('静态常量:', SystemInfoModule.initialModel); const battery = await SystemInfoModule.getBatteryLevel(); const network = await SystemInfoModule.getNetworkType(); console.log(`电量: ${battery}%, 网络: ${network}`); } catch (e) { console.error(e); } }

如果打印出来的结果符合预期，说明你的第一个 Android 原生模块已经跑通了。如果NativeModules.SystemInfoModule是 undefined，九成是 Package 没注册成功，或者 Metro 缓存太旧，执行npx react-native start --reset-cache再看。

我习惯在首次联调时故意在原生方法里抛一个异常，验证 reject 分支是否生效，别只看成功路径。

4. iOS 端实战：Swift 复刻同一个模块

4.1 iOS 原生模块的入口与导出

iOS 这边和 Android 最大的区别在于：没有“自动注册”机制。你写好一个 NSObject 子类，需要在编译时用宏让 RN 能认出它来。Swift 项目里通常还要借助一个-Bridging-Header.h桥接头文件，引入 React 的头文件。

如果你用的是 Xcode 直接管理项目，打开AppDelegate.mm，React Native 0.7x 已经把模块注册的入口整合好了。你只需要新建一个 Swift 文件，继承NSObject，让它暴露给 Objective-C 运行时即可。

iOS 上还有个现实问题：新装的 Xcode 工程第一次跑真机，总有人卡在“开发者模式没开启”上。iOS 16 之后真机调试必须先在系统设置里打开开发者模式，路径是 设置 -> 隐私与安全性 -> 底部开发者模式，开启后手机会重启一次。这个不加说明，第一次跑 RN 的 iOS 工程十有八九要懵半天。

4.2 Swift 实现系统信息模块

下面用 Swift 写一个功能和 Android 端完全对齐的模块：

import Foundation import React import UIKit @objc(SystemInfoModule) class SystemInfoModule: NSObject { // 同步导出常量，在 module 初始化时注入 JS 端 override static func requiresMainQueueSetup() -> Bool { return false } @objc func constantsToExport() -> [AnyHashable: Any] { return [ "initialModel": UIDevice.current.model, "moduleVersion": "1.0.0" ] } // 电池电量，异步 Promise 返回 @objc func getBatteryLevel(_ resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) { UIDevice.current.isBatteryMonitoringEnabled = true let level = UIDevice.current.batteryLevel if level >= 0 { resolve(Int(level * 100)) } else { reject("NO_BATTERY", "模拟器或当前设备无法读取电量", nil) } } // 网络类型，简单通过 status bar / Network framework 获取 @objc func getNetworkType(_ resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) { // 生产环境这里建议用 NWPathMonitor，Demo 从简 resolve("unknown") } }

Swift 写法里有几个容易踩的细节：

@objc注解必须加，RN 的桥接层是 Objective-C 运行时的世界，没有这个注解，方法就进不了 runtime 派发表。RCTPromiseResolveBlock和RCTPromiseRejectBlock要用@escaping标注，因为 Promise 的回调往往在异步操作结束后才会触发，闭包的生命周期比函数调用栈更长。

requiresMainQueueSetup返回 false 的意思是这个模块不需要在主线程上初始化。如果你的模块在 init 里就要访问 UIAppearance、注册通知中心这些依赖主线程的东西，就必须返回 true，但要注意这会增加启动开销，能 false 就 false。

注意：从 iOS 14 开始，读取 WiFi SSID 等敏感信息需要额外权限，如果只是要用网络类型做业务判断，建议用前面 Android 的做法返回 wifi/cellular/unknown 三个值，不要试图去拿具体 SSID，省掉 Info.plist 里一堆烦人的权限描述。

iOS 端的导出如果发现 JS 里NativeModules.SystemInfoModule是 undefined，先检查：

• Swift 文件有没有被添加进 Xcode target；
• 桥接头文件是否引用了 React；
• 类名前的@objc名是否与 JS 调用名完全一致。

4.3 iOS 权限与配置：Info.plist 和 ATS

iOS 原生模块如果涉及网络请求、相册、相机、蓝牙，都要在 Info.plist 里声明用途描述，否则一调用就闪退，而闪退日志只给你一句“This app has crashed because it attempted to access privacy-sensitive data without a usage description”，很折磨人。

一个比较隐蔽的问题是ATS（App Transport Security）。如果后台接口是 HTTP 非 HTTPS，在开发和公司内网环境里经常被 ATS 拦死。这时候不是让你把 ATS 全关（App Store 审查会有风险），而是在 Info.plist 里按需添加例外：

<key>NSAppTransportSecurity</key> <dict> <key>NSAllowsArbitraryLoads</key> <false/> <key>NSExceptionDomains</key> <dict> <key>your-internal-domain.com</key> <dict> <key>NSExceptionAllowsInsecureHTTPLoads</key> <true/> </dict> </dict> </dict>

这种按域名的例外毕业设计或内部工具完全够用，同时保住了 App Store 审核的基本体面。

跑 iOS 模块的另一个前置条件是真机调试。模拟器上 UIDevice.batteryLevel 常年返回 -1，我的演示代码里已经做了容错处理，如果你在自己的模块里读取了传感器、相机等模拟器没有的硬件，一定要在 JS 层加判断提示，避免用户拿模拟器玩半天以为产品出 bug 了。

5. 双端调试与问题排查实录

5.1 Android 端常见崩溃与解决

第一类：Method not found。这类报错通常是@ReactMethod注解漏写或方法名拼错。注意@ReactMethod修饰的方法必须是 public，返回值必须是 void（结果通过 Promise 或 Callback 回传），如果你写了suspend或者返回一个非空值，会在编译期或运行期直接报错。

第二类：This method is not supported。多见于调用了模板中不存在的 API，比如在 getName 之外的普通方法里去拿 Activity。记住，ReactContextBaseJavaModule 持有的是 ReactApplicationContext，它没有 Activity 引用，如果需要 Activity 相关操作，要继承ActivityEventListener或者走CurrentActivity获取，但后者可能为 null，必须判空。

第三类：Gradle 构建内存不足。这个非常常见，特别是项目里同时跑多个 module 时。我在android/gradle.properties里加过这些参数，实测能明显减少构建崩溃：

org.gradle.jvmargs=-Xmx2048m -XX:MaxMetaspaceSize=512m android.useAndroidX=true android.enableJetifier=true

5.2 iOS 端常见异常与调试

iOS 这边比较容易翻车的是link 问题。如果你用 CocoaPods 管理依赖，新增一个 Swift 原生模块后，需要在 ios 目录执行pod install，否则 Xcode 根本不知道你的新文件参与编译。很多新手改了原生代码发现没生效，都是因为忘了重新 pod install。

第二个坑是RCTBridgeModule 名字冲突。如果你或者同事之前已经定义过同名的模块，注册时会产生 warning，运行时行为也不可预期。建议在模块名上加上项目前缀，比如ZZSystemInfoModule，团队协作时极大降低冲突概率。

第三个坑是内存泄漏。Swift 闭包捕获 self 时，如果 self 是模块实例，而模块又被 JS 引用着，循环引用就很隐蔽。我在 iOS 侧的做法是所有耗时回调都用 weak self：

DispatchQueue.global().async { [weak self] in guard let self = self else { return } // ... }

5.3 调试工具推荐

调试原生模块，我一般用三种工具打配合：

• Charles：抓包看 JS -> 原生 -> 后端的完整链路，尤其在排查原生模块网络请求是否带上了正确 header 时非常好用。iPhone 上装好证书后，在 Wi-Fi 设置里配置 HTTP 代理，就可以看到所有走系统的网络请求。
• Android Studio / Xcode 自带调试器：直接打断点、看日志。原生模块的问题，你不进原生 IDE 永远只能靠猜。Android 端用 Logcat 过滤 ReactNativeJS 和 System.out 两个 Tag，iOS 端用 Xcode 的控制台直接搜模块名。
• Flutter/RN 的 dev menu：可以查 JS 层 console 日志和原生层日志，适合快速确认是 JS 的问题还是原生的问题。

有一次我花了一个下午排查 Android 端某个模块在部分机器上返回值总是少一截，最后是在 Android Studio 的 Profiler 里看到是主线程被某个耗时任务阻塞了，异步回调被延迟，跟模块逻辑本身毫无关系。所以遇到古怪的“偶发 bug”，先怀疑线程问题，再怀疑代码逻辑，这个经验帮我省了无数时间。

最后说点我不太会出现在文档里的体会

我写原生模块三年，最大的感受是：难点从来不是语法，而是思维方式的切换。JS 开发者习惯了一切都是异步、一切都有垃圾回收、一切异常都能 try/catch；而原生世界里，你需要自己管理线程、自己关注内存、自己处理系统权限。第一次写你会觉得很麻烦，但当你真正理解桥接层怎么工作之后，你会在设计模块 API 时潜意识里就开始考虑数据类型、线程安全、错误传递，这种思维方式反过来会让你在纯 JS 层的架构设计上也受益。

另外一个非常实用的建议：别把原生模块做成一个函数堆积的 God 类。按业务域拆分成独立的模块类（SystemInfoModule、BleModule、PaymentModule），每个类只负责一个领域，注册 Package 时按需加载。这样你后续要升级 SDK、修问题、加权限，只需要动一个模块文件，不会扯出一堆连带问题。

跨平台开发的边界不会消失，但会不断移动。今天你学会了打破 Android/iOS 原生模块这堵墙，明天你面对的不再是“能不能做”，而是“怎么做更优雅”。以后有机会我再写写原生 UI 组件（Native UI Components）的实现——那又是另一种风格的边界突破。