如何使用CMake生成可分发的iOS xcframework归档包

核心结论：完全可以跳过CMake默认绑定的xcodebuild build逻辑，把苹果要求的xcodebuild archive、xcframework合成步骤完全嵌入CMake构建流，全程不需要手动跳出CMake执行零散命令，生成的产物完全符合官方分发要求。

为什么默认cmake --build不会生成归档产物 #

CMake的Xcode生成器默认将构建动作映射为xcodebuild build，该命令仅输出本地调试用的编译产物，不会触发归档流程中要求的元数据校验、框架结构整理、模块化兼容配置，直接拿这个阶段的.framework打出来的xcframework会存在缺少签名信息、模块声明缺失、架构不兼容等问题，无法直接对外分发。

具体实现步骤 #

1. 预先给CMake目标配置archive兼容的构建设置 #

在定义库目标时，直接通过Xcode属性设置把归档需要的参数提前注入，避免后续xcodebuild archive调用时参数不匹配：

• 关闭跳过安装标记SKIP_INSTALL，保证archive阶段会把框架文件纳入归档包
• 配置正确的框架安装路径INSTALL_PATH，匹配archive时的目录结构规则
• 开启库分发适配BUILD_LIBRARY_FOR_DISTRIBUTION，保证不同系统版本下的符号兼容
• 按需配置签名参数，避免归档时卡在签名校验环节

对应的CMake配置示例：

add_library(MySharedLib SHARED ...)

set_target_properties(MySharedLib PROPERTIES
    XCODE_ATTRIBUTE_SKIP_INSTALL NO
    XCODE_ATTRIBUTE_INSTALL_PATH "$(LOCAL_LIBRARY_DIR)/Frameworks"
    XCODE_ATTRIBUTE_BUILD_LIBRARY_FOR_DISTRIBUTION YES
    XCODE_ATTRIBUTE_DEFINES_MODULE YES
    XCODE_ATTRIBUTE_CODE_SIGN_IDENTITY "Apple Development"
    XCODE_ATTRIBUTE_DEVELOPMENT_TEAM "你的开发团队ID"
)

2. 嵌入自定义archive命令替代默认build动作 #

针对每个需要支持的平台/架构维度，通过add_custom_command定义独立的归档输出目标，直接调用xcodebuild archive生成对应架构的.xcarchive归档包：

• 每个归档指定独立的输出路径，避免不同架构的产物互相覆盖
• 明确指定对应平台的sdk、架构参数，保证产物匹配目标平台要求
• 把原有编译目标设为自定义命令的依赖，保证归档前先完成代码编译

示例：

# 定义iOS Device架构的归档输出
set(IOS_DEVICE_ARCHIVE ${CMAKE_BINARY_DIR}/archives/ios_device/MySharedLib.xcarchive)
add_custom_command(OUTPUT ${IOS_DEVICE_ARCHIVE}
    COMMAND xcodebuild archive
        -project ${CMAKE_BINARY_DIR}/MyProject.xcodeproj
        -scheme MySharedLib
        -configuration Release
        -sdk iphoneos
        -arch arm64
        -archivePath ${IOS_DEVICE_ARCHIVE}
        SKIP_INSTALL=NO
    DEPENDS MySharedLib
    COMMENT "Generating iOS Device platform archive"
)

# 按照相同逻辑补充iOS Simulator、macOS等其他平台的归档命令

3. 串联归档产物自动合成最终xcframework #

定义最终的分发产物目标，把所有分平台的归档包作为依赖，待所有归档完成后自动调用xcodebuild -create-xcframework合成符合要求的xcframework：

• 输入路径取每个归档包内Products/Library/Frameworks/下的正式框架文件，不要直接引用编译临时目录里的非归档产物
• 输出路径指定到专门的分发目录，方便后续直接取用

示例：

set(FINAL_XCFRAMEWORK ${CMAKE_BINARY_DIR}/dist/MySharedLib.xcframework)
add_custom_target(DistributableXCFramework ALL
    COMMAND xcodebuild -create-xcframework
        -framework ${IOS_DEVICE_ARCHIVE}/Products/Library/Frameworks/MySharedLib.framework
        -framework ${IOS_SIMULATOR_ARCHIVE}/Products/Library/Frameworks/MySharedLib.framework
        -framework ${MACOS_ARCHIVE}/Products/Library/Frameworks/MySharedLib.framework
        -output ${FINAL_XCFRAMEWORK}
    DEPENDS
        ${IOS_DEVICE_ARCHIVE}
        ${IOS_SIMULATOR_ARCHIVE}
        ${MACOS_ARCHIVE}
    COMMENT "Packaging final distributable xcframework"
)

常见注意事项 #

• 不要用CMake内置的install规则拼接框架结构，该规则的目录逻辑和xcodebuild archive的规范不匹配，极易出现Info.plist缺失、模块声明丢失的问题，必须走真实archive流程生成的产物才符合官方要求
• 日常执行cmake --build时直接指定DistributableXCFramework作为构建目标即可，CMake会自动按依赖顺序完成编译、分平台归档、最终打包全流程，不需要手动脱离CMake执行零散命令
• 对需要支持Swift并发、Swift 5.9模块化稳定的场景，需要额外在构建设置里匹配对应Swift版本，避免归档后的框架存在编译兼容问题

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