如何将React Native组件打包为XCFramework供iOS分发

1. 核心逻辑梳理 #

RN UI组件一般包含JS/TS实现的UI逻辑，以及可能存在的iOS原生适配代码（比如自定义原生视图、桥接逻辑）。要打包成XCFramework，本质是把原生桥接层、React Native核心原生依赖、预打包的JS离线包封装在一起，让iOS原生项目无需配置RN环境就能直接集成调用。

2. 分步实操 #

第一步：整理组件的原生依赖 #

• 若组件是纯JS/TS实现，仍需依赖React Native核心原生库（如React、React-Core、React-RCTView等），这些库要纳入XCFramework的打包范围。
• 若包含自定义原生模块/视图，整理对应的.h、.m/.swift文件，确保桥接代码正确（比如RCT_EXPORT_MODULE、RCT_EXPORT_METHOD等宏的规范使用）。

第二步：预打包JS离线Bundle #

将RN组件的JS代码打包成离线bundle，避免远程加载：

npx react-native bundle --entry-file index.js --platform ios --dev false --bundle-output ./ios/YourComponent.bundle --assets-dest ./ios/assets

把生成的YourComponent.bundle和assets资源目录，放到后续iOS Framework项目的资源列表中。

第三步：创建iOS Framework项目 #

• 在Xcode中新建Cocoa Touch Framework项目，命名例如RNYourUIComponents。
• 导入整理好的原生代码、RN核心原生库的.a文件或XCFramework包。
• 将预打包的JS bundle和资源文件添加到项目的Copy Bundle Resources构建阶段。

第四步：配置Framework构建参数 #

• 在Build Settings中设置Mach-O Type为Static Library或Dynamic Library（动态分发推荐后者，但需注意RN依赖兼容性）。
• 配置Framework Search Paths和Header Search Paths，包含RN核心库的路径（比如../node_modules/react-native/React、../node_modules/react-native/React/Base等）。
• 开启Build Libraries for Distribution选项，确保生成的Framework符合XCFramework规范。

第五步：构建多架构XCFramework #

分别为真机和模拟器构建Framework，再合并为XCFramework：

# 构建真机版本
xcodebuild -scheme RNYourUIComponents -configuration Release -sdk iphoneos BUILD_DIR=../build
# 构建模拟器版本
xcodebuild -scheme RNYourUIComponents -configuration Release -sdk iphonesimulator BUILD_DIR=../build
# 合并为XCFramework
xcodebuild -create-xcframework \
    -framework ./build/Release-iphoneos/RNYourUIComponents.framework \
    -framework ./build/Release-iphonesimulator/RNYourUIComponents.framework \
    -output ./RNYourUIComponents.xcframework

第六步：添加集成初始化逻辑 #

在Framework中编写初始化方法，让iOS项目可以快速加载RN环境并获取组件视图：

// RNYourUIComponents.h
#import <Foundation/Foundation.h>
#import <UIKit/UIKit.h>

@interface RNYourUIComponents : NSObject
+ (void)initializeWithBundlePath:(NSString *)bundlePath;
+ (UIView *)yourTargetComponentViewWithProps:(NSDictionary *)props;
@end

// RNYourUIComponents.m
#import "RNYourUIComponents.h"
#import <React/RCTRootView.h>
#import <React/RCTBridge.h>

static RCTBridge *_rnBridge;

@implementation RNYourUIComponents

+ (void)initializeWithBundlePath:(NSString *)bundlePath {
    NSURL *bundleURL = [NSURL fileURLWithPath:bundlePath];
    _rnBridge = [[RCTBridge alloc] initWithBundleURL:bundleURL moduleProvider:nil launchOptions:nil];
    [_rnBridge start];
}

+ (UIView *)yourTargetComponentViewWithProps:(NSDictionary *)props {
    RCTRootView *componentView = [[RCTRootView alloc] initWithBridge:_rnBridge moduleName:@"YourTargetComponent" initialProperties:props];
    return componentView;
}

@end

iOS项目集成后，只需调用初始化方法，就能通过yourTargetComponentViewWithProps:获取RN组件的原生视图。

3. 关键注意事项 #

• 版本兼容性：确保XCFramework中打包的RN核心库版本，与集成方可能存在的RN依赖版本一致，避免冲突。
• 资源完整性：若RN组件用到图片、字体等资源，要确保这些资源被正确包含到XCFramework的bundle中，或提供单独的资源包供集成方导入。
• 调试流程：开发阶段先构建普通Framework测试功能，确认正常后再打包成XCFramework。

内容的提问来源于stack exchange，提问作者mokagio