离线地图包必须由原生sdk触发下载、解压、注册三步流程，不可用uni.downloadfile直接保存；android需用amap-offline-map插件解压至/sdcard/amap_offline/，ios须指定nscachesdirectory路径；全端兼容推荐静态瓦片方案。
离线地图包不能用 uni.downloadFile 直接保存
高德、百度、腾讯等 SDK 的离线地图不是普通 ZIP 或 DAT 文件，而是带校验签名、目录结构和索引文件（如 mapindex.dat、citylist.dat）的专用格式。直接用 uni.downloadFile 下载后存到任意路径，SDK 根本识别不了——调用 AMapOfflineMapManager.getOfflineMapList() 会返回空数组，缩放地图时提示“无离线数据”。
根本原因在于：离线包必须由原生 SDK 触发下载 + 解压 + 注册三步流程，且路径需符合平台规范：
- Android 推荐用
amap-offline-map插件（基于高德 4.x），它自动把.dat文件解压到/sdcard/amap_offline/并调用addOfflineMap() - iOS 必须手动集成高德 SDK，并在
AppDelegate.m中指定路径为NSCachesDirectory下的子目录（不能是Documents），否则审核可能被拒 - 模拟器上高德 SDK 明确禁用离线地图，必须真机调试
怎么在 JS 层调用原生离线下载逻辑
不能用 uni. 前缀方法，得走原生插件桥接。典型链路是：JS 调用 native.downloadCity('北京') → 原生层执行 AMapOfflineMapManager.downloadCity() → SDK 完成下载、解压、注册。
实操要点：
- 通过
uni.requireNativePlugin('amap-offline-map')加载插件（Android）；iOS 需提前在manifest.json中声明自定义原生模块 - 下载前务必检查权限：
android.permission.WRITE_EXTERNAL_STORAGE（Android）或NSLocationWhenInUseUsageDescription（iOS），否则静默失败 - 不要手动移动或重命名下载后的文件夹——SDK 会校验
offline_map_version和 CRC32 值，路径错或文件损毁即失效 - 别用官网公开的
amap_offline.zip（那是桌面端用的），App 必须用 SDK 提供的downloadCity方法触发
离线瓦片方案更适合全端兼容场景
如果你要支持 H5、小程序、App 全端，且能接受预置区域瓦片（非动态城市级下载），用 OpenLayers 或 Leaflet + 静态瓦片是更可控的选择。
关键操作：
- 瓦片按
{z}/{x}/{y}.jpg结构组织，整个tiles/文件夹放在项目static/目录下 - 用
web-view加载本地 HTML（如/static/offline-map.html），HTML 内用 Leaflet 初始化并指向./tiles/{z}/{x}/{y}.jpg - 注意：OpenLayers 推荐用 4.6.5 版本，新版有兼容问题；高德瓦片必须用高德源下载，其他地图源在移动端常报错或不显示
- H5 和小程序可直接读取
static/路径，App 端需确认打包后路径是否仍可被web-view访问（部分自定义基座会限制）
断点续传、状态同步与兜底必须自己做
原生插件一般不暴露完整下载进度或失败原因，容易卡在“正在下载”或无声失败。真正可用的方案要补足这三层：
- 用
plus.networkinfo.getCurrentType()和uni.onNetworkStatusChange主动监听网络变化，避免用户切到飞行模式后还在等 - 下载中写入临时标记文件（如
uni.getFileSystemManager().writeFile({filePath: '_doc/city_beijing_downloading'})），失败时可清空重试 - 加载地图前先查
getOfflineMapList()，若为空则 fallback 到静态瓦片页或占位图，而不是白屏或报错弹窗 - 权限被拒、存储空间不足、SD 卡不可用——这些情况原生层往往只返回泛化错误码，需结合日志 + 用户反馈定位
最易被忽略的是：离线地图不是“下载完就自动生效”，它依赖 SDK 在后台完成解压和索引重建，这个过程可能耗时数秒到数十秒，期间调用 getOfflineMapList() 仍可能为空。需要加轮询或监听 SDK 的回调事件（如 Android 的 onDownload），不能只靠一次判断。
