高德地图 Key 申请和配置指南高德地图 Key 申请和配置指南目录 Key 类型说明申请流程代码配置当前项目配

高德地图 Key 申请和配置指南

平台地址

高德开放平台: console.amap.com/

Key 类型说明

高德地图提供多种类型的 Key，用于不同的场景：

1. SDK Key（原生 App）

用途: 用于 Android/iOS 原生 App 的地图 SDK
功能: 地图组件、定位 SDK、地图显示等
配置位置: manifest.json

2. Web 服务 Key

用途: 用于调用 HTTP API（逆地理编码、地理编码、搜索等）
功能: 地址解析、地理编码、POI 搜索等
配置位置: 代码中直接使用

3. Web 端 Key

用途: 用于 H5 网页端地图服务
功能: H5 地图显示、定位等
配置位置: H5 页面配置

申请流程

步骤一：登录高德开放平台

访问：console.amap.com/
使用账号登录（验证码登录或密码登录）

步骤二：创建应用和 Key

2.1 创建 SDK Key（Android/iOS）

进入应用管理
- 点击左侧菜单 应用管理
- 点击 创建新应用
填写应用信息
- 应用名称: 。。。
- 应用类型: 选择 移动应用
添加 Android Key
- 点击 添加 Key
- Key名称: bdsh（或自定义）
- 服务平台: 勾选 Android平台
- PackageName: 自己填
- SHA1: 自己填
- 点击提交
添加 iOS Key
- 点击 添加 Key
- Key名称: bdsh（或自定义）
- 服务平台: 勾选 iOS平台
- Bundle ID: 自己填
- 点击提交

2.2 创建 Web 服务 Key

创建新应用
- 应用管理 → 创建新应用
- 应用名称: 。。-Web服务
- 应用类型: 选择 Web服务
添加 Web 服务 Key
- 点击 添加 Key
- Key名称: web_service_key（自定义）
- 服务平台: 只勾选 Web服务
- IP白名单:
  - 开发环境：可以不设置或设置为 0.0.0.0/0（允许所有 IP）
  - 生产环境：设置服务器 IP
- 点击提交
复制 Key
- 创建成功后，复制生成的 Key

2.3 创建 Web 端 Key（可选）

如果需要 H5 端地图功能：

