react-native-maps 安装与配置指南：iOS / Android 双平台地图集成实战

• 移动开发
• UI组件
• 前端

【免费下载链接】react-native-maps

React Native Mapview component for iOS + Android

项目地址：https://gitcode.com/gh_mirrors/re/react-native-maps

点击查看免费下载

导读

本文是 react-native-maps（当前仓库版本 v1.29.5）的官方安装与配置手册，覆盖从 npm 安装、Expo 插件接入，到 iOS 端 Apple Maps / Google Maps 双后端选择、Android 端 Google Maps API Key 注入的完整流程，并整理了大量一线开发中常见的故障排查方案。读完本文，你将掌握在裸工作流（bare workflow）与 Expo 托管项目中正确接入地图组件、配置双平台原生依赖的全部操作步骤。

---

一、安装 npm 包

react-native-maps 以 npm 包形式分发，安装命令非常简单：

$ npm install react-native-maps # --- 或 --- $ yarn add react-native-maps

安装前请确认你的工程满足版本约束。从仓库的 package.json 可以看到，该库的 peerDependencies 要求：

• react >= 18.3.1
• react-native >= 0.76.0
• react-native-web >= 0.11（可选，仅 Web 端需要）

同时engines字段要求node >= 20.19.4。注意：npm install完成后，真正的原生地图实现还需要根据平台分别做配置，不能直接跑起来。

二、平台差异：地图后端的选择

地图的实际渲染实现完全取决于平台：

• Android：只能使用 Google Maps（Android SDK 端），因此你必须先申请一个Android SDK 专用 API Key。
• iOS：可以选择 Google Maps，也可以使用系统自带的Apple Maps（MapKit）实现。

当在 iOS 上使用 Google Maps 时，你还需要申请iOS SDK 专用 API Key，并把 Google Maps 原生库引入构建；而基于 Apple Maps 的实现则开箱即用，配置更简单，代价是会缺少一部分只有 Google Maps 后端才支持的特性（如 KML 标记、热力图、聚合标记等）。

WARNING：在使用 Google Maps Platform 的 API 与 SDK 之前，你必须先注册 Google Cloud 账号并创建billing account（计费账号），否则无法启用地图服务。

这一平台差异也直接体现在仓库的原生代码结构上：iOS 侧同时维护了两套实现，Apple Maps 实现位于 ios/AirMaps，Google Maps 实现位于 ios/AirGoogleMaps；Android 侧则只有一套基于 Google Maps SDK 的实现，位于 android/src/main/java/com/rnmaps/maps。

三、Expo 项目接入（config plugin）

如果你使用 Expo，可以通过官方提供的 config plugin 一键接入，只需把它加入app.json（或app.config.js）的plugins数组：

{ "expo": { "plugins": ["react-native-maps"] } }

Note:该插件仅兼容 react-native-maps 1.22 及以上版本，并要求 Expo SDK 版本 53 及以上。

如果使用 Google 作为地图提供方，还需要在插件参数中为对应平台提供 API Key：

{ "expo": { "plugins": [ [ "react-native-maps", { "iosGoogleMapsApiKey": "YOUR_KEY_HERE", "androidGoogleMapsApiKey": "YOUR_KEY_HERE" } ] ] } }

插件背后做了什么

Expo 插件的实现在仓库的 plugin/src/index.ts，它会把 iOS 与 Android 两套修改逻辑串起来：

• iOS 侧（plugin/src/ios.ts）：把iosGoogleMapsApiKey写入Info.plist的GMSApiKey字段；当提供了 iOS Key 时，自动向 Podfile 注入pod 'react-native-maps/Google'，并在 Swift AppDelegate 的didFinishLaunchingWithOptions方法最前面插入GMSServices.provideAPIKey("...")调用（配合import GoogleMaps）。若未提供 Key，则会反过来把已注入的代码移除，保持工程干净。
• Android 侧（plugin/src/android.ts）：在AndroidManifest.xml的<application>节点下添加名为com.google.android.geo.API_KEY的<meta-data>条目；未提供 Key 时同样会移除该条目。

插件的类型定义见 plugin/src/types.ts，入口由 app.plugin.js 指向构建产物。这套机制意味着：Expo 用户不需要手动改 AppDelegate、Podfile 或 Manifest，插件会在expo prebuild时自动完成全部原生配置。

四、裸工作流：iOS 配置

