React Native Maps 在 iOS 构建中的模块化问题解决方案

在使用 React Native Maps 1.20.1 版本与 React Native 0.78.1 搭配开发 iOS 应用时，开发者可能会遇到一个常见的构建错误："non-modular-include-in-framework-module"。这个问题通常出现在 Podfile 配置不当的情况下，特别是在使用静态框架链接时。

问题背景

当开发者按照官方文档的指示，在 Podfile 中添加以下配置时：

rn_maps_path = '../node_modules/react-native-maps'
pod 'react-native-google-maps', :path => rn_maps_path

并在执行 pod install 后尝试构建项目时，Xcode 会抛出上述错误。这个问题的根源在于 Podfile 中模块的声明顺序和位置不正确。

根本原因分析

1. 模块声明位置错误：React Native Maps 的 pod 声明被放在了全局作用域或 target 块之外，这会导致 Xcode 在解析模块依赖关系时出现混乱。

2. 静态框架链接冲突：当项目中同时启用了 use_frameworks! :linkage => :static 配置时，模块的加载顺序和位置变得尤为关键。

3. React Native 0.78+ 的构建系统变化：新版本的 React Native 对 iOS 构建系统做了一些调整，对模块的声明顺序更加敏感。

解决方案

正确的做法是将 React Native Maps 的 pod 声明移动到 target 块内部，确保它在正确的上下文中被加载：

target 'YourAppName' do
  # 其他配置...
  
  # 将 react-native-maps 的声明放在这里
  rn_maps_path = '../node_modules/react-native-maps'
  pod 'react-native-google-maps', :path => rn_maps_path
  
  # 其他依赖...
end

修改后需要执行以下步骤：

1. 删除 ios/Pods 目录
2. 删除 ios/Podfile.lock 文件
3. 运行 pod install 重新安装依赖

最佳实践建议

1. 保持 Podfile 结构清晰：将第三方库的声明都放在 target 块内部，避免全局声明。

2. 注意静态框架的特殊性：当使用 use_frameworks! :linkage => :static 时，要特别注意模块之间的依赖关系。

3. React Native 版本兼容性：升级 React Native 版本时，要检查 Podfile 是否需要相应调整。

4. 构建缓存清理：遇到类似问题时，除了清理 Pods 相关文件，还可以尝试清理 Xcode 的 DerivedData 目录。

通过遵循这些原则，开发者可以避免大多数与模块化相关的构建错误，确保 React Native Maps 在 iOS 平台上正常工作。