登录
从零实现 React Native（2）: 跨平台支持
平台支持的取舍
在上一篇《从零实现 React Native（1）: 桥通信的原理与实现》中，基于 macos 平台实现了 JS 与 Native 的双向桥通信，在本篇中将对其他平台进行支持，实现「write once，run anywhere」这个理念。
接下来便来进行 iOS 和 Android 平台的支持工作。
iOS 进展顺利
在支持了 macos 端后，支持 iOS 是很容易的，可以马上着手来搞这个事情。得益于 Apple 生态带来的：macOS 和 iOS 都内置了 JavaScriptCore.framework，这意味着无需额外的引擎移植工作；且编程 API 很相似，这意味着差异化实现较少，大多可复用或类比实现。
事实上，我只花了半天时间就完成了 iOS 端的支持工作，其中主要的时间花在了构建配置的修改、测试示例的新增和调整，少部分时间花在了差异化的 DeviceInfo 模块实现。
得益于 Apple 生态，iOS 的支持工作中大部分代码都是复用的，复用率 90%。因为 macos 和 iOS 的 JSC API 一致，以及 C++ 语言的优势，可以用于跨端复用。复用的内容包含：
- JSCExector
- Bridge 通信逻辑
- 模块注册逻辑
Android 滑铁卢
在顺利支持了 iOS 后，预想是 Android 的支持也不会太难，但实际做起来发现没这么简单。
记得是周末的午后的轻松下午，我先把 Android 的相关环境搭建好（包括 Android Studio、Java SDK 及其环境变量、NDK 等），然后进入 JSC 的移植工作。Why JSC 移植？因为不同于 Apple 生态，Android 系统是没有内置 JSC 引擎的。而正是这一步让我陷入泥潭。
我首先尝试了三方编译的版本，但是要么遇到了 libjsc.so（JSC 编译后的二进制文件，可供 Android 平台运行，可类比理解为前端的 wasm） 不支持 arm64（由于是 MBP 机器，安卓模拟器必须用 arm64 而非 x86 架构的），要么是遇到了 libjsc.so 和 NDK 版本不兼容。然后尝试了从社区提供的 jsc-android-buildscripts 自行编译，也遇到了各种问题编译失败，考虑到每次编译时间：2-3 小时，这也是一个艰难的旅程。
就算解决了 JavaScriptCore，还有 JNI 在等着我。Java 和 C++ 之间的桥梁不是简单的函数调用。我要处理诸如：类型转换、线程同步等问题。前方有很多新的坑在等着我。
舍与得
Maybe it's not the right time. 先理解核心，再扩展边界。先放下 Android 的支持，或许未来的某一天再回头来看这件事。
这个决定让我想起了 MVP（最小可行产品）的原则：先让核心功能跑通，再逐步完善。在学习项目中，这个原则同样适用——先掌握本质，再扩展边界。
既然决定专注于 iOS 和 macOS 双平台，那么接下来就需要一套优雅的构建系统来支撑跨平台开发。一个好的构建系统不仅能让开发者轻松切换平台，更重要的是，它能为后续的代码复用奠定基础。
构建系统的演进
在上一篇博客中，受制于篇幅的限制，跳过了对构建系统的讲解。而在跨平台支持中，天然需要迭代构建系统，也正是对其展开讲讲的一个好时机。
Make 是什么
Make 是一个诞生于 1976 年的构建工具，它的工作原理很简单：描述文件之间的依赖关系，然后只重新编译"变化过的"文件。
Make 适合于 需要多步骤构建流程 的项目，本项目的构建流程较为复杂：JS 产物打包 -> CMake 配置 -> C++ 产物编译 -> 运行 test 代码，很适合引入 Make 进行任务流程的编排。
Make 工具的配套 Makefile 文件是一个文本配置文件，它定义了构建规则、依赖关系和执行命令，可以将其理解为 npm 和 package.json 的关系。
以下是基于 macos 编译和测试的 Makefile 文件摘要代码，核心步骤包含了 js-build, configure, test。
# ============================================
# 变量定义 (Makefile 第 10-13 行)
# ============================================
BUILD_DIR = build
CMAKE_BUILD_TYPE ?= Debug
CORES = $(shell sysctl -n hw.ncpu) # 动态检测 CPU 核心数
# ============================================
# 主要构建目标 - 依赖链设计
# ============================================
# 默认目标：make 等价于 make build
.PHONY: all
all: build
# 核心构建流程：js-build → configure → 实际编译
.PHONY: build
build: js-build configure
@echo "🔨 Building Mini React Native..."
@cd $(BUILD_DIR) && make -j$(CORES)
@echo "✅ Build complete"
# ============================================
# 步骤 1：JavaScript 构建 (第 29-33 行)
# ============================================
.PHONY: js-build
js-build:
@echo "📦 Building JavaScript bundle..."
@npm run build # 执行 rollup -c，生成 dist/bundle.js
@echo "✅ JavaScript bundle built"
# ============================================
# 步骤 2：CMake 配置 (第 22-26 行)
# ============================================
.PHONY: configure
configure:
@echo "🔧 Configuring build system..."
@mkdir -p $(BUILD_DIR)
@cd $(BUILD_DIR) && cmake -DCMAKE_BUILD_TYPE=$(CMAKE_BUILD_TYPE) -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ..
@echo "✅ Configuration complete"
# ============================================
# 步骤 4：分层测试流程 (第 91-130 行)
# ============================================
# 完整测试：build → 4 个测试依次执行
.PHONY: test
test: build
@echo "🧪 Running all tests..."
@echo "\n📝 Test 1: Basic functionality test"
@./$(BUILD_DIR)/mini_rn_test
@echo "\n📝 Test 2: Module framework test"
@./$(BUILD_DIR)/test_module_framework
@echo "\n📝 Test 3: Integration test"
@./$(BUILD_DIR)/test_integration
@echo "\n📝 Test 4: Performance test"
@./$(BUILD_DIR)/test_performance
@echo "\n✅ All tests complete"
# 单独的测试目标 - 允许细粒度测试
.PHONY: test-basic
test-basic: build
@echo "🧪 Running basic functionality test..."
@./$(BUILD_DIR)/mini_rn_test
.PHONY: test-performance
test-performance: build
@echo "🧪 Running performance test..."
@./$(BUILD_DIR)/test_performance
在引入了 make 后，可以很方便的进行复杂流程的编排，例如我们想要运行测试代码时，实际的发生的事情如下所示。
用户命令: make test
↓
test: build
↓
build: js-build configure
↓ ↓
js-build configure
↓ ↓
npm run build cmake ..
↓ ↓
dist/bundle.js build/Makefile
↓
make -j8 (CMake 管理的依赖)
↓
libmini_react_native.a
↓
mini_rn_test (等 4 个可执行文件)
Before 引入 Make：想象一下，如果没有 Make，每次修改代码后你需要手动执行
# 步骤1：构建 JavaScript
npm run build
# 步骤2：配置 CMake
mkdir -p build
cd build && cmake ..
# 步骤3：编译 C++
cd build && make -j8
# 步骤4：运行测试
./build/mini_rn_test
./build/test_module_framework
./build/test_integration
./build/test_performance
每次都要记住这么多命令，还要确保执行顺序正确。更糟糕的是，如果某个步骤失败了，你需要手动判断从哪里重新开始。
After 引入 Make：make test 一条命令搞定所有事情
CMake 是什么
在把 C++ 代码编译成二进制文件这一步之前，其实构建系统提前引入了 CMake 进行管理。CMake 不是“构建工具”，而是“构建系统的构建系统”，在这个场景中 CMake 实际上生成了编译代码的工具 Makefile 文件。CMake 会读取 CMakeLists.txt，然后生成原生的构建文件。
Why CMake？因为 mini-rn 项目开始之初就是要考虑多平台支持的，为了实现这个 feature，便会遇到 多平台构建的复杂性 这个问题。
问题 1：平台特定源文件管理
不同平台需要不同的实现：
- macOS：使用
IOKit获取硬件信息 - iOS：使用
UIDevice获取设备信息
没有 CMake 需要维护两套构建脚本，引入 CMake 后可通过条件编译一套配置搞定。
问题 2：系统框架动态链接
不同平台需要链接不同框架：macOS 需要 IOKit，iOS 需要 UIKit。
引入 CMake 后可自动检测并链接正确的框架。
解决效果
引入 CMake 前：需要维护多套构建脚本，手动管理复杂配置，容易出错。
引入 CMake 后：一套 CMakeLists.txt 支持所有平台，自动处理平台差异，大幅降低维护成本。
CMake 关键语法解释：
-
CMAKE_SYSTEM_NAME：CMake 内置变量，表示目标系统名称（iOS、Darwin等） -
find_library()：在系统中查找指定的库文件 -
target_link_libraries()：将库文件链接到目标可执行文件 -
set()：设置变量的值 -
if(MATCHES)：条件判断，支持正则表达式匹配
改动一：Makefile 新增 iOS 构建目标
在 macOS 的可扩展构建系统配置就绪后，接下来看看如何改动以支持 iOS。
改动一实现了什么？
核心目标：在现有 Makefile 基础上，新增 iOS 平台的完整构建流程，实现"一套 Makefile，双平台支持"。
具体实现：
-
新增 4 个 iOS 专用目标：
ios-configure、ios-build、ios-test、ios-test-deviceinfo - 建立 iOS 构建流程：js-build → ios-configure → ios-build → ios-test
-
实现平台隔离：iOS 使用独立的
build_ios/目录，与 macOS 的build/目录完全分离 - 自动化 Xcode 环境配置：自动检测 SDK 路径、设置开发者目录、配置模拟器架构
新增的 4 个 iOS 目标
原本基于 macOS 的构建路径是：js-build → configure → build → test，现在为 iOS 新增了对应的平行路径：js-build → ios-configure → ios-build → ios-test。
# iOS 构建配置（模拟器）
.PHONY: ios-configure
ios-configure:
@mkdir -p $(BUILD_DIR)_ios
@cd $(BUILD_DIR)_ios && DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer cmake \
-DCMAKE_SYSTEM_NAME=iOS \
-DCMAKE_OSX_ARCHITECTURES=$$(uname -m) \
-DCMAKE_OSX_SYSROOT=$$(DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer xcrun --sdk iphonesimulator --show-sdk-path) \
-DCMAKE_BUILD_TYPE=$(CMAKE_BUILD_TYPE) \
-DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
..
# 构建 iOS 版本（模拟器）
.PHONY: ios-build
ios-build: js-build ios-configure
@cd $(BUILD_DIR)_ios && make -j$(CORES)
# iOS 测试目标
.PHONY: ios-test
ios-test: ios-build
@./test_ios.sh all
# iOS DeviceInfo 测试
.PHONY: ios-test-deviceinfo
ios-test-deviceinfo: ios-build
@./test_ios.sh deviceinfo
关键设计决策
1. 独立构建目录
macOS 用 build/，iOS 用 build_ios/，互不干扰：
@mkdir -p $(BUILD_DIR)_ios # iOS 构建目录
2. 仅支持 iOS 模拟器
为什么不支持真机？因为：
- 真机需要开发者证书和配置文件
- 模拟器足够验证 Bridge 通信机制
- 降低环境配置复杂度
-DCMAKE_OSX_SYSROOT=$$(xcrun --sdk iphonesimulator --show-sdk-path)
3. 语义化命令
make ios-configure 比写一长串 CMake 命令简洁太多。这就是 Makefile 作为用户接口的价值。
改动二：CMake 平台条件编译
改动二实现了什么？
核心目标：让 CMake 能够智能识别目标平台，并自动选择正确的源文件和系统框架，实现"一套 CMakeLists.txt，智能适配双平台"。
具体实现：
-
平台检测机制：通过
CMAKE_SYSTEM_NAME变量自动识别是 macOS 还是 iOS -
源文件智能选择：根据平台自动选择对应的
.mm实现文件 - 框架动态链接：iOS 链接 UIKit，macOS 链接 IOKit，共享 JavaScriptCore 和 Foundation
- 编译标志自动设置：为 Objective-C++ 文件自动设置 ARC 标志
- 部署目标配置：iOS 设为 12.0+，macOS 设为 10.15+
设计精髓：编译时确定，运行时无开销。最终的 iOS 二进制文件中完全没有 macOS 代码，反之亦然。
原来的代码（仅 macOS）
# 原始版本 - 仅支持 macOS
if(APPLE)
set(PLATFORM_SOURCES
src/macos/modules/deviceinfo/DeviceInfoModule.mm
)
find_library(IOKIT_FRAMEWORK IOKit)
endif()
target_link_libraries(mini_react_native
${JAVASCRIPTCORE_FRAMEWORK}
${IOKIT_FRAMEWORK}
)
演进后的代码（macOS + iOS）
# 演进版本 - 支持 macOS + iOS
if(APPLE)
# 根据具体平台选择源文件
if(${CMAKE_SYSTEM_NAME} MATCHES "iOS")
set(PLATFORM_SOURCES
src/ios/modules/deviceinfo/DeviceInfoModule.mm
)
else()
# macOS
set(PLATFORM_SOURCES
src/macos/modules/deviceinfo/DeviceInfoModule.mm
)
endif()
# 平台特定框架
if(${CMAKE_SYSTEM_NAME} MATCHES "iOS")
find_library(UIKIT_FRAMEWORK UIKit)
set(PLATFORM_FRAMEWORKS ${UIKIT_FRAMEWORK})
else()
find_library(IOKIT_FRAMEWORK IOKit)
set(PLATFORM_FRAMEWORKS ${IOKIT_FRAMEWORK})
endif()
# 统一链接
target_link_libraries(mini_react_native
${JAVASCRIPTCORE_FRAMEWORK}
${FOUNDATION_FRAMEWORK}
${PLATFORM_FRAMEWORKS}
)
endif()
三个关键变化
1. 源文件分离
src/
├── macos/modules/deviceinfo/DeviceInfoModule.mm
└── ios/modules/deviceinfo/DeviceInfoModule.mm
两个文件虽然文件名相同，但实现不同：
- macOS 版本：用 IOKit 获取硬件信息
- iOS 版本：用 UIDevice 获取设备信息
2. 框架动态链接
| 平台 | 共享框架 | 平台特定框架 |
|---|---|---|
| macOS | JavaScriptCore, Foundation | IOKit |
| iOS | JavaScriptCore, Foundation | UIKit |
3. 部署目标设置
if(${CMAKE_SYSTEM_NAME} MATCHES "iOS")
set(CMAKE_OSX_DEPLOYMENT_TARGET "12.0")
elseif(${CMAKE_SYSTEM_NAME} MATCHES "Darwin")
set(CMAKE_OSX_DEPLOYMENT_TARGET "10.15")
endif()
两个改动的协同作用
改动一 + 改动二 = 完美的跨平台构建系统
这两个改动巧妙地分工合作：
- Makefile（改动一）：作为用户接口层，提供简单统一的命令，隐藏平台配置的复杂性
- CMake（改动二）：作为构建逻辑层，智能处理平台差异，自动选择正确的源文件和框架
协同效果：
-
开发者体验：
make buildvsmake ios-build，命令接口一致 - 构建隔离：两个平台使用独立目录，可以并行构建，切换无需清理
- 智能适配：CMake 根据 Makefile 传入的平台信息，自动配置所有细节
- 零运行时开销：编译时就确定了平台，最终二进制文件纯净无冗余
这种设计让跨平台支持变得既强大又优雅：开发者只需要记住两个命令，背后的所有复杂性都被自动化处理了。
DeviceInfo - 变与不变
在构建系统演进完成后，我们来深入分析 DeviceInfo 模块的双平台实现。这个模块展示了跨平台架构设计的智慧：如何在保持接口统一的同时，让每个平台发挥自身优势。
90% 复用率是怎么做到的？
关键洞察：大部分逻辑其实是平台无关的
仔细分析 DeviceInfo 模块，你会发现一个惊人的事实：
// 这些逻辑在任何平台都一样
std::string DeviceInfoModule::getName() const {
return "DeviceInfo";
}
std::vector<std::string> DeviceInfoModule::getMethods() const {
return {
"getUniqueId", // methodId = 0
"getSystemVersion", // methodId = 1
"getDeviceId" // methodId = 2
};
}
void DeviceInfoModule::invoke(const std::string& methodName,
const std::string& args, int callId) {
try {
if (methodName == "getUniqueId") {
std::string uniqueId = getUniqueIdImpl(); // 只是调用，不关心具体实现
sendSuccessCallback(callId, uniqueId);
} else {
sendErrorCallback(callId, "Unknown method: " + methodName);
}
} catch (const std::exception& e) {
sendErrorCallback(callId, "Method invocation failed: " + std::string(e.what()));
}
}
**Bridge 通信协议、方法注册机制、消息分发逻辑，完全都是可以复用的！**真正不同的，只是那几个 xxxImpl() 方法的底层实现。
复用的边界
但这里有个更深层的问题：为什么有些代码能 100% 复用，有些却完全不能？
让我们看看实际的复用率统计：
| 代码类型 | 复用率 | 为什么？ |
|---|---|---|
| Bridge 通信逻辑 | 100% | 协议标准化 |
| 模块注册机制 | 100% | 框架层抽象 |
| 错误处理机制 | 100% | 异常处理逻辑相同 |
| 设备唯一标识 | 0% | 平台理念完全不同 |
| 系统版本获取 | 95% | 只有注释不同 |
| 设备型号获取 | 85% | 都用 sysctlbyname，iOS多了模拟器判断 |
100% 复用：协议的力量
为什么 Bridge 通信能 100% 复用？
因为这是协议层，不管底层平台怎么变，JavaScript 和 Native 之间的通信协议是固定的。方法名、参数、回调 ID、错误处理这些都是标准化的。就像 HTTP 协议，不管服务器是 Linux 还是 Windows，浏览器都用同样的方式发请求。
0% 复用：平台的鸿沟
为什么设备唯一标识完全不能复用？
macOS 追求真正的硬件级别唯一性，有复杂的降级机制；iOS 在 MVP 阶段采用了简化策略，每次启动生成新ID。这不是技术问题，而是：
- 平台哲学的差异：桌面 vs 移动的隐私理念
- 开发策略的差异：完整实现 vs MVP验证
复用边界的哲学
通过 DeviceInfo 模块，我们发现了跨平台复用的三个层次：
- 协议层：100% 复用，因为标准统一
- API 层：看运气，苹果生态有优势
- 实现层：看平台差异，移动端更复杂
这揭示了一个残酷的真相：跨平台的成本永远存在，只是被转移了。
可以用抽象基类隐藏差异，但差异本身不会消失。关键是找到合适的边界，让复用最大化，让差异最小化。
头文件的魔法
解决方案其实就是基于 面向对象 的：
// common/modules/DeviceInfoModule.h
class DeviceInfoModule : public NativeModule {
public:
DeviceInfoModule();
~DeviceInfoModule() override = default;
// NativeModule 接口实现 - 所有平台共享
std::string getName() const override;
std::vector<std::string> getMethods() const override;
void invoke(const std::string& methodName, const std::string& args,
int callId) override;
// 平台特定的实现接口 - 让各平台去填这些"洞"
std::string getUniqueIdImpl() const;
std::string getSystemVersionImpl() const;
std::string getDeviceIdImpl() const;
private:
// 工具方法
std::string createSuccessResponse(const std::string& data) const;
std::string createErrorResponse(const std::string& error) const;
};
注意这里没有用虚函数，因为已经引入了 CMake 在编译时确定了对应平台的文件，不需要运行时多态，结果是 同一个头文件，不同的实现文件。每个平台都有自己的 .mm 文件来实现这些方法，编译时自动选择对应的实现。
基类定义了 what（做什么），各平台实现 how （怎么做）。Bridge 通信、方法注册、消息分发等这些复杂的逻辑只写一遍，所有平台自动继承。
分平台实现
// macOS 实现 - src/macos/modules/deviceinfo/DeviceInfoModule.mm
std::string DeviceInfoModule::getUniqueIdImpl() const {
@autoreleasepool {
// 尝试获取硬件 UUID
io_registry_entry_t ioRegistryRoot =
IORegistryEntryFromPath(kIOMasterPortDefault, "IOService:/");
CFStringRef uuidCf = (CFStringRef)IORegistryEntryCreateCFProperty(
ioRegistryRoot, CFSTR(kIOPlatformUUIDKey), kCFAllocatorDefault, 0);
if (uuidCf) {
NSString* uuid = (__bridge NSString*)uuidCf;
std::string result = [uuid UTF8String];
CFRelease(uuidCf);
return result;
}
// 多层降级机制...
return "macOS-" + getDeviceIdImpl() + "-" + getSystemVersionImpl();
}
}
// iOS 实现 - src/ios/modules/deviceinfo/DeviceInfoModule.mm
std::string DeviceInfoModule::getUniqueIdImpl() const {
@autoreleasepool {
// iOS 简化实现：使用 NSUUID 生成唯一标识
// 注意：这个实现每次启动都会生成新的ID，适用于MVP测试
NSUUID* uuid = [NSUUID UUID];
NSString* uuidString = [uuid UUIDString];
return [uuidString UTF8String];
}
}
Objective-C++ 关键字解释：
-
@autoreleasepool：自动释放池，管理 Objective-C 对象的内存，确保及时释放 -
__bridge：ARC（自动引用计数）中的桥接转换，在 C/C++ 指针和 Objective-C 对象间转换 -
[object method]：Objective-C 的方法调用语法 -
.mm文件扩展名：表示 Objective-C++ 文件，可以混合使用 C++、C 和 Objective-C 代码
两个平台的实现文件自动拥有了完整的 Bridge 通信能力，现在只需要实现平台差异部分即可~
应自动化尽自动化
DeviceInfo 模块的自动化实现揭示了一个重要原则：
好的跨平台架构不是让代码在所有平台都能跑，而是让正确的代码在正确的平台上跑。
通过这个项目的三层自动化体系：
- Makefile 自动化：统一的命令接口，隐藏平台配置复杂性
- CMake 自动化：智能的源文件选择和框架链接
- 编译器自动化：平台特定的二进制生成
这样的架构让开发者专注于业务逻辑，而把平台适配的复杂性交给了工具链。
真正的自动化不是写一份代码到处跑，而是：
-
开发体验统一：
make buildvsmake ios-build，命令接口一致 - 实现策略分离：每个平台有最适合的实现方式
- 构建过程透明：开发者不需要关心 Xcode SDK 路径、编译标志等细节
这种设计在面对更复杂的系统时依然有效：只要保持接口统一、实现分离、构建自动化，就能优雅地扩展到视图渲染、事件处理等更复杂的场景。
彩蛋
项目地址: github.com/zerosrat/mi…
当前项目中包含了本篇文章中的全部内容:
- ✅ iOS 构建系统适配
- ✅ iOS 跨平台的差异化实现（DeviceInfo）
完成本阶段后，项目已经具备了进入第三阶段的基础：视图渲染系统。
📝 本文首发于个人博客: zerosrat.dev/n/2025/mini…
