uni-app App端离线地图包需通过原生SDK下载解压注册，不可用uni.downloadFile直接保存；Android推荐amap-offline-map插件，iOS需手动集成并指定NSCachesDirectory路径；须处理断点续传、状态同步与权限校验。
uni-app App端离线地图包怎么下载到本地？
离线地图包不能靠 uni.downloadFile 直接存成“可用地图文件”，高德/百度/腾讯的 SDK 对离线包有特定目录结构和校验机制，必须走原生层触发下载 + 解压 + 注册流程。
uni-app 本身不提供地图离线能力封装，得靠原生插件或自定义基座调用原生 SDK。HBuilderX 2.8+ 的「自定义调试基座」支持高德离线地图，但仅限 Android；iOS 需额外配置证书和权限，且苹果审核对后台下载地图包较敏感。
- Android 端推荐用
amap-offline-map插件（基于高德 4.x SDK），它会自动把下载的.dat文件解压到/sdcard/amap_offline/并调用AMapManager.getInstance().addOfflineMap() - iOS 端需手动集成高德 SDK，并在
AppDelegate.m中注册离线地图路径，路径必须是NSCachesDirectory下的子目录，不能写 Documents - 下载前务必检查存储权限（
android.permission.WRITE_EXTERNAL_STORAGE或 iOS 的NSLocationWhenInUseUsageDescription），否则静默失败
为什么 uni.downloadFile 下载的地图包打不开？
因为离线地图不是普通 ZIP 或 DAT 文件——它是 SDK 内部格式，依赖配套的 mapindex.dat、citylist.dat 和版本签名。直接用前端 API 下载后，没调用 SDK 的 addOfflineMap 或 updateOfflineMap，SDK 根本识别不了。
常见错误现象：AMapOfflineMapManager.getOfflineMapList() 返回空数组，或地图缩放时提示“无离线数据”。
- 别把下载 URL 指向官网公开的
amap_offline.zip，那是给桌面端用的；App 必须用 SDK 提供的AMapOfflineMapManager.downloadCity方法触发下载 - 不要手动移动或重命名下载后的文件夹，高德 SDK 会校验
offline_map_version和 CRC32 - 模拟器上无法使用离线地图（高德 SDK 明确禁用），必须真机调试
如何在 uni-app 里调用原生离线地图接口？
不能用 uni. 前缀方法，得通过 uni.requireNativePlugin 加载原生模块，或用 uni.postMessage 向原生层发指令（需提前在 manifest.json 里配置原生插件）。
以 Android 高德插件为例，典型调用链是：js 调用 native.downloadCity('北京') → 原生层执行 AMapOfflineMapManager.downloadCity() → 下载完成回调通知 JS 层。
- 插件 JS 接口名通常类似
offlineMap.downloadCity，不是downloadFile - 城市 code 必须用高德官方编码（如北京是
110000），不能传中文名或拼音 - 监听进度要用插件提供的
onProgress回调，不是onDownloadProgress - 失败回调里注意区分网络错误（
ERR_NETWORK）和 SDK 错误（OFFLINE_MAP_DOWNLOAD_FAIL）
离线地图包体积大，用户中途退出怎么办？
高德单个城市离线包普遍 200–800MB，下载中断后不会自动续传，SDK 默认删除残缺文件。必须自己实现断点记录 + 恢复逻辑，且 iOS 上因沙盒限制更难处理。
真实场景中，用户切后台、锁屏、系统杀进程都会导致下载中断，这时候不能只依赖 SDK 自带状态。
- 每次开始下载前，先查本地是否已有部分文件（比如存在
beijing_110000_v5.6.0.dat但大小不足），再决定是 resume 还是 restart - 把下载状态存进
uni.setStorageSync，key 用城市 code + 版本号组合，避免多城市并发冲突 - Android 上建议在
onPause时暂停下载，在onResume时恢复；iOS 则需监听UIApplicationDidEnterBackgroundNotification - 别让用户等完整个包再提示“下载完成”——下载完只是第一步，还要等 SDK 解压并 build index，这个过程可能卡 10–30 秒，期间
getOfflineMapList仍返回空
离线地图最麻烦的不是下载动作本身，而是状态同步：JS 层看到“100%”，原生层可能还在解压索引，而用户已经点了“使用离线地图”，结果白屏。这个间隙期必须加 loading 锁定操作，不能只信下载回调。
