Android MapBox无法从OBB（APK扩展文件）加载离线地图

我之前也碰到过类似的OBB加载MapBox离线瓦片的坑，咱们一步步拆解问题，找到解决方案：

1. 先排查路径格式问题（最可能的原因） #

你当前的瓦片路径是直接写的绝对路径，但MapBox SDK识别本地文件路径需要加上file://前缀——就像asset://是assets文件夹的专属前缀一样。之前assets加载正常是因为用了正确的协议头，而OBB路径缺少file://，导致SDK把它当成网络请求去处理，自然加载失败。

修改后的配置应该是这样：

"sources": {
  "mapbox": {
    "tiles": [ "file:///mnt/obb/a2d68a13d68baf704a98a82bc8f9d62f/mapparis/{z}/{x}/{y}.pbf" ],
    "type": "vector"
  }
}

注意这里是file:///（三个斜杠），因为后面接的是绝对路径。

2. 避免硬编码OBB路径，用系统API获取正确路径 #

不同设备的OBB挂载路径可能存在差异，硬编码/mnt/obb/xxx很容易出问题。Android提供了专门的API来获取应用的OBB目录，建议在代码里动态生成路径：

// 获取应用的OBB目录
File obbDir = getObbDir();
if (obbDir != null && obbDir.exists()) {
    String tilePath = "file://" + obbDir.getAbsolutePath() + "/mapparis/{z}/{x}/{y}.pbf";
    // 把这个tilePath设置到你的style配置中
}

这样不管设备怎么挂载OBB，都能拿到正确的路径。

3. 确认OBB文件的完整性与权限 #

• 先手动验证OBB里的文件：把OBB解压出来，检查mapparis文件夹的层级结构（z/x/y的目录是否正确），以及瓦片文件是否能正常打开（可以用QGIS这类工具加载测试）。如果解压后文件损坏，那肯定加载失败，需要重新生成或下载OBB。
• 检查应用权限：Android 10及以上版本，即使是应用自己的OBB文件，也需要确保APP拥有READ_EXTERNAL_STORAGE权限（Android 13+对应READ_MEDIA_IMAGES），可以在Manifest里声明并动态申请。

4. 调试小技巧 #

在代码里加个检查，确认瓦片文件是否存在：

File tileFile = new File(getObbDir(), "mapparis/0/0/0.pbf");
Log.d("MapBoxOBB", "Tile 0/0/0 exists: " + tileFile.exists());

如果打印false，说明路径或者OBB文件有问题，先解决这个再看SDK的报错。

内容的提问来源于stack exchange，提问作者Pavel Poley