集成封装静态库的XCFramework提示找不到模块如何解决

封装.a静态库的XCFramework触发No such module $FRAMEWORK、Cannot find $FRAMEWORK in scope报错，核心原因是绝大多数第三方打包纯Objective-C/C静态库生成XCFramework时，默认不会生成Clang模块映射文件，Xcode无法将其识别为可直接导入的独立模块。手动拷贝头文件到项目里能临时运行，本质是绕开了Xcode的模块校验逻辑，长期使用会出现头文件与库版本不匹配、符号冲突等问题。 #

不要手动给XCFramework下不同架构切片配置搜索路径，这是集成普通多架构静态库的过时方案，Xcode对XCFramework有原生的架构自动匹配逻辑，手动配路径反而会触发识别错误。

1. 先补全XCFramework缺失的模块映射文件 #

先打开XCFramework包内容，检查每个架构切片目录（比如ios-arm64_armv7_armv7s、ios-arm64_i386_x86_64-simulator）下的结构：

• 确认切片根目录存在对应架构的.a静态库文件
• 确认切片根目录存在Headers文件夹，且所有公开头文件（含SDK总入口头文件）都存放在该目录下
• 检查是否存在Modules文件夹，以及文件夹内是否有module.modulemap文件——90%以上的此类报错都是因为第三方打包时漏了这个文件。

如果缺失，按以下内容新建module.modulemap，放到每个切片的Modules/目录下：

module 替换为你的SDK实际模块名 {
    umbrella header "替换为SDK总入口头文件名.h"
    export *
    module * { export * }
}

注意：每个架构切片下的文件路径、modulemap内容必须完全一致，不要出现某一个切片漏放的情况。

2. 清理项目旧配置 #

把之前手动添加的和该SDK相关的头文件搜索路径、库搜索路径全部删除，把之前手动拖入项目的SDK头文件、静态库文件全部移除，避免旧配置冲突。

3. 嵌套依赖层级配置 #

针对「主App -> 子项目 -> SDK」的三层依赖结构，配置时要遵循依赖传递规则：

• 把补全modulemap的XCFramework直接拖入子项目的Frameworks, Libraries, and Embedded Content列表，Embed选项必须选择Do Not Embed——静态库打包的XCFramework如果被嵌入，会触发主项目链接时的符号重复错误。
• 子项目和主App的Other Linker Flags配置中保留已添加的-ObjC -all_load，两层都要加，不要只配置某一层。
• 子项目和主App的Allow Non-modular Includes in Framework Modules选项都设置为YES，避免Objective-C头文件嵌套导入触发的非模块化报错。
• 子项目中不要在公开头文件（.h）里直接导入SDK内容，需要引用SDK类时用@class 类名;做前置声明，在.m实现文件中再用@import 模块名;或者#import <模块名/总头文件名.h>导入即可。

• 手动配置架构切片路径的方案完全不需要，补全modulemap后Xcode会自动根据编译目标架构选择对应切片的头文件、库文件，不需要手动干预。
• SPM集成方案失败也是因为XCFramework缺失modulemap，补全modulemap后，直接在Package.swift里将XCFramework配置为binaryTarget即可正常集成，不需要额外配置搜索路径。

内容的提问来源于stack exchange，提问作者k-thorat