React Native Maps 在 iOS 构建中的常见问题及解决方案

问题背景

React Native Maps 是一个广泛使用的跨平台地图组件库，但在升级到 1.22.x 版本后，许多开发者在 iOS 平台上遇到了构建失败的问题。这些问题主要出现在使用 React Native 0.79.1 版本且未启用新架构(Fabric)的项目中。

核心问题表现

开发者在使用 React Native Maps 1.22.0 及以上版本时，iOS 构建过程中会遇到多种错误：

1. 编译错误：Use of '@import' when C++ modules are disabled 错误
2. Pod 安装问题：找不到 react-native-maps-generated 规范
3. 头文件导入问题：Google Maps 相关头文件导入方式不兼容

根本原因分析

这些问题主要源于以下几个技术层面的变化：

1. Google Maps iOS SDK 的模块导入方式变更：从 1.22.0 版本开始，库内部使用了 @import 语法，而默认的 Xcode 项目配置可能未启用 C++ 模块支持。

2. 自动链接机制调整：新版本对 React Native 的自动链接机制做了修改，需要显式声明额外的 Pod 依赖。

3. 新旧架构兼容性问题：虽然问题出现在禁用新架构的项目中，但库的某些默认配置可能更倾向于支持新架构。

解决方案

1. Podfile 配置调整

在项目的 Podfile 中添加以下内容：

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

2. 解决 @import 语法问题

在 Podfile 的 post_install 阶段添加以下脚本，将特定文件中的 @import 替换为传统的 #import：

post_install do |installer|
  # ...其他配置...

  specific_files = [
    "#{Pod::Config.instance.installation_root}/Pods/Google-Maps-iOS-Utils/Sources/GoogleMapsUtilsObjC/include/GMSMarker+GMUClusteritem.h",
    "#{Pod::Config.instance.installation_root}/Pods/Google-Maps-iOS-Utils/Sources/GoogleMapsUtilsObjC/include/GMUGeoJSONParser.h",
    "#{Pod::Config.instance.installation_root}/Pods/Google-Maps-iOS-Utils/Sources/GoogleMapsUtilsObjC/include/GMUPolygon.h",
    "#{Pod::Config.instance.installation_root}/Pods/Google-Maps-iOS-Utils/Sources/GoogleMapsUtilsObjC/include/GMUWeightedLatLng.h",
    "#{Pod::Config.instance.installation_root}/Pods/GoogleMaps/Maps/Sources/GMSEmpty.h"
  ]

  specific_files.each do |file|
    if File.exist?(file)
      text = File.read(file)
      if text.include?("@import GoogleMaps;")
        new_text = text.gsub("@import GoogleMaps;", "#import <GoogleMaps/GoogleMaps.h>")
        File.open(file, "w") { |f| f.write(new_text) }
        puts "Patched @import in: #{file}"
      end
    end
  end
end

3. 清理和重建步骤

执行以下命令确保干净的构建环境：

# 清理 Pod 缓存
pod cache clean --all

# 删除旧的 Pod 相关文件
rm -rf Pods Podfile.lock

# 重新安装依赖
pod install --repo-update

针对 Expo 项目的特殊处理

对于使用 Expo 的项目，由于 Expo 会覆盖 Podfile 的修改，可以创建一个自定义插件来确保每次构建都应用这些修复：

1. 创建 react-native-maps-fix-plugin.js 文件
2. 实现自动修改 Podfile 的逻辑
3. 在 app.config.js 中引用该插件

版本兼容性建议

如果上述解决方案仍不奏效，可以考虑以下版本组合：

• React Native 0.77-0.79
• react-native-maps 1.20.1
• 明确指定版本号（避免使用 ^ 符号）

总结

React Native Maps 在 1.22.x 版本的 iOS 构建问题主要源于底层依赖和导入方式的变更。通过调整 Podfile 配置、修复头文件导入方式以及确保干净的构建环境，大多数情况下可以解决这些问题。对于特定环境（如 Expo），需要采用额外的自动化手段来确保修复的持久性。

开发者应根据自己的项目环境选择合适的解决方案，并在升级前充分测试地图功能的各种场景，确保不影响用户体验。