CocoaPods无法正常导入自定义组件FooKit问题排查

1. 检查FooKit的podspec类型配置 #

红色靶心图标说明CocoaPods将FooKit识别成了测试目标而非常规框架组件。打开FooKit.podspec，确认组件类型配置正确：

Pod::Spec.new do |spec|
  spec.name         = "FooKit"
  spec.version      = "1.0.0"
  spec.summary      = "你的私有组件描述"
  spec.license      = { :type => "MIT", :file => "LICENSE" }
  spec.platform     = :ios, "13.0"
  spec.source       = { :git => "你的私有仓库地址", :tag => "#{spec.version}" }
  # 关键：确保源码路径指向正确的源码目录
  spec.source_files = "FooKit/**/*.{h,m,swift}"
  # Objective-C项目需额外配置公开头文件
  # spec.public_header_files = "FooKit/**/*.h"
end

如果误将FooKit定义为test_spec（比如使用spec.test_spec do |test_spec|块），CocoaPods会把它当作测试组件，不会被主项目识别为可导入模块。

2. 确认Podfile中FooKit的引用范围 #

检查测试项目的Podfile，确保FooKit直接添加到主App目标下，而非仅存在于测试目标中：

target 'TestApp' do
  use_frameworks!
  pod 'FooKit', :path => '../FooKit' # 或你的私有源地址
  pod 'BarKit'
  pod 'BazKit'
  pod 'ZotKit'
end

# 避免仅在测试目标中引用FooKit
# target 'TestAppTests' do
#   inherit! :search_paths
#   pod 'FooKit'
# end

3. 校验FooKit的源码结构配置 #

• Swift项目：确认FooKit目录下存在module.modulemap（手动管理模块时），或Xcode项目的模块配置正确；
• Objective-C项目：确认存在 umbrella header（如FooKit.h），并在podspec中通过spec.public_header_files配置公开头文件路径；
• 确保spec.source_files指向的目录包含所有需要编译的源码文件，无路径错误或空目录。

4. 清理缓存并重建项目 #

执行以下命令彻底清理后重新安装：

pod deintegrate
rm -rf Podfile.lock
rm -rf ~/Library/Caches/CocoaPods
pod install

关闭Xcode后重新打开工作区，执行Cmd+Shift+K清理编译缓存，再尝试编译导入。

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