iOS Firebase 静态库集成问题解决方案

问题概述

在 Flutter 或 React Native 项目中使用 Firebase 时，执行 pod install 命令可能会遇到 Swift pod 无法作为静态库集成的错误，特别是与 FirebaseCoreInternal-library 和 GoogleUtilities-library 相关的模块映射问题。

问题表现

执行 pod install、pod install --repo-update 或 pod update 时出现错误：

[!] The following Swift pods cannot yet be integrated as static libraries:

The Swift pod `FirebaseCoreInternal-library` depends upon
`GoogleUtilities-library`, which does not define modules. To opt into
those targets generating module maps (which is necessary to import
them from Swift when building as static libraries), you may set
`use_modular_headers!` globally in your Podfile, or specify
`:modular_headers => true` for particular dependencies.

解决方案概览

根据项目类型和 Firebase 版本，有多种解决方案可供选择：

React Native

# Podfile 修改方案
pod 'Firebase', :modular_headers => true
pod 'FirebaseCore', :modular_headers => true
pod 'GoogleUtilities', :modular_headers => true
$RNFirebaseAsStaticFramework = true

Expo

// app.json 配置方案
{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "ios": {
            "useFrameworks": "static",
            "podfileProperties": { "use_modular_headers!": true }
          }
        }
      ]
    ]
  }
}

Flutter

# Podfile 修改方案
target 'Runner' do
  use_frameworks! :linkage => :static
  use_modular_headers!
  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
end

详细解决方案

方案一：Expo 项目（推荐）

对于使用 Expo 的项目，这是最简单且可持续的解决方案：

1. 安装 expo-build-properties

npx expo install expo-build-properties

2. 在 app.json 中添加配置

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "ios": {
            "useFrameworks": "static",
            "podfileProperties": { "use_modular_headers!": true }
          }
        }
      ]
    ]
  }
}

3. 重新构建项目

npx expo prebuild --clean

方案二：React Native 项目

方法 A：使用静态框架（推荐）

在 Podfile 中添加以下配置：

platform :ios, '12.4'

target 'YourApp' do
  use_frameworks! :linkage => :static
  $RNFirebaseAsStaticFramework = true
  
  # 添加必要的模块头文件配置
  pod 'Firebase', :modular_headers => true
  pod 'FirebaseCore', :modular_headers => true
  pod 'GoogleUtilities', :modular_headers => true
  
  # 其他现有配置...
end

方法 B：仅使用模块头文件

如果不想启用 use_frameworks!，可以单独为每个依赖项设置模块头文件：

target 'YourApp' do
  # 不启用 use_frameworks!
  
  # 只为 Firebase 相关依赖启用模块头文件
  pod 'Firebase', :modular_headers => true
  pod 'FirebaseCore', :modular_headers => true
  pod 'FirebaseCoreInternal', :modular_headers => true
  pod 'GoogleUtilities', :modular_headers => true
  
  # 其他现有配置...
end

方案三：Flutter 项目

对于 Flutter 项目，修改 ios/Podfile：

platform :ios, '11.0'

target 'Runner' do
  use_frameworks! :linkage => :static
  use_modular_headers!
  
  # 如果有特定依赖需要模块头文件
  pod 'GoogleUtilities', :modular_headers => true
  pod 'FirebaseCoreInternal', :modular_headers => true
  
  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
end

重要注意事项

兼容性问题

1. Flipper 兼容性：启用 use_frameworks! 会导致 Flipper 无法工作
2. Swift 模块兼容性：某些 Firebase 模块（如 Functions 和 Storage）需要 use_frameworks!
3. 未来兼容性：随着更多 Firebase 模块转向 Swift，仅使用模块头文件的解决方案可能不再适用

长期考虑

React Native Firebase 维护者指出，避免使用 use_frameworks! 的变通方案只是临时的，随着更多模块转换为 Swift，这些方案最终会失效。建议：

• 采用 use_frameworks! :linkage => :static
• 或者迁移到完全支持静态框架的依赖项

故障排除

如果上述方案仍无法解决问题：

1. 清理并重新安装

cd ios
pod deintegrate
pod install --repo-update

2. 检查 Firebase 版本兼容性

npm list @react-native-firebase/app

3. 查看具体错误信息

• 错误可能指向特定依赖项，需要单独为其设置 :modular_headers => true

总结

Firebase iOS 集成问题主要源于 CocoaPods 的静态库与动态框架配置冲突。根据项目类型选择合适的解决方案：

• Expo 项目：使用 expo-build-properties 插件
• React Native：优先选择 use_frameworks! :linkage => :static
• Flutter：结合使用静态框架和模块头文件

遵循这些解决方案，您应该能够成功解决 Firebase pod 集成问题并顺利进行 iOS 开发。