React Native Maps 安装与配置完全指南

穆继宪Half-Dane

于 2025-06-02 09:15:34 发布

阅读量353

点赞数 5

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00923/article/details/148377342

React Native Maps 安装与配置完全指南

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

前言

React Native Maps 是一个功能强大的跨平台地图组件库，允许开发者在 React Native 应用中集成地图功能。本文将详细介绍如何正确安装和配置该库，涵盖 iOS 和 Android 平台的完整设置流程，以及常见问题的解决方案。

基础安装

首先需要通过 npm 或 yarn 安装核心库：

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

该库在不同平台上有不同的实现方式：

Android 必须使用 Google Maps
iOS 可选择 Google Maps 或原生 Apple Maps

iOS 平台配置

1. 安装依赖

安装 npm 包后，需要安装 iOS 的 CocoaPods 依赖：

cd ios && pod install
# 或
npx pod-install

2. Google Maps 配置（可选）

如需在 iOS 上使用 Google Maps，需要：

获取 Google Maps API 密钥
修改 AppDelegate.m(m) 文件：

#import <GoogleMaps/GoogleMaps.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  [GMSServices provideAPIKey:@"YOUR_API_KEY"];  // 必须是方法的第一行调用
  // 其他代码...
}

确保 iOS 部署目标 ≥13.4，在 Podfile 顶部添加：

platform :ios, '13.4'

在 Podfile 中添加 Google Maps 依赖（位于 use_native_modules! 之前）：

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

在 Info.plist 中添加位置使用说明：

<key>NSLocationWhenInUseUsageDescription</key>
<string>需要访问您的位置以提供地图服务</string>

Android 平台配置

1. 添加 Google Maps API 密钥

在 android/app/src/main/AndroidManifest.xml 中添加：

<application>
  <meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="您的Google Maps API密钥"/>
</application>

2. 版本兼容性说明

从 v0.31.0 开始，不再需要在 build.gradle 中指定以下版本号：

supportLibVersion
playServicesVersion
androidMapsUtilsVersion

但如果项目中其他模块需要，playServicesVersion 必须 ≥18.0.0

3. 确保 Google Play 服务可用

模拟器：需安装 Google Play 服务
真机：确保设备已安装最新版 Google Play 服务

常见问题解决方案

1. 地图背景空白（Google Maps）

可能原因：

API 密钥无效或配置错误
相关 Google API 未启用

解决方案：

确认 iOS 的 provideAPIKey 是 didFinishLaunchingWithOptions 的第一行调用
确保已启用以下 API：
- Google Maps SDK for Android
- Google Maps SDK for iOS（如使用）

2. 地图背景灰色（Android）

解决方案：在 android/app/src/main/res/values 创建 google_maps_api.xml：

<resources>
  <string name="google_maps_key" translatable="false">您的API密钥</string>
</resources>

3. 完全不显示地图

确保地图组件有明确的尺寸，示例：

import MapView from 'react-native-maps';

const styles = StyleSheet.create({
  container: {
    height: 400,
    width: '100%',
  },
  map: {
    ...StyleSheet.absoluteFillObject,
  },
});

function MyMap() {
  return (
    <View style={styles.container}>
      <MapView
        style={styles.map}
        region={{
          latitude: 37.78825,
          longitude: -122.4324,
          latitudeDelta: 0.015,
          longitudeDelta: 0.0121,
        }}
      />
    </View>
  );
}

4. 构建问题（iOS）

如果项目使用动态框架（包含 Swift 代码），Google-Maps-iOS-Utils 可能需要特殊处理。

5. 运行时错误（iOS）

确保构建配置与运行时使用的 provider 一致
Apple Maps 不支持某些 Google Maps 专属功能（如 KML 标记、热力图等）

6. 缓存问题

清理缓存命令：

watchman watch-del-all
npm cache clean
cd android && ./gradlew clean && cd ..

7. Google Play 服务冲突

当多个模块依赖不同版本的 Google Play 服务时，可在 build.gradle 中统一管理：

implementation(project(':react-native-other-module')){
    exclude group: 'com.google.android.gms'
}

implementation 'com.google.android.gms:play-services-base:18.0.1'
implementation 'com.google.android.gms:play-services-maps:18.0.2'