在 React Native 应用中添加原生地图
在 React Native 中配置 expo-maps,使用 Apple 地图和 Google 地图、共享标记、位置权限与相机控制,并了解 Android 密钥和 iOS 版本限制。
在开发构建(development build)中安装 expo-maps,然后在 iOS 上渲染 AppleMaps.View,在 Android 上渲染 GoogleMaps.View。这两个组件接收相同的相机、标记和位置数据,因此一个封装组件即可覆盖两个平台。
大多数 React Native 地图教程都是基于 react-native-maps 编写的,其 props 无法直接沿用到 Expo 的库中。如果把一段 <MapView> 代码直接复制到 expo-maps 项目里,从相机设置到其他所有属性都会报类型错误。
本指南完整介绍 expo-maps 的使用流程:选择地图库、构建应用、添加 Android API 密钥、在两个平台上渲染地图、添加标记、将地图居中到用户位置以及处理标记点击。同时还会说明 iOS 版本限制,这些限制决定了你能使用哪些功能。如果你需要 Mapbox 提供的矢量瓦片和自定义样式,请参阅使用 Mapbox 创建 React Native 地图。
核心要点
- expo-maps 通过
AppleMaps.View和GoogleMaps.View两个组件,分别在 iOS 上显示 Apple 地图、在 Android 上显示 Google 地图,不支持在 iOS 上使用 Google 地图。 - 需在开发构建中运行 expo-maps。Apple 地图无需 API 密钥,但 Android 需要在 app.json 的
android.config.googleMaps.apiKey中配置 Google Maps 密钥,然后重新构建。 cameraPosition仅设置地图的初始位置。如需之后移动相机,请通过地图的 ref 调用setCameraPosition。- Expo 文档列出 expo-maps 的最低版本要求为 iOS 17,而
onMarkerClick等标记点击回调需要 iOS 18。
应该使用 expo-maps 还是 react-native-maps?
如果你的 Expo 项目已经在使用开发构建,请选择 expo-maps。如果你需要在 iOS 上使用 Google 地图,或需要在 Expo Go 中运行,请选择 react-native-maps。expo-maps 是 Expo 官方的地图库,在 iOS 上通过 SwiftUI 渲染,在 Android 上通过 Jetpack Compose 渲染。react-native-maps 由社区维护,提供一套统一的 MapView API,可对接多种地图服务商。
| expo-maps | react-native-maps | |
|---|---|---|
| 开发方 | Expo 团队 | 社区 |
| 原生层 | SwiftUI(iOS)、Jetpack Compose(Android) | 单一 MapView 组件 |
| iOS 地图服务商 | 仅 Apple 地图 | Apple 地图或 Google 地图 |
| iOS 最低版本 | Expo 文档为 iOS 17;包的 README 标注为 iOS 18.0 | 本文不涉及 |
| Expo Go | 需使用开发构建 | 根据 Expo 文档,已内置于 Expo Go |
| 使用 React 组件作为标记 | 不支持(改用图片标记) | 支持 |
| API 形式 | 两个平台专属组件 | 单一组件 |
在发布之初,expo-maps 的公告将该库定位为 alpha 版本:“随 SDK 53 一同,我们发布了 expo-maps 的 alpha 版本。”而 SDK 58 的参考页面并未显示任何状态标签。上线前请查阅 expo-maps 参考文档确认其当前状态。另一种方案可参阅 Expo 的 react-native-maps 页面。
安装 expo-maps 并创建开发构建
expo-maps 需要两样东西:npm 包,以及包含该包的原生二进制文件(即开发构建)。请使用 Expo CLI 安装,以确保版本与你的 SDK 匹配:
npx expo install expo-maps expo-location expo-dev-client
npx expo run:ios # or: npx expo run:android
expo-location 用于在本指南后续部分获取用户坐标。expo-dev-client 会将二进制文件变为开发构建。expo-maps 文档只介绍了在开发构建中运行的方式,因此请使用开发构建。你也可以通过 EAS 进行云端构建。如需开箱即用的项目,可运行 npx create-expo-app --example with-maps,该项目已预先安装并配置好 expo-maps。
添加 Android Google Maps API 密钥
Apple 地图无需密钥即可使用。Android 上的 Google 地图则需要一个启用了 Maps SDK for Android 的 Google Cloud API 密钥,将其添加到 app.json 后还需重新构建应用。
- 创建 Google Cloud 项目并启用 Maps SDK for Android。
- 创建 API 密钥,并使用你的包名和签名证书的 SHA-1 指纹将其限制为仅供 Android 应用使用。对于 EAS 构建,可通过
eas credentials查看指纹。 - 在 app.json 中添加密钥和位置权限插件:
{
"expo": {
"android": {
"package": "com.example.places",
"config": {
"googleMaps": { "apiKey": "YOUR_ANDROID_MAPS_KEY" }
}
},
"plugins": [
[
"expo-maps",
{
"requestLocationPermission": true,
"locationPermission": "Allow $(PRODUCT_NAME) to show your position on the map"
}
]
]
}
}
- 运行
npx expo run:android重新构建。仅重新加载 JavaScript 无法使原生配置的变更生效。
在插件选项中,requestLocationPermission 是一个布尔值,用于向 AndroidManifest.xml 和 Info.plist 添加权限声明;locationPermission 用于设置仅限 iOS 的权限用途说明。app.json 无法读取环境变量。若要避免将密钥提交到代码仓库,可将相同的 android.config.googleMaps.apiKey 路径迁移到 app.config.js 中,并在其中通过 process.env 读取密钥。
在两个平台上显示地图
expo-maps 没有跨平台组件,因此需要编写一个小型封装组件,根据 Platform.OS 选择 AppleMaps.View 或 GoogleMaps.View,并为两者传入相同的 cameraPosition。CameraPosition 是一个包含 coordinates 和 zoom 的对象:
import { Platform, Text } from 'react-native';
import { AppleMaps, GoogleMaps } from 'expo-maps';
const START = { coordinates: { latitude: 51.5074, longitude: -0.1278 }, zoom: 12 };
export function BasicMap() {
if (Platform.OS === 'ios') return <AppleMaps.View style={{ flex: 1 }} cameraPosition={START} />;
if (Platform.OS === 'android') return <GoogleMaps.View style={{ flex: 1 }} cameraPosition={START} />;
return <Text>Maps are only available on Android and iOS.</Text>;
}
最后一个分支用于处理 Web 及其他平台,这些平台上两个组件都不存在。
基于同一数据数组添加标记
AppleMaps.View 和 GoogleMaps.View 都接收 markers 数组,且两种标记类型都支持 id、title 和 coordinates。这意味着一个映射函数即可同时为两个平台提供数据。对于平台专属字段,例如 Apple 的 tintColor 或 Google 的 snippet,可通过展开运算符将其合并到共享标记上:
type Place = { id: string; title: string; latitude: number; longitude: number };
export const PLACES: Place[] = [
{ id: 'office', title: 'Office', latitude: 51.5154, longitude: -0.141 },
{ id: 'cafe', title: 'Cafe', latitude: 51.5113, longitude: -0.1198 },
];
export const toMarker = (p: Place) => ({
id: p.id,
title: p.title,
coordinates: { latitude: p.latitude, longitude: p.longitude },
});
// iOS: markers={PLACES.map((p) => ({ ...toMarker(p), tintColor: '#e5484d' }))}
// Android: markers={PLACES.map((p) => ({ ...toMarker(p), snippet: 'Open now' }))}
expo-maps 无法将 React 组件渲染为标记。如需自定义图钉,它支持使用 expo-image 的 useImage 加载图片图标。
如何显示用户位置并将地图居中?
在 expo-maps 中显示用户位置需要三个步骤:请求位置权限、在获得授权后显示定位圆点,以及在获取到坐标后移动相机。定位圆点要显示出来,权限必须既在构建时声明,又在运行时请求。expo-maps 提供的 useLocationPermissions hook 会返回当前权限状态以及一个用于请求权限的函数。
| 任务 | AppleMaps.View | GoogleMaps.View |
|---|---|---|
| 定位圆点 | properties.isMyLocationEnabled | properties.isMyLocationEnabled 加 userLocation |
| 跟随用户 | 调用 setCameraPosition | userLocation.followUserLocation |
| 动画时长 | 不支持 | duration(毫秒) |
请仅在获得授权后再启用定位圆点。一个已报告的 Android 问题显示,在未获得权限的情况下开启 isMyLocationEnabled 会导致 Android 应用崩溃,而 iOS 则会直接忽略该设置。相关修复已于 2026 年 11 月 4 日合并到 Expo 的主分支,但较早版本的 expo-maps 并不包含此修复,而基于权限状态控制定位圆点的做法适用于所有版本。该 issue 还指出,配置插件的 requestLocationPermission 选项只会在构建时声明权限,而不会在运行时发起任何请求。
在 expo-maps 中,cameraPosition prop 的文档定义是地图的初始相机位置,因此通过修改 state 来改变它并不是官方文档推荐的移动相机方式。请改为通过 ref 调用 setCameraPosition。在 iOS 上不支持设置动画时长,且返回的 Promise 会在相机更新被调度后即 resolve,而不是在动画完成时。
import { useEffect, useRef, useState, type ComponentRef } from 'react';
import { Platform, Text, View } from 'react-native';
import { AppleMaps, GoogleMaps, useLocationPermissions } from 'expo-maps';
import * as Location from 'expo-location';
import { PLACES, toMarker } from './places';
const START = { coordinates: { latitude: 51.5074, longitude: -0.1278 }, zoom: 12 };
type Coords = { latitude: number; longitude: number };
export function PlacesMap({ onSelect }: { onSelect: (id: string) => void }) {
const appleRef = useRef<ComponentRef<typeof AppleMaps.View>>(null);
const [permission, requestPermission] = useLocationPermissions();
const [me, setMe] = useState<Coords | null>(null);
const granted = !!permission?.granted;
useEffect(() => {
if (permission && !permission.granted && permission.canAskAgain) requestPermission();
}, [permission]);
useEffect(() => {
if (!granted) return;
Location.getCurrentPositionAsync().then(({ coords }) => {
const here = { latitude: coords.latitude, longitude: coords.longitude };
setMe(here);
appleRef.current?.setCameraPosition({ coordinates: here, zoom: 14 }); // iOS only; no duration
});
}, [granted]);
const handleMarker = (m: { id?: string }) => m.id && onSelect(m.id);
const denied = permission && !permission.granted && !permission.canAskAgain;
const map =
Platform.OS === 'ios' ? (
<AppleMaps.View
ref={appleRef}
style={{ flex: 1 }}
cameraPosition={START}
markers={PLACES.map((p) => ({ ...toMarker(p), tintColor: '#e5484d' }))}
properties={{ isMyLocationEnabled: granted }}
onMarkerClick={handleMarker} // iOS 18+
/>
) : Platform.OS === 'android' ? (
<GoogleMaps.View
style={{ flex: 1 }}
cameraPosition={START}
markers={PLACES.map(toMarker)}
properties={{ isMyLocationEnabled: granted }}
userLocation={me ? { coordinates: me, followUserLocation: true } : undefined}
onMarkerClick={handleMarker}
/>
) : (
<Text>Maps are only available on Android and iOS.</Text>
);
return (
<View style={{ flex: 1 }}>
{map}
{denied && <Text>Location is off. Enable it in Settings to see where you are.</Text>}
</View>
);
}
坐标由 Location.getCurrentPositionAsync 提供。在 Android 上,followUserLocation 会让相机始终跟随用户,因此代码只在 iOS 上调用 setCameraPosition。如果权限被永久拒绝,地图将停留在 START 位置,并在下方显示一条不阻断操作的提示信息。
使用 onMarkerClick 响应标记点击
要在 expo-maps 中处理标记点击,请向 AppleMaps.View 或 GoogleMaps.View 传入 onMarkerClick。该回调会接收被点击的标记,因此你可以读取其 id 并在数据中查找对应的记录。在 Android 上,它适用于所有受支持的版本。在 iOS 上,Expo 文档将其标注为 iOS 18.0+,同样的限制也适用于其他点击回调,以及通过 selectMarker 和 selectAnnotation 进行的编程式选中。
在 iOS 17 设备上,地图仍可正常渲染,但点击标记不会在 JavaScript 中触发任何响应。如果你的 UI 必须依赖点击交互,可通过 expo-build-properties 将 ios.deploymentTarget 设置为 18.0。否则,可在地图下方添加一个列表来驱动相同的选中状态,让 iOS 17 用户也能访问每个地点。
总结
expo-maps 能以原生组件满足常见的地图页面需求:iOS 上使用 Apple 地图,Android 上使用 Google 地图,共享同一个数据数组,只需一小段 Platform.OS 分支判断。下一步,请使用你的 Android 密钥重新构建,并分别在真实的 iOS 17 和 iOS 18 设备上进行测试,点击和权限方面的差异正是在这些设备上显现出来的。应用上线后,React Native 会话回放可以帮你发现日志中看不到的问题,例如用户来回拖动地图寻找图钉,或直接关闭了位置权限弹窗。观察这些会话,你就能判断地图流程对真实用户是否行之有效。
常见问题
为什么 Google 地图在开发环境中正常,但在 Play 商店版本中却是一片空白?
这通常是因为 API 密钥被限制到了错误的 SHA-1 指纹。启用 Play 应用签名后,Google 会对发布版本重新签名,因此用户安装的应用使用的是 Google 的应用签名证书,而不是你的上传密钥或调试密钥。请在 Play 管理中心的“应用完整性”页面复制应用签名 SHA-1,并将其添加到该密钥的 Android 应用限制中。同时请保留密钥上的开发环境指纹。
expo-maps 能否绘制路线、区域或半径圆?
可以。AppleMaps.View 和 GoogleMaps.View 都支持 polylines、polygons 和 circles 这三个 props。每个 prop 接收一个由坐标构成的图形数组,圆形则需要提供圆心和以米为单位的半径。expo-maps 只负责绘制图形,不负责计算路线。如需驾车或步行路径,请从路线规划服务获取路线几何数据,并将解码后的坐标作为 polyline 传入。
如何将 expo-maps 切换为卫星视图?
在 properties prop 中设置 mapType。在 AppleMaps.View 上,使用 AppleMapsMapType 枚举:STANDARD、IMAGERY(仅卫星图)或 HYBRID(卫星图叠加道路和标注)。在 GoogleMaps.View 上,使用 GoogleMapsMapType:NORMAL、SATELLITE、HYBRID 或 TERRAIN。由于两个平台的取值名称不同,共享的封装组件应将统一的设置(例如 'satellite')在 iOS 上映射为 IMAGERY,在 Android 上映射为 SATELLITE。
通过 expo-maps 获得的位置权限是否同样适用于 expo-location?
是的。Android 和 iOS 是将位置权限授予整个应用,而不是授予某个单独的库。一旦用户在 expo-maps 的 useLocationPermissions hook 弹出的前台权限提示中同意授权,expo-location 也能获得相同的权限,因此 getCurrentPositionAsync 运行时不会再次弹出提示。后台定位在两个平台上都是单独的授权,需要通过 expo-location 另行请求。
Gain Debugging Superpowers
Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers.
Star on GitHub12k