如何将XCFramework正确集成到Podspec中并解决非模块化头文件报错

错误根因 #

你当前的错误是由手动指定单架构切片的头文件作为source_files导致的：XCFramework本身已经内置了全架构对应的头文件目录，CocoaPods会自动根据编译时的目标架构匹配对应切片的Headers路径，手动指定单架构头文件会触发路径映射异常，进而报非模块化头文件错误。

正确配置方法 #

1. 首先删除Podspec中xcframework.source_files = 'path/to/framework_1.xcframework/ios-arm64_x86_64-simulator/Headers/**/*.h'这行配置，不需要手动引入XCFramework内部的头文件。
2. 给XCFramework的subspec补充如下配置，确保头文件搜索路径和模块化配置正确：

Spec do |spec|
  # 原有基础信息配置保留
  spec.subspec 'XCFrameworkPod' do |xcframework|
    xcframework.vendored_frameworks = 'path/to/framework_1.xcframework'
    # 补充头文件搜索路径，CocoaPods会自动替换变量匹配对应架构切片
    xcframework.pod_target_xcconfig = {
      'HEADER_SEARCH_PATHS' => '$(inherited) "${PODS_XCFRAMEWORKS_BUILD_DIR}/XCFrameworkPod/Headers"',
      'CLANG_ALLOW_NON_MODULAR_INCLUDES_IN_FRAMEWORK_MODULES' => 'YES',
      'USE_HEADERMAP' => 'NO'
    }
    # 如果你的XCFramework没有内置modulemap，新增如下配置，指定自定义的modulemap路径
    # xcframework.module_map = 'path/to/your/custom/module.modulemap'
  end
end

3. 如果需要自定义modulemap，参考如下模板编写，可解决inttypes.h非模块化引用的报错：

framework module Framework1 {
  umbrella header "你的主头文件名.h"
  export *
  module * { export * }
  # 显式声明依赖系统的inttypes模块，避免非模块化报错
  use Darwin.C.inttypes
  link "framework"
}

4. 清理缓存重新集成：

# 清理项目集成缓存
pod deintegrate
# 清理本地Pod缓存
pod cache clean --all
# 重新集成
pod install
# 最后手动清理Xcode的DerivedData目录，避免旧缓存残留

额外排查点 #

如果配置后仍有报错，检查以下项：

• 所有引用该XCFramework头文件的地方，都使用<Framework1/xxx.h>的框架式引用格式，不要用"xxx.h"的相对路径引用
• 检查XCFramework的Info.plist中各架构切片的Headers字段配置正确，指向对应的Headers目录
• 确认Podspec的平台配置和XCFramework支持的平台匹配，避免不相关架构的切片被错误引入编译流程

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