Flutter集成Mapbox离线模式下地图不加载显示黑屏问题

按以下优先级逐一排查，所有问题修正后即可正常加载离线资源：

基础逻辑校验 #

• 优先检查区域匹配问题（90%同类问题根因）：你当前地图初始化的中心点坐标为LatLng(14.508, 46.048)（红海附近区域），但离线包下载的bounds范围是LatLng(-12.824277, -38.371157)到LatLng(-12.835331, -38.382491)（巴西东部区域），两个位置完全不重叠，断网状态下当前视角没有对应离线瓦片，必然显示黑屏。测试时需要将相机移动到你实际下载了离线包的坐标范围内验证。
• 校验token逻辑：断网时不要将accessToken设置为"notoken"，Mapbox SDK即使加载本地离线资源，也会校验token的合法性，假token会直接阻断地图渲染流程，全程使用你在Mapbox后台申请的有效公钥即可。
• 校验style一致性：地图初始化传入的styleString参数，必须和下载离线包时OfflineRegionDefinition里配置的mapStyleUrl完全一致。你当前下载用的是mapbox://styles/mapbox/streets-v11，初始化时不能传入其他在线style地址，否则SDK会优先尝试拉取在线style资源，断网拉取失败就会黑屏。
• 校验资源声明：确认pubspec.yaml的assets节点下已经加入assets/cache.db路径，未声明的话该文件不会被打进应用安装包，installOfflineMapTiles方法读不到本地数据库就会加载失败。
• 修正metadata配置：下载离线包时传入的metadata只需要保留和当前style匹配的mapbox-streets矢量数据源即可，多余的mapbox-satellite栅格数据源配置会导致SDK离线资源校验失败，无法匹配已下载的瓦片包。

安卓端配置修正 #

• 补全存储权限：你当前的权限列表缺少存储相关权限，安卓13及以上版本需要在AndroidManifest.xml中添加READ_MEDIA_IMAGES权限，安卓12及以下版本需要添加READ_EXTERNAL_STORAGE、WRITE_EXTERNAL_STORAGE权限，没有权限的话SDK无法读取本地数据库文件。
• 校验meta-data配置格式，确保token配置写法正确：

<meta-data
    android:name="com.mapbox.token"
    android:value="你的有效Mapbox公钥" />

不要遗漏android:value字段，否则SDK读取不到token会直接初始化失败。

下载与加载逻辑修正 #

• 校验离线区域坐标顺序：构造LatLngBounds时严格遵循「纬度在前、经度在后」的规则，东北、西南边界坐标不要写反，否则下载的离线区域会完全偏离预期。
• 增加下载完成校验：离线下载成功回调中，调用getListOfRegions()方法确认离线区域已经写入本地持久化数据库，避免下载流程返回成功但数据实际未落盘，断网时读不到资源。
• 修正离线瓦片加载逻辑：installOfflineMapTiles方法只需要在地图组件初始化前调用1次即可，不要在网络状态变化时重复调用，重复加载会导致本地数据库连接锁死，瓦片无法正常渲染。
• 调整onMapCreated里的相机移动逻辑：如果获取到的当前位置不在你下载的离线包范围内，断网状态下相机动画移动到无离线瓦片的位置，同样会显示黑屏。

验证流程 #

1. 联网状态下启动应用，手动移动地图到你下载离线包的巴西区域坐标范围，确认该区域瓦片可以正常加载
2. 关闭应用、杀掉进程，断开设备网络后冷启动应用，移动地图到已下载的离线区域验证加载状态
3. 不要停留在默认初始化的红海区域测试，该区域你没有下载对应离线瓦片，必然无法显示地图

内容的提问来源于stack exchange，提问作者Karan Mehta