App端必须使用nvue页面渲染高德地图，因<map>组件依赖原生SDK且仅支持nvue；需手动集成SDK、严格匹配Key配置、补全系统权限，并避免误用amap-wx.js等小程序专用代码。
App端必须用 nvue 页面才能渲染高德地图
uni-app 的 <map> 组件在 app 端（ios/android）仅支持 nvue 渲染模式，vue 页面下该组件会降级为白屏或报错“map is not supported in vue”。这不是 bug，是 uni-app 原生地图控件的底层限制——它依赖原生 sdk 的视图容器，而 vue 页面走的是 webview 渲染链路，无法挂载原生地图视图。
实操建议：
- 地图页必须新建为
pages/map/index.nvue，不能用.vue后缀 - 即使主流程是 Vue 页面，跳转到地图页也需用
uni.navigateTo({ url: '/pages/map/index' })，且目标页后缀隐含为.nvue - 不要在
.vue页面里尝试用cover-view叠加模拟地图，性能差、手势不响应、缩放卡顿，得不偿失
离线打包时高德 SDK 必须手动集成，云打包无效
uni-app 默认云打包不包含高德地图原生能力。你看到的 <map> 标签只是壳，没集成 SDK 就等于没装发动机——页面能编译过，但运行时地图区域空白，控制台无报错，只有定位失败或初始化超时这类间接提示。
实操建议：
- Android：下载高德地图 SDK（
AMap_3DMap_Vx.x.x_2025xx.xx.jar及对应jniLibs），放入nativeplugins/amap-map/libs/，并在app/build.gradle中添加implementation fileTree(dir: 'libs', include: ['*.jar']) - iOS：将
MAMapKit.framework拖入 Xcode 工程，勾选 “Copy items if needed”，并确认已添加CoreLocation、SystemConfiguration等系统依赖库 - Key 配置必须和打包环境严格一致：Android 的
package name和 SHA1、iOS 的Bundle ID，必须与高德平台申请 Key 时填写的完全相同，差一个字符都会鉴权失败
manifest.json 权限配置漏一项，地图就拿不到定位
高德地图在 App 端依赖系统级定位权限才能初始化成功。很多开发者只加了 ACCESS_FINE_LOCATION，却忽略了后台定位、网络状态等辅助权限，结果地图能显示，但定位按钮灰掉、uni.getLocation 返回空坐标或 error code 1002（定位失败）。
实操建议（Android）：
- 在
manifest.json → App 模块 → 权限配置中勾选全部以下权限：ACCESS_COARSE_LOCATION、ACCESS_FINE_LOCATION、ACCESS_BACKGROUND_LOCATION、ACCESS_NETWORK_STATE、ACCESS_WIFI_STATE、INTERNET - iOS 需额外在
ios/Info.plist补充两个 key：NSLocationWhenInUseUsageDescription和NSLocationAlwaysAndWhenInUseUsageDescription，值不能为空字符串 - 真机测试前务必手动进手机设置开启应用的定位权限，模拟器默认关闭且无法弹窗请求
amap-wx.js 不是给 App 用的，别往 common 里瞎放
网上很多教程说“把 amap-wx.js 放到 common/ 目录下就能用高德 API”，这是典型的小程序思维误植到 App 端。这个 JS 文件是微信小程序专用 SDK，封装的是 wx.request 调用高德 Web 服务，和 App 端原生地图 SDK 完全无关。放在 App 项目里不仅没用，还可能因全局变量污染导致其他模块异常。
实操建议：
- App 端获取逆地理编码、POI 搜索等数据，应调用原生插件封装的接口，或自己用
uni.request直接请求高德 Web API（需用 Web 服务 Key） - 如果用了第三方封装插件（如
uni-amap），请确认其是否同时支持 App 平台；多数纯 JS 插件只适配小程序 -
amap-wx.js只保留在mp-weixin条件编译块内，例如：#ifdef MP-WEIXIN...import amap from '@/static/lib/amap-wx.js'...#endif
最常被忽略的一点：鸿蒙（HarmonyOS）目前仍不支持 uni-app 官方 <map> 组件，必须用 UTS 原生插件方式接入高德 SDK，否则地图直接不显示。这点在做多端发布时，很容易在测试阶段才暴露出来。
