iOS自定义Framework真机崩溃，模拟器正常（React Native集成，M1 Mac）

场景 #

在M1 Mac上开发iOS原生自定义Framework，将其作为React Native原生模块集成到RN项目中。模拟器（Rosetta模式、Apple Silicon模式）运行正常，但真机加载时崩溃。

Framework构建设置 #

• Architecture：arm64、x86_64
• Build active architecture：No
• Installation Directory：@executable_path/../Frameworks

Framework的lipo信息 #

Architectures in the fat file: /Users/userName/Documents/AbcSourceCode/CustomFramework/CustomFramework.framework/CustomFramework are: x86_64 arm64

构建通用Framework的运行脚本 #

#!/bin/sh
UNIVERSAL_OUTPUTFOLDER=${BUILD_DIR}/${CONFIGURATION}-universal
# 确保输出目录存在
mkdir -p "${UNIVERSAL_OUTPUTFOLDER}"
# 构建真机版本
xcodebuild -target "${PROJECT_NAME}" ONLY_ACTIVE_ARCH=NO -configuration ${CONFIGURATION} -sdk iphoneos BUILD_DIR="${BUILD_DIR}" BUILD_ROOT="${BUILD_ROOT}" clean build
# 复制真机framework到通用目录
cp -R "${BUILD_DIR}/${CONFIGURATION}-iphoneos/${PROJECT_NAME}.framework" "${UNIVERSAL_OUTPUTFOLDER}/"
# 构建模拟器版本
xcodebuild -target "${PROJECT_NAME}" -configuration ${CONFIGURATION} -sdk iphonesimulator ONLY_ACTIVE_ARCH=NO BUILD_DIR="${BUILD_DIR}" BUILD_ROOT="${BUILD_ROOT}" clean build
# 复制模拟器framework到通用目录
cp -R "${BUILD_DIR}/${CONFIGURATION}-iphonesimulator/${PROJECT_NAME}.framework" "${UNIVERSAL_OUTPUTFOLDER}/"
# 合并真机和模拟器framework
lipo -create -output "${UNIVERSAL_OUTPUTFOLDER}/${PROJECT_NAME}.framework/${PROJECT_NAME}" 
"${BUILD_DIR}/${CONFIGURATION}-iphoneos/${PROJECT_NAME}.framework/${PROJECT_NAME}" 
"${BUILD_DIR}/${CONFIGURATION}-iphonesimulator/${PROJECT_NAME}.framework/${PROJECT_NAME}"
# 复制Swift模块（如果存在）
SIMULATOR_SWIFT_MODULES_DIR="${BUILD_DIR}/${CONFIGURATION}-iphonesimulator/${PROJECT_NAME}.framework/Modules/${PROJECT_NAME}.swiftmodule/."
if [ -d "${SIMULATOR_SWIFT_MODULES_DIR}" ]; then
cp -R "${SIMULATOR_SWIFT_MODULES_DIR}" "${UNIVERSAL_OUTPUTFOLDER}/${PROJECT_NAME}.framework/Modules/${PROJECT_NAME}.swiftmodule"
fi
# 复制到项目目录并打开Finder
cp -R "${UNIVERSAL_OUTPUTFOLDER}/${PROJECT_NAME}.framework" "${PROJECT_DIR}"
open "${UNIVERSAL_OUTPUTFOLDER}"

真机崩溃错误信息 #

dyld[541]: Library not loaded: @rpath/CustomFramework.framework/CustomFramework  
Referenced from: <E072FE8A-611F-30AB-A6ED-186777B4B0F1> /private/var/containers/Bundle/Application/8B615D3F-B911-41DB-A630-F74C7737DAC4/App.app/App  
原因: 尝试加载以下路径均失败: 
'/usr/lib/swift/CustomFramework.framework/CustomFramework' (文件不存在，不在dyld缓存中), 
'/private/preboot/Cryptexes/OS/usr/lib/swift/CustomFramework.framework/CustomFramework' (文件不存在), 
'/private/var/containers/Bundle/Application/8B615D3F-B911-41DB-A630-F74C7737DAC4/App.app/Frameworks/CustomFramework.framework/CustomFramework' (mach-o文件存在，但平台不兼容：当前为'iOS-sim'，需要'iOS'), 
后续重复路径均为相同平台不兼容问题

错误根源 #

你的通用Framework里同时包含了真机arm64和Apple Silicon模拟器arm64架构，虽然lipo显示是x86_64+arm64，但真机系统会识别到其中的模拟器arm64架构，判定平台不兼容，导致加载失败。

修复步骤 #

1. 修正通用Framework构建脚本

