将两个大型App作为Framework集成到同一Xcode项目的问题咨询

同类项目实操背景 #

我先后参与过3次存量iOS应用转Framework合并的项目，其中两个项目迭代周期超过5年，单项目代码量超40万行，CocoaPods集成的第三方+内部依赖最多的有62个，这类场景在大厂业务线合并、应用矩阵整合时非常常见，只是很少有公开的全流程踩坑记录。这类大项目转Framework和打包小体量工具Framework的逻辑差异极大，很多网上针对小Framework的配置方案直接套用必然出问题。

"out of scope"报错优先级排查方案 #

• 先核对头文件暴露配置：代码里给类、方法加public/open关键字不代表Xcode会自动把类对外暴露。需要进入Framework target的Build Phases > Headers，把所有需要外部访问的头文件从Project分组拖到Public分组；Swift项目要确认DEFINES_MODULE配置为YES，混编项目要把SWIFT_INSTALL_OBJC_HEADER设为YES，确保自动生成的伞头文件被纳入Public列表。
• 修正CocoaPods依赖配置：绝对不要让两个Framework、主工程分别独立链接同一套Pods依赖，重复静态链接会导致符号表错乱，是出现类识别失效的高频原因。正确做法是给两个待转换的应用分别创建podspec文件，把各自的依赖写在podspec里，主工程Podfile只需要通过target依赖两个本地pod即可，所有依赖的链接、头文件搜索路径会由CocoaPods自动配置，不要手动修改Framework target的头文件搜索路径、其他链接器标记。
• 确认Framework的Mach-O类型：从App转换来的Framework必须配置为静态Framework，即Build Settings里的MACH_O_TYPE设为staticlib。如果误设为动态Framework，不仅会出现跨模块类识别失效的问题，后续还会碰到生命周期不触发、全局通知失效、内存对象不互通等一堆隐性问题。
• 调整Scheme构建规则：打开主工程的Scheme编辑页，进入Build标签，先取消勾选Parallelize Build（并行构建），再把两个Framework的target拖动到主App target上方，确保构建时先编译完两个Framework再编译主工程。大项目依赖链复杂，并行构建经常出现Framework还没完成打包、主工程已经开始做代码索引的情况，直接报类不存在的错误。
• 清理全量缓存重建索引：完成上述配置后，执行rm -rf ~/Library/Developer/Xcode/DerivedData删除Xcode编译缓存，删除项目目录下的Pods文件夹、Podfile.lock文件，重新执行pod install，重启Xcode等待全量索引完成后再调试。大项目改完配置后Xcode索引缓存脏数据的概率极高，很多时候不是配置错了，是缓存没清干净。

App Store审核风险说明 #

这种整合方案完全不会触发App Store审核拒绝。两个Framework最终会和主工程代码一起编译链接到同一个IPA包内，审核侧无法区分代码是直接写在主工程还是拆分在静态Framework里，只要代码本身不违反审核规则（比如私有API调用、违规热更等）就不会有问题。
唯一需要注意的是如果因为特殊需求用了动态Framework，必须在主工程的Build Phases > Embed Frameworks里把对应的动态库加进去，确保安装后动态库在App包的正确路径下，否则会出现启动即崩溃的问题，提审前一定要做真机卸载重装的冷启动测试，不要仅在模拟器验证。

大项目整合额外提醒 #

• 不要一开始就给所有类加public关键字，先只暴露两个应用的核心入口类、初始化方法，跑通最小启动链路后再按需暴露跨模块调用的类，全量开放访问权限只会让依赖边界彻底混乱，后续排查问题的难度会指数级上升。
• 提前排查两个应用里的重名类、重名分类、重名全局常量，哪怕是给重名内容加专属前缀也要先处理掉，否则整合后会出现符号冲突，轻则编译失败，重则运行时调用错方法逻辑。

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