使用Expo Modules集成第三方本地XCFramework（iOS）遇头文件缺失问题

你在构建Expo Modules封装的Spotify iOS SDK模块时，遇到模拟器构建报错：'SpotifyAppRemote.h' file not found，手动复制头文件到指定路径可临时解决，但需要通过podspec配置彻底修复。

错误信息示例 #

❌  (/Users/<username>/Library/Developer/Xcode/DerivedData/expospotifyexample-ayfjxgjzbhoakacqvfpiaawhvpwz/Build/Products/Debug-iphonesimulator/ExpoSpotify/ExpoSpotify-umbrella.h:13:9)

  11 | #endif
  12 | 
> 13 | #import "SpotifyAppRemote.h"
     |         ^ 'SpotifyAppRemote.h' file not found
  14 | #import "SpotifyiOS.h"
  15 | #import "SPTAppRemote.h"
  16 | #import "SPTAppRemoteAlbum.h"

核心问题分析 #

当前podspec配置错误地将Spotify SDK的头文件加入了source_files，导致CocoaPods错误地把这些头文件打包到你的模块umbrella header里，同时没有正确识别xcframework的内置头文件搜索路径，进而引发路径混乱和重复导入问题。

修正后的Podspec配置 #

直接修改你的ExpoSpotify.podspec，移除多余配置，只保留xcframework的正确引入：

require 'json'

package = JSON.parse(File.read(File.join(__dir__, '..', 'package.json')))

Pod::Spec.new do |s|
  s.name           = 'ExpoSpotify'
  s.version        = package['version']
  s.summary        = package['description']
  s.description    = package['description']
  s.license        = package['license']
  s.author         = package['author']
  s.homepage       = package['homepage']
  s.platform       = :ios, '13.0'
  s.swift_version  = '5.4'
  s.source         = { git: 'https://github.com/' }
  s.static_framework = true

  s.dependency 'ExpoModulesCore'

  # Swift/Objective-C compatibility
  s.pod_target_xcconfig = {
    'DEFINES_MODULE' => 'YES',
    'SWIFT_COMPILATION_MODE' => 'wholemodule',
    # 添加这行，确保Xcode能定位到xcframework
    'FRAMEWORK_SEARCH_PATHS' => '"$(PODS_ROOT)/ExpoSpotify"'
  }

  # 正确配置xcframework路径（与podspec同目录）
  s.vendored_frameworks = 'SpotifyiOS.xcframework'
  # 仅包含你的模块源码，不要包含SDK头文件
  s.source_files = "**/*.{h,m,swift}"
end

关键调整点 #

• 移除错误的source_files配置：不要把Spotify SDK的头文件加到source_files中，CocoaPods会自动处理xcframework的内置头文件搜索，无需手动导入。
• 添加FRAMEWORK_SEARCH_PATHS：明确告诉Xcode去哪里查找你的vendored xcframework。
• 简化vendored_frameworks路径：根据你的文件夹结构，xcframework和podspec在同一ios目录下，直接写SpotifyiOS.xcframework即可。
• 移除多余配置：删除preserve_paths和header_mappings_dir，这些配置会干扰CocoaPods对xcframework的默认处理逻辑。

后续操作 #

1. 删除example/ios/Pods文件夹、Podfile.lock文件
2. 清除Xcode的DerivedData（可通过Xcode菜单File > Project Settings > Derived Data路径删除）
3. 在example/ios目录下重新执行pod install
4. 重新构建项目

问题根源解释 #

• 将SDK头文件加入source_files会让CocoaPods将这些头文件复制到你的模块公共头目录，同时因为xcframework包含多架构版本，导致重复生成导入语句。
• header_mappings_dir配置错误地改变了头文件的映射路径，导致导入路径混乱，无法正确找到头文件。

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