修改构建脚本，强制模拟器构建x86_64架构，避免和真机arm64混淆：

#!/bin/sh
UNIVERSAL_OUTPUTFOLDER=${BUILD_DIR}/${CONFIGURATION}-universal
mkdir -p "${UNIVERSAL_OUTPUTFOLDER}"

# 构建真机版本
xcodebuild -target "${PROJECT_NAME}" ONLY_ACTIVE_ARCH=NO -configuration ${CONFIGURATION} -sdk iphoneos BUILD_DIR="${BUILD_DIR}" BUILD_ROOT="${BUILD_ROOT}" clean build
cp -R "${BUILD_DIR}/${CONFIGURATION}-iphoneos/${PROJECT_NAME}.framework" "${UNIVERSAL_OUTPUTFOLDER}/"

# 强制构建模拟器x86_64架构（适配Rosetta和Apple Silicon模拟器）
xcodebuild -target "${PROJECT_NAME}" -configuration ${CONFIGURATION} -sdk iphonesimulator ONLY_ACTIVE_ARCH=NO ARCHS=x86_64 BUILD_DIR="${BUILD_DIR}" BUILD_ROOT="${BUILD_ROOT}" clean build

# 合并真机arm64和模拟器x86_64
lipo -create -output "${UNIVERSAL_OUTPUTFOLDER}/${PROJECT_NAME}.framework/${PROJECT_NAME}" \
"${BUILD_DIR}/${CONFIGURATION}-iphoneos/${PROJECT_NAME}.framework/${PROJECT_NAME}" \
"${BUILD_DIR}/${CONFIGURATION}-iphonesimulator/${PROJECT_NAME}.framework/${PROJECT_NAME}"

# 同时复制真机和模拟器的Swift模块
SIMULATOR_SWIFT_MODULES_DIR="${BUILD_DIR}/${CONFIGURATION}-iphonesimulator/${PROJECT_NAME}.framework/Modules/${PROJECT_NAME}.swiftmodule/."
DEVICE_SWIFT_MODULES_DIR="${BUILD_DIR}/${CONFIGURATION}-iphoneos/${PROJECT_NAME}.framework/Modules/${PROJECT_NAME}.swiftmodule/."
if [ -d "${SIMULATOR_SWIFT_MODULES_DIR}" ]; then
cp -R "${SIMULATOR_SWIFT_MODULES_DIR}" "${UNIVERSAL_OUTPUTFOLDER}/${PROJECT_NAME}.framework/Modules/${PROJECT_NAME}.swiftmodule"
fi
if [ -d "${DEVICE_SWIFT_MODULES_DIR}" ]; then
cp -R "${DEVICE_SWIFT_MODULES_DIR}" "${UNIVERSAL_OUTPUTFOLDER}/${PROJECT_NAME}.framework/Modules/${PROJECT_NAME}.swiftmodule"
fi

cp -R "${UNIVERSAL_OUTPUTFOLDER}/${PROJECT_NAME}.framework" "${PROJECT_DIR}"
open "${UNIVERSAL_OUTPUTFOLDER}"

2. 在RN项目iOS端添加剥离脚本（备选方案）

如果不想修改Framework构建脚本，可在RN项目Xcode工程中添加脚本，打包真机时自动剥离模拟器架构：

1. 打开RN项目的ios/[项目名].xcworkspace
2. 选中主项目Target，进入Build Phases
3. 点击+ -> New Run Script Phase
4. 输入以下脚本：

APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}"

# 遍历Frameworks目录，剥离模拟器架构
find "$APP_PATH/Frameworks" -name '*.framework' -type d | while read -r FRAMEWORK
do
FRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable)
FRAMEWORK_EXECUTABLE_PATH="$FRAMEWORK/$FRAMEWORK_EXECUTABLE_NAME"
echo "处理framework: $FRAMEWORK_EXECUTABLE_PATH"

# 检查是否包含模拟器架构
lipo -info "$FRAMEWORK_EXECUTABLE_PATH" | grep -q "i386\|x86_64\|arm64-simulator"
if [ $? -eq 0 ]; then
# 剥离模拟器架构，保留真机arm64
lipo -remove i386 -remove x86_64 -remove arm64-simulator "$FRAMEWORK_EXECUTABLE_PATH" -output "$FRAMEWORK_EXECUTABLE_PATH"
echo "已剥离模拟器架构"
fi
done

3. 验证修复效果

• 重新构建Framework，替换RN项目中的旧Framework
• 清理RN项目iOS构建缓存：cd ios && pod deintegrate && pod install && rm -rf build
• 重新打包真机测试，确认崩溃问题解决

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