对于 bare workflow（裸工作流）项目，需要按下面的步骤手动配置 iOS 与 Android。

4.1 安装 CocoaPods 依赖

安装完 npm 包后，进入 ios 目录执行：

$ (cd ios && pod install) # --- 或 --- $ npx pod-install

pod install会依据仓库根目录的 react-native-maps.podspec 解析依赖。从该文件可以看到，podspec 通过default_subspec = 'Maps'默认引入 Apple Maps 实现（ios/AirMaps），并附带一个构建脚本（script phase）：它会检测PODS_ROOT下是否存在GoogleMaps与Google-Maps-iOS-Utils库，并据此把HAVE_GOOGLE_MAPS宏写入 ios/AirMaps/RNMapsDefines.h，从而在编译期决定启用哪套后端。这也是「Apple Maps 开箱即用、Google Maps 需要显式接入」的底层原因。

4.2 启用 Google Maps（iOS）

若要在 iOS 上启用 Google Maps，请先获取 Google API Key，然后按工程语言修改 AppDelegate。

Objective-C（AppDelegate.m/AppDelegate.mm）

+ #import <GoogleMaps/GoogleMaps.h> @implementation AppDelegate ... (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { + [GMSServices provideAPIKey:@"_YOUR_API_KEY_"]; // add this line using the api key obtained from Google Console ...

注意：[GMSServices provideAPIKey]必须是didFinishLaunchingWithOptions方法中的第一个调用。

Swift（AppDelegate.swift）

React Native 0.77 及以上版本创建的工程默认使用 Swift 编写的 AppDelegate：