创建新应用
- 应用管理 → 创建新应用
- 应用名称: 洛。。-Web端
- 应用类型: 选择 **Web端（JS API）`
添加 Web 端 Key
- 点击 添加 Key
- Key名称: web_js_key（自定义）
- 服务平台: 勾选 Web端（JS API）
- 安全密钥: 系统会自动生成，请保存
- 点击提交

代码配置

1. SDK Key 配置（manifest.json）

文件位置：manifest.json

{
  "app-plus": {
    "modules": {
      "Maps": {
        "provider": "amap"
      }
    },
    "distribute": {
      "sdkConfigs": {
        "amap": {
          "android": {
            "key": "申请的key"
          },
          "ios": {
            "key": "申请的key"
          }
        }
      }
    }
  }
}

2. Web 服务 Key 配置（代码中）

在 getAddressByLocation 函数中：

function getAddressByLocation(longitude, latitude) {
  // 使用高德地图 Web 服务 Key（专门用于 HTTP API 调用）
  const regeoKey = '申请的key'
  
  uni.request({
    url: 'https://restapi.amap.com/v3/geocode/regeo',
    method: 'GET',
    data: {
      key: regeoKey,
      location: `${longitude},${latitude}`,
      radius: 1000,
      extensions: 'base'
    },
    // ...
  })
}

3. Android 权限配置（manifest.json）

{
  "app-plus": {
    "distribute": {
      "android": {
        "permissions": [
          "<uses-permission android:name=\"android.permission.ACCESS_COARSE_LOCATION\"/>",
          "<uses-permission android:name=\"android.permission.ACCESS_FINE_LOCATION\"/>",
          "<uses-permission android:name=\"android.permission.ACCESS_LOCATION_EXTRA_COMMANDS\"/>"
        ]
      }
    }
  }
}

4. iOS 权限配置（manifest.json）

{
  "app-plus": {
    "distribute": {
      "ios": {
        "privacyDescription": {
          "NSLocationWhenInUseUsageDescription": "需要使用您的位置信息以提供地图定位服务",
          "NSLocationAlwaysUsageDescription": "需要使用您的位置信息以提供地图定位服务",
          "NSLocationAlwaysAndWhenInUseUsageDescription": "需要使用您的位置信息以提供地图定位服务"
        }
      }
    }
  }
}

常见问题

1. USERKEY_PLAT_NOMATCH 错误

问题: 调用 Web API 时出现平台不匹配错误

原因:

SDK Key 和 Web 服务 Key 不能混用
SDK Key 主要用于原生地图组件，不能用于 HTTP API

解决方案:

创建专门的 Web 服务 Key（推荐）
确保 Web 服务 Key 的平台类型正确设置为 "Web服务"
更新代码中的 regeoKey 为 Web 服务 Key

2. 定位失败：地图提供商未配置

问题: getLocation:fail translate coordinate system faild, map provider not configured

原因: 开发环境未配置地图服务提供商

解决方案:

确保 manifest.json 中配置了 Maps 模块和 provider: "amap"
代码已自动降级到 wgs84 坐标系
正式打包后会自动使用 gcj02 坐标系

3. SHA1 如何获取

使用 HBuilderX（推荐）

HBuilderX → 发行 → 原生 App-云打包
选择 Android 平台
创建/选择证书
自动显示 SHA1 值

4. Key 配置不生效

可能原因:

配置修改后需要等待 5-10 分钟生效
Key 的平台类型配置错误
IP 白名单限制

解决方案:

等待配置生效（5-10 分钟）
检查 Key 的平台类型是否正确
检查 IP 白名单设置
重新打包应用（manifest.json 修改需要重新打包）

5. 定位权限被拒绝

问题: 应用无法获取定位权限

解决方案:

检查 manifest.json 中的权限配置
检查 iOS 的 privacyDescription 配置
引导用户到系统设置中开启定位权限
代码中已添加权限请求逻辑

验证测试

1. SDK Key 验证

打包应用
- HBuilderX → 发行 → 原生 App-云打包
- 选择 Android/iOS 平台
- 使用配置的证书打包
测试地图功能
- 安装打包后的应用
- 测试地图显示是否正常
- 测试定位功能是否正常

2. Web 服务 Key 验证

测试逆地理编码
- 运行应用
- 触发定位功能
- 检查控制台是否有错误
- 确认地址解析正常
检查错误日志
- 打开浏览器/开发者工具控制台
- 查看是否有 USERKEY_PLAT_NOMATCH 错误
- 确认 API 调用成功

3. 完整功能测试

定位功能
- 获取当前位置
- 显示定位地址
- 点击重新定位
地址解析
- 经纬度转换为地址
- 显示完整地址
- 缓存地址信息
错误处理
- 权限被拒绝时的提示
- 网络异常时的降级
- 使用缓存地址

配置检查清单

SDK Key 配置

Web 服务 Key 配置

创建了 Web 服务类型的 Key
代码中使用了 Web 服务 Key
Key 的平台类型正确

权限配置

Android 位置权限已添加
iOS 位置权限说明已配置
权限请求逻辑已实现

测试验证

定位功能正常
地址解析正常
无错误日志
错误处理正常

注意事项

Key 安全
- 不要将 Key 提交到公开代码仓库
- 生产环境建议设置 IP 白名单
- 定期检查 Key 的使用情况
配置生效时间
- 新创建的 Key 立即生效
- 修改配置后需要等待 5-10 分钟
- manifest.json 修改需要重新打包
Key 类型不能混用
- SDK Key 用于原生地图组件
- Web 服务 Key 用于 HTTP API
- 不同类型的 Key 需要分开创建
开发环境 vs 生产环境
- 开发环境可以使用降级方案（wgs84）
- 生产环境需要正确配置所有 Key
- 建议使用不同的 Key 区分环境

如有问题，请参考：

高德开放平台文档：lbs.amap.com/
高德开放平台控制台：console.amap.com/