Xcode编译xcframework后导入项目报Unknown attribute 'Combine.Published'错误

安全阿岳

2026-10-1

问题诱因

Framework未开启模块定义：开启BUILD_LIBRARIES_FOR_DISTRIBUTION参数的前提下，必须同步开启Defines Module配置，否则生成的xcframework会丢失模块映射，导致宿主项目无法识别内部符号
公开头文件配置错误：Archive构建流程和普通Debug构建的头文件搜索路径逻辑有差异，如果需要对外暴露的头没有放到Build Phases > Headers的Public分组下，Archive生成的framework会丢失公开头
Swift访问权限不符合分发要求：普通本地构建允许同模块下默认的internal权限访问，但是开启BUILD_LIBRARIES_FOR_DISTRIBUTION后，所有对外暴露的类、方法、属性必须显式标记public或open，否则会被从分发接口中剔除
测试项目链接配置错误：如果CleanUI是静态framework，需要在测试项目的Other Linker Flags中添加-ObjC标识，强制链接所有OC分类符号，避免运行时符号缺失
架构切片冲突：Xcode 14及以上版本默认会为模拟器构建arm64切片，如果你的测试项目排除了模拟器arm64架构，会导致架构不匹配报错

修复方案

调整Framework项目构建设置

搜索Defines Module，将所有配置的取值设为YES
搜索Build Libraries for Distribution，确认所有配置的取值为YES，和脚本参数保持一致避免被覆盖
检查iOS Deployment Target，确认取值和你的测试项目的部署目标版本一致或更低

检查公开符号配置

OC混编项目：切换到Build Phases > Headers，把所有需要对外暴露的头文件从Project/Private分组拖到Public分组，同时确认Umbrella头文件中正确导入了所有公开OC头
纯Swift项目：所有需要对外暴露的类、结构体、方法、属性显式添加public/open修饰符，需要支持外部继承的类和方法要标记open

调整测试项目配置

确认导入xcframework的嵌入配置：动态framework选Embed & Sign，静态framework选Do Not Embed
在测试项目的Build Settings > Other Linker Flags中添加-ObjC参数
检查测试项目的Excluded Architectures配置，不要排除和xcframework匹配的架构

使用优化后的编译脚本，新增清理旧产物、强制开启模块定义的逻辑：

# 先清理旧的构建产物
rm -rf ./build

# 编译iOS真机架构
xcodebuild archive \
  -scheme CleanUI \
  -configuration Release \
  -destination 'generic/platform=iOS' \
  -archivePath './build/CleanUI.framework-iphoneos.xcarchive' \
  SKIP_INSTALL=NO \
  BUILD_LIBRARIES_FOR_DISTRIBUTION=YES \
  DEFINES_MODULE=YES

# 编译iOS模拟器架构
xcodebuild archive \
  -scheme CleanUI \
  -configuration Release \
  -destination 'generic/platform=iOS Simulator' \
  -archivePath './build/CleanUI.framework-iphonesimulator.xcarchive' \
  SKIP_INSTALL=NO \
  BUILD_LIBRARIES_FOR_DISTRIBUTION=YES \
  DEFINES_MODULE=YES

# 生成xcframework
xcodebuild -create-xcframework \
  -framework './build/CleanUI.framework-iphonesimulator.xcarchive/Products/Library/Frameworks/CleanUI.framework' \
  -framework './build/CleanUI.framework-iphoneos.xcarchive/Products/Library/Frameworks/CleanUI.framework' \
  -output './build/CleanUI.xcframework'

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