+ import GoogleMaps @main class AppDelegate: RCTAppDelegate { override func application( _ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil ) -> Bool { + GMSServices.provideAPIKey("_YOUR_API_KEY_") // add this line using the api key obtained from Google Console ... } }

同样，GMSServices.provideAPIKey必须是该方法的第一个调用。

仓库自带的示例工程 example/ios/rnmshowcase/AppDelegate.swift 展示了生产级的写法：它从 Info.plist 读取MAPS_API_KEY，再调用GMSServices.provideAPIKey(MAPS_API_KEY)，避免了把 Key 硬编码在源码中——这是值得推荐的实践。

4.3 部署目标与 Podfile 平台版本

Google Maps SDK for iOS 要求iOS 14+，因此请确保：

1. Xcode 工程（Targets → General → Deployment Info）的部署目标>= 14；
2. Podfile 顶部的 platform 声明>= 14：

platform :ios, '14'

（仓库示例工程 example/ios/Podfile 中实际使用的是platform :ios, '15.1'，这与 podspec 中s.platform = :ios, "15.1"一致。）

4.4 在 Podfile 中声明 Google Maps 子模块

在 Podfile 的use_native_modules!函数上方添加以下内容，然后在 ios 目录重新执行pod install：

# React Native Maps dependencies rn_maps_path = '../node_modules/react-native-maps' pod 'react-native-maps/Google', :path => rn_maps_path

从 react-native-maps.podspec 的s.subspec 'Google'定义可以看出，这条声明会引入ios/AirGoogleMaps源码、GoogleMaps与Google-Maps-iOS-Utils两个 CocoaPods 依赖，并以-DHAVE_GOOGLE_MAPS=1 -DHAVE_GOOGLE_MAPS_UTILS=1编译。示例工程的实际用法见 example/ios/Podfile（该工程将rn_maps_path设为'../..'，因为它在仓库内以相对路径引用本库）。

4.5 覆盖 Google Maps 依赖版本（可选）

如果你需要锁定 Google Maps 相关依赖的版本，可以在 Podfile 中、react-native-maps/Google声明之前设置两个全局变量：

$RNMapsGoogleMapsVersion = '10.10.0' $RNMapsGoogleMapsUtilsVersion = '7.0.0' rn_maps_path = '../node_modules/react-native-maps' pod 'react-native-maps/Google', :path => rn_maps_path

对应的解析逻辑位于 react-native-maps.podspec 中：podspec 默认使用GoogleMaps 9.4.0与Google-Maps-iOS-Utils 6.1.0，一旦检测到上述全局变量已定义，就会改用你指定的版本。

4.6 Info.plist 位置权限说明

应用的Info.plist必须包含NSLocationWhenInUseUsageDescription键，并用面向用户的措辞清楚说明应用为什么需要位置信息，否则Apple 会拒绝应用上架。这一点无论你是否真正读取用户位置都是强制要求——因为 Google Maps iOS SDK 内部包含了访问用户位置的代码。

配置完成后，iOS 端的接入就完成了。

五、裸工作流：Android 配置

5.1 在 Manifest 中声明 Google Maps API Key

把 API Key 添加到android/app/src/main/AndroidManifest.xml：

<application> <!-- You will only need to add this meta-data tag, but make sure it's a child of application --> <meta-data android:name="com.google.android.geo.API_KEY" android:value="Your Google maps API Key Here"/> </application>

Android 端的地图视图 android/src/main/java/com/rnmaps/maps/MapView.java 及其管理器正是依赖这个 Key 初始化 Google Map 实例的。

5.2 升级到 v0.31.0+ 的说明

早期版本的安装文档要求你在build.gradle中配置supportLibVersion、playServicesVersion、androidMapsUtilsVersion等键。这些键现在都不再需要，可以安全删除（除非项目里其他模块仍在引用）。

ATTENTION：如果你仍保留了playServicesVersion，其版本号必须至少为18.0.0。

5.3 确保设备装有 Google Play Services

• 使用Genymotion 模拟器：按其官方 FAQ 中关于 Google Play Services 的指引安装。
• 使用真机：在 Google 搜索 "Google Play Services"，进入 Play Store 对应页面后点击更新按钮（注意不要在 Play Store 内部搜索，那样找不到更新入口）。

六、故障排查（Troubleshooting）

6.1 地图背景空白（Google Maps）

如果 Google logo、标记、折线等元素都正常显示，唯独地图背景空白，这几乎可以断定是 API Key 问题。请依次检查：

1. 核对 API Key 及其**应用限制（restrictions）**配置是否正确；
2. 确保原生侧provideAPIKey调用是didFinishLaunchingWithOptions的第一行；
3. 确保你的 Google Cloud 项目已启用对应的 API：
   • Android：Google Maps SDK for Android
   • iOS（如需要）：Google Maps SDK for iOS

参考：该问题在社区中被多次报告，相关 issue 编号为 #118、#176、#684。

6.2 地图背景灰色（Google Maps）

Android 设备上如果出现灰屏，可以在android/app/src/main/res/values/下创建google_maps_api.xml：

<resources> <string name="google_maps_key" templateMergeStrategy="preserve" translatable="false">(api key here)</string> </resources>

templateMergeStrategy="preserve"是 Android Studio 模板生成时的关键属性，可避免后续构建覆盖你的 Key 值。

6.3 完全没有地图（什么也不显示）

请确认地图组件及其容器都有明确的视口尺寸。示例如下：

import MapView, { PROVIDER_GOOGLE } from 'react-native-maps'; // remove PROVIDER_GOOGLE import if not using Google Maps ... const styles = StyleSheet.create({ container: { ...StyleSheet.absoluteFillObject, height: 400, width: 400, justifyContent: 'flex-end', alignItems: 'center', }, map: { ...StyleSheet.absoluteFillObject, }, }); export default () => ( <View style={styles.container}> <MapView provider={PROVIDER_GOOGLE} // remove if not using Google Maps style={styles.map} region={{ latitude: 37.78825, longitude: -122.4324, latitudeDelta: 0.015, longitudeDelta: 0.0121, }} > </MapView> </View> );

其中provider={PROVIDER_GOOGLE}在 src/ProviderConstants.ts 中定义；如果不用 Google Maps，请移除该 prop 及对应导入。

6.4 Google Maps iOS Utils 构建问题（iOS）

如果你的 Xcode 工程使用动态框架（例如工程中混有 Swift 代码），则无法通过 CocoaPods 安装Google-Maps-iOS-Utils。该问题及绕过方案在 Google 官方的google-maps-ios-utils仓库的Swift.md文档中有详细记录，可据此处理。

6.5 iOS 运行时错误（Apple Maps 后端）

• 如果工程按 Apple Maps 后端构建，却在运行时试图以GOOGLE_PROVIDER挂载地图，会直接抛出运行时异常；
• 使用 Apple Maps 时，部分依赖 Google Maps SDK 的高级功能会被以运行时错误的方式禁用，包括：
  • 从 KML 文件创建标记（Marker）
  • 热力图（Heatmap）渲染
  • 标记聚合（Marker clustering）
  • 其他 Google 专属能力

6.6 清理缓存

遇到构建或运行异常时，可以依次执行以下命令清理缓存：

watchman watch-del-all npm cache clean # Android，若遇到 `com.android.dex.DexException: Multiple dex files define Landroid/support/v7/appcompat/R$anim`，请清理 build 目录 cd android ./gradlew clean cd ..

6.7 使用 Android Studio

确保 Android Studio 保持最新，并按 React Native 官方环境搭建文档配置 SDK。特别注意以下包必须安装：

• Extras / Google Play services
• Extras / Google Repository
• Android 6.0 (API 23) / Google APIs Intel x86 Atom System Image Rev. 19
• Android SDK Build-tools 23.0.3

6.8 Android 模拟器问题

• 启动模拟器时，勾选Wipe user data；
• 使用 AVD（Android Virtual Devices）时，确保虚拟设备的设置中勾选了Use Host GPU；
• 如果模拟器上只显示[APPNAME] won't run without Google Play services which are not supported by your device.提示，说明当前系统镜像不含 Google APIs，需要在 Android SDK Manager 中下载包含 Google APIs 的 CPU/ABI 系统镜像，再切换模拟器的 CPU/ABI 设置。

6.9 Google Play Services 与其他模块版本冲突

当多个模块同时依赖相同版本的 Google Play Services 依赖（例如react-native-onesignal）时，可以从这些模块中排除冲突依赖，改在工程级build.gradle中统一引入：

implementation(project(':react-native-onesignal')){ exclude group: 'com.google.android.gms' } implementation(project(':react-native-maps')){ exclude group: 'com.google.android.gms' } implementation 'com.google.android.gms:play-services-base:18.0.1' implementation 'com.google.android.gms:play-services-location:19.0.1' implementation 'com.google.android.gms:play-services-maps:18.0.2'

ATTENTION：react-native-maps要求play-services-maps >= 18.0.0，低于该版本将无法编译通过。

6.10 Google Play services 本身的问题

• 确认你的模拟器包含 Google Play（路径：Android Studio → Virtual Devices → 检查 "Play Store" 列是否有图标）；
• 点击模拟器底部的点状（...）图标；
• 进入 Google Play 标签页并点击Update完成更新。

---

七、小结

回顾整条安装链路：npm 安装 → 按平台注入 API Key → 引入原生依赖 → 配置权限与部署目标。三个关键点值得牢记：

1. API Key 双平台分离：Android 与 iOS 的 Key 不同，且 iOS 的provideAPIKey必须是首行调用；
2. iOS 后端二选一：默认 Apple Maps 开箱即用，Google Maps 需要额外 Podfile 声明、版本变量与位置权限文案；
3. Expo 用户优先走插件：在 app.json 中声明react-native-maps插件并传入 Key，原生配置由 config plugin（plugin/src/index.ts）自动完成，大幅降低接入成本。

如需进一步了解组件的具体用法，可继续阅读仓库中的 docs/mapview.md、docs/marker.md、docs/polyline.md 等专项文档；示例工程的完整接入代码可参考 example/ios/rnmshowcase/AppDelegate.swift 与 example/ios/Podfile。

赞分享

• 移动开发
• UI组件
• 前端

【免费下载链接】react-native-maps

React Native Mapview component for iOS + Android

项目地址：https://gitcode.com/gh_mirrors/re/react-native-maps

点击查看免费下载

相关推荐

• React Native Maps终极指南：10个实用技巧实现流畅地图动画与精准定位

  React Native Maps终极指南：10个实用技巧实现流畅地图动画与精准定位 React Native Maps是React Native生态中最强大的

  移动开发UI组件前端

• 终极指南：如何快速配置react-native-maps Apple Maps地图服务

  终极指南：如何快速配置react native maps Apple Maps地图服务 React Native Maps是React Native生态中最强大

  移动开发UI组件前端

• InSpec核心架构解析：理解框架内部工作原理

  InSpec核心架构解析：理解框架内部工作原理 InSpec是一个强大的基础设施审计和测试框架，它采用独特的架构设计来实现跨平台合规性检查。本文将深入解析InS

上一篇：极简流处理：Flink Java Lambda表达式实战指南

下一篇：阿里Wan2.2开源：电影级视频生成平民化，消费级显卡即可部署