关键词：
react native 高德地图、expo 高德地图、rn amap、react native 导航、离线地图
在中国大陆做 React Native 地图业务，真正难点通常不是“地图能不能显示”，而是：
- 工程接入是否稳定（Expo / 原生配置）
- 能力是否完整（定位、搜索、导航、离线）
- 初始化和隐私流程是否不踩坑
- 能否长期维护（新架构、文档、错误排查）
这篇文章给一套可直接落地的工程方案：expo-gaode-map 生态。
一、适用场景
如果你在做以下业务，这套方案很适合：
- 网约车 / 外卖 / 同城配送
- 轨迹回放 / 电子围栏 / 巡检
- 地址选点 / POI 搜索 / 路径规划
- 需要 Expo 工程效率 + 中国地图场景能力
二、方案对比（工程视角）
| 对比项 | expo-gaode-map | react-native-maps（通用） | 社区老高德库 |
|---|---|---|---|
| 中国地图业务适配 | ✅ 高德能力为核心 | ⚠️ 通用抽象为主，国内 Android 常受 GMS 可用性限制 | ✅ 基础能力 |
| Expo 接入体验 | ✅ Expo Modules + Config Plugin | ⚠️ 常需项目侧补配置 | ⚠️ 适配成本看项目 |
| 地图 + 搜索 + 导航 + Web API | ✅ 同仓协同（四包） | ❌ 常需多库拼装 | ❌ 多为地图层 |
| 新架构支持 | ✅ 新旧架构兼容 | ✅/⚠️ 看官方支持范围 | ⚠️ 视具体库现状 |
| 离线地图 | ✅ 内置能力 | ⚠️ 需额外方案 | ⚠️ 看版本/分支 |
三、包结构怎么选（先选对，再动手）
# 核心：地图 + 定位 + 覆盖物
npm install expo-gaode-map
# 可选：原生搜索
npm install expo-gaode-map-search
# 可选：Web API（纯 JS 搜索/地理编码/路径）
npm install expo-gaode-map-web-api
# 可选：导航（已包含地图能力）
npm install expo-gaode-map-navigation
注意：expo-gaode-map 和 expo-gaode-map-navigation 二选一，不要同时装。
四、最关键规则：初始化只有两条路径（必须明确）
路径 A：使用 Config Plugin（推荐）
你在 app.json 配了 androidKey/iosKey 后，原生 SDK 默认自动初始化。
地图/定位场景通常不需要再手动 initSDK()。
只有在使用 expo-gaode-map-web-api 时，再调用：
ExpoGaodeMapModule.initSDK({ webKey: 'your-web-api-key' });
路径 B：不使用 Config Plugin（必须手动）
你必须在业务入口调用：
ExpoGaodeMapModule.initSDK({
androidKey: 'your-android-api-key',
iosKey: 'your-ios-api-key',
});
否则地图/定位/搜索/导航能力不可用。
如果还用 Web API，再额外加 webKey。
五、接入步骤（10 分钟）
1) 配置 Config Plugin（推荐）
app.json：
{
"expo": {
"plugins": [
[
"expo-gaode-map",
{
"androidKey": "your-android-key",
"iosKey": "your-ios-key"
}
]
]
}
}
重建：
npx expo prebuild --clean
npx expo run:android
npx expo run:ios
2) 首次安装先做隐私同意（必须）
import { ExpoGaodeMapModule } from 'expo-gaode-map';
const privacyStatus = ExpoGaodeMapModule.getPrivacyStatus();
if (!privacyStatus.isReady) {
ExpoGaodeMapModule.setPrivacyConfig({
hasShow: true,
hasContainsPrivacy: true,
hasAgree: true,
privacyVersion: '2026-04-15'
});
}
3) 地图最小渲染
import { View } from 'react-native';
import { MapView } from 'expo-gaode-map';
export default function MapScreen() {
return (
<View style={{ flex: 1 }}>
<MapView
style={{ flex: 1 }}
initialCameraPosition={{
target: { latitude: 39.90923, longitude: 116.397428 },
zoom: 12
}}
myLocationEnabled
/>
</View>
);
}
六、三种常见代码模板（可直接复用）
模板 A：Config Plugin + 仅地图定位（无需 initSDK）
// 只做隐私同步即可
if (!ExpoGaodeMapModule.getPrivacyStatus().isReady) {
ExpoGaodeMapModule.setPrivacyConfig({
hasShow: true, hasContainsPrivacy: true, hasAgree: true
});
}
模板 B：Config Plugin + Web API（只传 webKey）
if (!ExpoGaodeMapModule.getPrivacyStatus().isReady) {
ExpoGaodeMapModule.setPrivacyConfig({
hasShow: true, hasContainsPrivacy: true, hasAgree: true
});
}
ExpoGaodeMapModule.initSDK({
webKey: 'your-web-api-key'
});
模板 C：不使用 Config Plugin（必须传原生 key）
if (!ExpoGaodeMapModule.getPrivacyStatus().isReady) {
ExpoGaodeMapModule.setPrivacyConfig({
hasShow: true, hasContainsPrivacy: true, hasAgree: true
});
}
ExpoGaodeMapModule.initSDK({
androidKey: 'your-android-api-key',
iosKey: 'your-ios-api-key',
webKey: 'your-web-api-key' // 可选
});
七、常见问题与排查
| 问题 | 高概率原因 | 处理建议 |
|---|---|---|
| 地图黑屏/不显示 | 模拟器环境限制、Key 配置错误 | 优先真机；核对 key 与包名/Bundle ID；prebuild --clean 重建 |
PRIVACY_NOT_AGREED | 首次安装未完成隐私同意 | 先走隐私弹窗，再调用地图能力 |
| 定位拿不到 | 权限没开 / 被系统拒绝 | 检查并请求权限，失败后引导到系统设置 |
| Web API 报 key 相关错误 | 未下发 webKey | 调用 initSDK({ webKey }) 或在 Web API 构造时显式传 key |
八、上线前检查清单（建议逐条打勾）
- 已明确采用哪条初始化路径（A 或 B）
- 首次安装隐私流程可完整走通
- 真机验证 Android/iOS 均通过
- 定位权限拒绝场景有兜底 UI
- 业务关键链路有错误日志（初始化、定位、搜索、路线）
- 没有同时安装
expo-gaode-map与expo-gaode-map-navigation
九、结论
这套方案最大的价值不只是“显示地图”，而是把中国地图业务需要的能力一次性工程化落地：
地图 + 搜索 + 导航 + 离线 + 合规 + 可维护性。
expo-gaode-map（地图/定位/覆盖物/离线）expo-gaode-map-search（POI/周边/地理编码）expo-gaode-map-navigation（路径规划+导航）expo-gaode-map-web-api（纯 JS 服务层）
不是只解决“显示地图”，而是一次把业务链路搭完整。
