如何为XCFramework手动添加modulemap文件支持？

背景 #

我有一个目录结构如下的XCFramework：

.
└── WechatOpenSDK-XCFramework.xcframework
    ├── Info.plist
    ├── README.txt
    ├── ios-arm64_armv7
    │	├── Headers
    │	│	├── WXApi.h
    │	│	├── WXApiObject.h
    │	│	└── WechatAuthSDK.h
    │	├── Modules
    │	│	└── module.modulemap
    │	└── libWechatOpenSDK.a
    └── ios-arm64_i386_x86_64-simulator
        ├── Headers
        │	├── WXApi.h
        │	├── WXApiObject.h
        │	└── WechatAuthSDK.h
        ├── Modules
        │	└── module.modulemap
        └── libWechatOpenSDK.a

该XCFramework原本不含Modules目录及module.modulemap文件，是我手动添加的。我尝试了两种module.modulemap定义方式：

第一种定义 #

framework module WechatOpenSDK {
  umbrella header "WXApi.h"

  export *
  module * { export * }
}

第二种定义 #

framework module WechatOpenSDK {
  header "WXApi.h"
  header "WXApiObject.h"
  header "WechatAuthSDK.h"

  export *
}

但将这个XCFramework拖入其他项目后，无论用哪种定义，都无法通过import WechatOpenSDK导入框架。我还尝试修改了XCFramework顶层的Info.plist文件，移除了值为Headers的HeadersPath属性，但问题依旧。

解决方案 #

1. 修正Modulemap的路径引用 #

你的两种定义都存在路径错误：module.modulemap位于Modules目录下，头文件在同级的Headers目录，必须用相对路径引用头文件：

推荐写法一（Umbrella Header）

framework module WechatOpenSDK {
  umbrella header "../Headers/WXApi.h"
  
  export *
  module * { export * }
}

推荐写法二（逐个指定头文件）

framework module WechatOpenSDK {
  header "../Headers/WXApi.h"
  header "../Headers/WXApiObject.h"
  header "../Headers/WechatAuthSDK.h"
  
  export *
}

2. 恢复并确认Info.plist配置 #

不要移除HeadersPath，打开XCFramework顶层的Info.plist，找到对应架构的HeadersPath字段，确保值为Headers（头文件确实在每个架构目录下的Headers文件夹中），如果之前删除了，重新添加该属性。

3. 项目导入后的配置检查 #

• 拖入XCFramework后，确认Build Phases → Link Binary With Libraries中已包含该框架。
• 检查项目Build Settings：
  • Framework Search Paths需包含XCFramework的路径，建议勾选Recursive。
  • Enable Modules (C and Objective-C)设置为YES。
  • 若自动识别路径失败，可手动在Import Paths中添加$(PROJECT_DIR)/[XCFramework所在路径]/ios-arm64_armv7/Headers（模拟器架构路径同理）。

4. 清理项目重试 #

• 按Command + Shift + K清理项目。
• 关闭Xcode，删除~/Library/Developer/Xcode/DerivedData目录下的对应项目缓存。
• 重新打开项目，尝试import WechatOpenSDK。

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