MapLibre GL Native Android SDK 怎么集成
MapLibre GL Native Android SDK 集成方式很直接:在模块级 Gradle 中通过 Maven Central 引入 org.maplibre.gl:android-sdk,布局 XML 放入 MapView,Activity 里必须先调用 MapLibre.getInstance,再 getMapAsync 设置样式。截至 2026 年 10 月,稳定版为 android-v13.7.1,自 13.0.0 起默认走 Vulkan 后端,minSdk 要求 23(Android 6.0+)。按下面步骤做完并正确转发生命周期,即可在真机或模拟器上看到矢量底图。

怎么添加 Gradle 依赖
SDK 由 Maven Central 分发,新项目一般已在 settings.gradle 里包含 mavenCentral();旧项目需在项目级 repositories 中确认有该仓库。模块级依赖推荐默认 Vulkan 产物,Kotlin DSL 与 Groovy 写法等价。
- 确认 repositories 含 mavenCentral()。
- 在 app 模块的 build.gradle 或 build.gradle.kts 添加依赖,版本以发布页为准,例如稳定版 13.7.1。
- Sync Project,等待 AAR 与 native 库拉取完成。
- 确认 minSdk 不低于 23;若目标设备需兼容更广,可改用 OpenGL ES 产物(见下一节)。
| Artifact | 说明 | 适用场景 |
|---|---|---|
| org.maplibre.gl:android-sdk | 默认,Vulkan | 正式项目首选 |
| org.maplibre.gl:android-sdk-opengl | OpenGL ES | 旧机、部分模拟器、Vulkan 不稳定时 |
| org.maplibre.gl:android-sdk-vulkan | 仅 Vulkan | 明确只要 Vulkan |
| org.maplibre.gl:android-sdk-vulkan-opengl | 运行时可二选一,体积约大 10MB | 需要按设备自适应 |
带实验性 C Plugin API 的变体需加 -with-plugin-api 后缀;还有 -debug 变体。无需手动下载 zip,Gradle 解析即可。版本可在 android-v13.7.1 发布说明 与 Releases 列表核对。
Groovy 写法示例:implementation ‘org.maplibre.gl:android-sdk:13.7.1’
Kotlin DSL 写法示例:implementation(“org.maplibre.gl:android-sdk:13.7.1”)
布局与 Activity 初始化怎么写
核心顺序不能反:先调用 MapLibre.getInstance(context)(或带 apiKey、WellKnownTileServer、RenderingEngine.Type 的重载),再 inflate 或创建 MapView。无 key 时可用官方演示样式 URL。
- 布局 XML 增加 MapView,宽高通常 match_parent,控件类名为 org.maplibre.android.maps.MapView,并设置 android:id、layout_width、layout_height。
- onCreate 中:先 MapLibre.getInstance(this),再 setContentView 或绑定视图。
- 调用 mapView.onCreate(savedInstanceState),然后 mapView.getMapAsync,在回调里 map.setStyle,样式可用 https://demotiles.maplibre.org/style.json,并在样式加载完成后设置相机、图层等。
- 把以下生命周期完整转发给 MapView:onStart、onResume、onPause、onStop、onSaveInstanceState、onLowMemory、onDestroy,以及官方要求的 onCreate。漏转会导致黑屏、状态错乱或内存异常。
- getInstance 用于管理上下文、可选 API Key 与瓦片服务类型;样式加载失败时优先查 URL、网络与 key 是否正确附加到 TileJSON 或 tiles。
- 位置相关(LocationComponent)需额外权限;默认可能带上 Google Play Location Services,若不需要可按文档排除以去掉专有依赖。
- 消费者 ProGuard 规则已内置;若自行压缩仍崩溃,可对 org.maplibre.android 包做 keep。

渲染后端怎么选,验收标准是什么
自 13.0.0 起,默认 android-sdk 使用 Vulkan。MapLibre.getInstance 可传入 RenderingEngine.Type.VULKAN,或依赖自动检测:API 24 及以上且设备报告 Vulkan 1.0 硬件支持时选 Vulkan,否则 OpenGL ES。单后端 artifact 若请求不支持的后端会抛 UnsupportedOperationException;后端在进程内选定后不能热切换,需重启进程。可用 RenderingEngine.getCurrentType() 查询当前类型。
- 真机优先:Vulkan 在部分模拟器(例如高 API 模拟器)上可能出现 vk::createInstanceUnique 一类初始化失败,此时改用 android-sdk-opengl、较低 API 模拟器或真机。
- 验收标准:冷启动后演示样式完整出图;旋转或后台再回前台地图不丢状态;缩放手势流畅;Logcat 无 UnsatisfiedLinkError、无未捕获的 UnsupportedOperationException。
- Globe 等预发布(如带 globe 后缀的 nightly)支持 style 中 projection type 为 globe,属非稳定通道,正式集成请用稳定版。
平台说明与示例入口见 maplibre-native Android README;更细的 API 与 examples 以官网文档为准。
常见报错与怎么处理
- 未先 getInstance 就创建 MapView:初始化失败或行为异常。固定写成「getInstance → setContentView → mapView.onCreate → getMapAsync」。
- UnsatisfiedLinkError:native 库未正确加载。优先升级到较新的 13.x;检查 ABI 是否被错误裁剪;混淆时保留 SDK 包名。
- Vulkan 模拟器崩溃或空闲后瓦片卡住:换 OpenGL ES artifact 或真机;升级到含相关修复的稳定版(13.7.1 含多项 Vulkan 与样式崩溃修复)。
- 空白地图:检查样式 URL、网络,以及 key 是否需通过 ResourceTransformCallback 手动挂到直接写 tiles 数组的源上。
- 手势滞后、地图卡住:部分旧 GPU 驱动(如部分 Adreno)有已知问题,可试 OpenGL ES 后端或升级 SDK。
常见问题
最新稳定版是多少,怎么查?
截至 2026 年 10 月 15 日发布的稳定版为 android-v13.7.1;之后请以 GitHub android 标签 Releases 或 Maven Central 上 org.maplibre.gl:android-sdk 的版本列表为准,预发布(如 globe 变体)不要当生产依赖。
必须申请 API Key 吗?
不一定。本地演示可用 demotiles.maplibre.org 的公开样式;接商业或自有瓦片服务时再在 getInstance 重载里传入 apiKey 与对应 WellKnownTileServer,或以官网为准配置。
Compose 项目能用吗?
官方核心是 View 与 MapView;社区有基于 MapLibre 的 Compose 封装项目可选用,但依赖与生命周期仍建议先按原生 MapView 流程理解清楚再封装。
minSdk 和 Vulkan 设备要求分别是什么?
SDK minSdk 为 23;Vulkan 路径通常需要 API 24 及以上且设备具备 FEATURE_VULKAN_HARDWARE_VERSION。覆盖更老或驱动不稳的设备时,直接依赖 android-sdk-opengl 更稳妥。
集成 maplibre-gl-native 的关键是:Maven 引入正确 artifact、先 getInstance 再 MapView、完整转发生命周期,并按设备能力选择 Vulkan 或 OpenGL ES。建议生产环境锁定稳定版 13.7.1(或当时最新稳定版),先用演示样式跑通验收,再替换为自己的 style URL 与瓦片鉴权。