311 lines
9.0 KiB
Markdown
311 lines
9.0 KiB
Markdown
# 地图 API Key 配置文档
|
||
|
||
> 创建时间：2026-06-04
|
||
> 更新说明：2026-06-04 新建文档，记录各平台地图配置机制及 H5 鉴权失败问题排查
|
||
|
||
---
|
||
|
||
## 一、概述
|
||
|
||
本项目 vr-shopxo-uniapp 支持多端部署（APP、H5、微信小程序等），不同平台使用不同的地图 SDK，对应的 API Key 配置方式也不同。
|
||
|
||
**问题背景**：在 H5 本地预览模式下，打开地图时报错 "鉴权失败，请传入正确的 key"，经排查是腾讯地图 JS SDK 的 Key 配置问题。
|
||
|
||
---
|
||
|
||
## 二、各平台地图配置对比
|
||
|
||
| 平台 | 地图SDK | Key 配置位置 | Key 来源 | 是否需要服务端配置 |
|
||
|------|---------|-------------|----------|------------------|
|
||
| **APP (Android)** | 高德地图原生 SDK | `manifest.json` → `app-plus.distribute.sdkConfigs.maps.amap.appkey_android` | 固定写死 | ❌ 不需要 |
|
||
| **APP (iOS)** | 高德地图原生 SDK | `manifest.json` → `app-plus.distribute.sdkConfigs.maps.amap.appkey_ios` | 固定写死 | ❌ 不需要 |
|
||
| **H5** | 腾讯地图 JS SDK | `manifest.json` → `h5.sdkConfigs.maps.tencent.key` | 固定写死 | ❌ 不需要 |
|
||
| **微信小程序** | 微信内置地图 (`uni.openLocation`) | 无需配置 | 无需 Key | ❌ 不需要 |
|
||
| **微信小程序** (插件模式) | 腾讯位置服务插件 | 服务端 `config.common_tencent_map_ak` | 动态读取 | ✅ 需要 |
|
||
|
||
---
|
||
|
||
## 三、各平台详细配置
|
||
|
||
### 3.1 APP 高德地图配置
|
||
|
||
**配置文件**：`manifest.json`
|
||
|
||
```json
|
||
"app-plus": {
|
||
"distribute": {
|
||
"sdkConfigs": {
|
||
"maps": {
|
||
"amap": {
|
||
"name": "amapu9VF72Gg",
|
||
"appkey_ios": "f55e9099897821681f5c74051e4527bd",
|
||
"appkey_android": "ebe9f1d84f8ceb8b3c4ba6ead2bfa78b"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**说明**：
|
||
- `name`：高德地图应用名称
|
||
- `appkey_android`：Android 平台 Key
|
||
- `appkey_ios`：iOS 平台 Key
|
||
|
||
**申请地址**：[高德开放平台](https://lbs.amap.com/)
|
||
|
||
---
|
||
|
||
### 3.2 H5 腾讯地图配置
|
||
|
||
**配置文件**：`manifest.json`
|
||
|
||
```json
|
||
"h5": {
|
||
"sdkConfigs": {
|
||
"maps": {
|
||
"tencent": {
|
||
"key": "XZHBZ-4OUKA-SMSKV-CXXHB-OKOGQ-FSF6U"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**说明**：
|
||
- 使用腾讯位置服务 WebServiceAPI Key
|
||
- Key 需在腾讯位置服务控制台申请
|
||
- 支持 Web JS API 调用
|
||
|
||
**申请地址**：[腾讯位置服务控制台](https://lbs.qq.com/)
|
||
|
||
**常见问题**：
|
||
- "鉴权失败，请传入正确的 key" → Key 无效或未申请
|
||
- Key 的服务权限需包含 WebServiceAPI
|
||
- 生产环境需在控制台配置安全域名（可选）
|
||
|
||
---
|
||
|
||
### 3.3 微信小程序配置
|
||
|
||
#### 3.3.1 默认模式（推荐）
|
||
|
||
微信小程序默认使用 `uni.openLocation()` → 调用微信内置地图，**无需配置任何地图 API Key**。
|
||
|
||
```javascript
|
||
// App.vue open_location 函数中的默认逻辑
|
||
uni.openLocation({
|
||
name: name,
|
||
address: address,
|
||
scale: scale,
|
||
longitude: lng,
|
||
latitude: lat,
|
||
});
|
||
```
|
||
|
||
**优点**：
|
||
- 无需申请地图 Key
|
||
- 用户体验流畅（调用微信原生地图）
|
||
- 无额外配置
|
||
|
||
**缺点**：
|
||
- 功能受限（无路线规划等高级功能）
|
||
|
||
#### 3.3.2 插件模式（可选）
|
||
|
||
如果需要使用腾讯位置服务的路线规划功能，可在微信小程序后台添加插件：
|
||
|
||
**配置步骤**：
|
||
1. 登录 [微信小程序后台](https://mp.weixin.qq.com/)
|
||
2. 设置 → 第三方设置 → 插件管理 → 添加插件
|
||
3. 搜索「腾讯位置服务路线规划」并添加
|
||
|
||
**manifest.json 配置**：
|
||
```json
|
||
"mp-weixin": {
|
||
"plugins": {
|
||
"routePlan": {
|
||
"version": "1.0.19",
|
||
"provider": "wx50b5593e81dd937a"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**代码调用**（需开启 `is_weixin_open_location_use_plugins = 1`）：
|
||
|
||
```javascript
|
||
// App.vue L1737-1750
|
||
if (this.data.is_weixin_open_location_use_plugins == 1) {
|
||
var key = this.get_config('config.common_tencent_map_ak') || null;
|
||
if (key != null) {
|
||
var plugin = requirePlugin('routePlan');
|
||
var end_point = JSON.stringify({
|
||
name: name,
|
||
longitude: lng,
|
||
latitude: lat,
|
||
});
|
||
uni.navigateTo({
|
||
url: 'plugin://routePlan/route-plan?key=' + key + '&referer=' + appName + '&endPoint=' + end_point,
|
||
});
|
||
}
|
||
}
|
||
```
|
||
|
||
**Key 来源**：服务端配置 `config.common_tencent_map_ak`
|
||
|
||
---
|
||
|
||
## 四、open_location 函数解析
|
||
|
||
**文件**：`App.vue` L1721-1760
|
||
|
||
```javascript
|
||
open_location(lng, lat, name, address, scale) {
|
||
// 参数校验
|
||
if (lng == undefined || lat == undefined || lng == '' || lat == '') {
|
||
this.showToast('位置信息不正确');
|
||
return false;
|
||
}
|
||
lat = parseFloat(lat);
|
||
lng = parseFloat(lng);
|
||
|
||
// #ifdef MP-WEIXIN
|
||
// 微信小程序插件模式
|
||
if (this.data.is_weixin_open_location_use_plugins == 1) {
|
||
var key = this.get_config('config.common_tencent_map_ak') || null;
|
||
// 使用腾讯位置服务插件...
|
||
}
|
||
// #endif
|
||
|
||
// 默认：调用 uni.openLocation
|
||
uni.openLocation({
|
||
name: name,
|
||
address: address,
|
||
scale: scale || 18,
|
||
longitude: lng,
|
||
latitude: lat,
|
||
});
|
||
}
|
||
```
|
||
|
||
**调用链路**：
|
||
1. `app.globalData.open_location(lng, lat, name, address)`
|
||
2. 平台条件编译（`#ifdef MP-WEIXIN`）
|
||
3. 判断是否使用插件模式
|
||
4. 调用地图原生 API
|
||
|
||
---
|
||
|
||
## 五、服务端配置读取机制
|
||
|
||
**配置数据流**：
|
||
```
|
||
服务端 API /api/common/base
|
||
↓
|
||
响应写入缓存 key: 'cache_config_info_key'
|
||
↓
|
||
App.vue this.get_config('config.xxx') 读取
|
||
```
|
||
|
||
**关键代码**（`App.vue`）：
|
||
|
||
```javascript
|
||
// 获取配置（从缓存读取）
|
||
get_config(key, default_value) {
|
||
var config = uni.getStorageSync(this.data.cache_config_info_key) || null;
|
||
// 解析 key.xxx.yyy 格式
|
||
var arr = key.split('.');
|
||
// ...
|
||
}
|
||
|
||
// 初始化配置（从服务端拉取）
|
||
init_config(num = 0, object, method, params) {
|
||
uni.request({
|
||
url: this.get_request_url('common', 'base'),
|
||
method: 'POST',
|
||
data: { is_key: 1 },
|
||
success: (res) => {
|
||
if (res.data.code == 0) {
|
||
var data = res.data.data;
|
||
uni.setStorageSync(this.data.cache_config_info_key, data);
|
||
}
|
||
}
|
||
});
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 六、常见问题排查
|
||
|
||
### Q1: H5 预览报错 "鉴权失败，请传入正确的 key"
|
||
|
||
**原因**：H5 的腾讯地图 Key 无效或未配置
|
||
|
||
**排查步骤**：
|
||
1. 检查 `manifest.json` 中 `h5.sdkConfigs.maps.tencent.key` 是否存在
|
||
2. 登录 [腾讯位置服务控制台](https://lbs.qq.com/) 验证 Key 状态
|
||
3. 确认 Key 已开通 WebServiceAPI 服务
|
||
4. 如 Key 无效，重新申请并更新 `manifest.json`
|
||
|
||
### Q2: 微信小程序地图无法打开
|
||
|
||
**原因**：可能是权限问题或未正确声明位置权限
|
||
|
||
**排查步骤**：
|
||
1. 检查 `manifest.json` 中 `mp-weixin.requiredPrivateInfos` 是否包含 `chooseLocation` / `getLocation`
|
||
2. 检查 `mp-weixin.permission.scope.userLocation.desc` 是否配置
|
||
3. 用户首次使用时需授权位置权限
|
||
|
||
### Q3: APP 地图无法定位
|
||
|
||
**原因**：高德地图 Key 配置错误或未申请原生定位模块
|
||
|
||
**排查步骤**：
|
||
1. 检查 `manifest.json` 中 `app-plus.modules.Geolocation` 是否启用
|
||
2. 检查 `app-plus.distribute.sdkConfigs.maps.amap.appkey_android` 是否正确
|
||
3. 检查 `AndroidManifest.xml` 是否配置定位权限（通常由云打包自动处理）
|
||
|
||
### Q4: 服务端配置 `config.common_tencent_map_ak` 未生效
|
||
|
||
**原因**：配置未同步或缓存问题
|
||
|
||
**排查步骤**：
|
||
1. 确认服务端 `common/base` API 返回了 `config.common_tencent_map_ak` 字段
|
||
2. 清除小程序缓存，重新加载配置
|
||
3. 检查 `is_weixin_open_location_use_plugins` 是否设置为 1
|
||
|
||
---
|
||
|
||
## 七、配置检查清单
|
||
|
||
| 项目 | 检查点 | 状态 |
|
||
|------|--------|------|
|
||
| **H5 腾讯地图** | `manifest.json` 中 `h5.sdkConfigs.maps.tencent.key` 是否有效 | ✅ 已更新 |
|
||
| **APP 高德地图 Android** | `manifest.json` 中 `appkey_android` 是否有效 | ✅ 正常 |
|
||
| **APP 高德地图 iOS** | `manifest.json` 中 `appkey_ios` 是否有效 | ✅ 正常 |
|
||
| **微信小程序** | `manifest.json` 中 `requiredPrivateInfos` 包含位置权限 | ✅ 正常 |
|
||
| **微信小程序插件模式** | 服务端配置 `config.common_tencent_map_ak` | 可选功能 |
|
||
|
||
---
|
||
|
||
## 八、参考链接
|
||
|
||
| 资源 | 地址 |
|
||
|------|------|
|
||
| 腾讯位置服务控制台 | https://lbs.qq.com/ |
|
||
| 高德开放平台 | https://lbs.amap.com/ |
|
||
| uni.openLocation 文档 | https://uniapp.dcloud.net.cn/api/location/open-location.html |
|
||
| uni.getLocation 文档 | https://uniapp.dcloud.net.cn/api/location/get-location.html |
|
||
| 微信小程序地图组件 | https://developers.weixin.qq.com/miniprogram/dev/component/map.html |
|
||
|
||
---
|
||
|
||
## 九、更新记录
|
||
|
||
| 日期 | 更新内容 |
|
||
|------|---------|
|
||
| 2026-06-04 | 新建文档，记录各平台地图配置机制及 H5 鉴权失败问题排查 |
|
||
| 2026-06-04 | 更新 `manifest.json` 中的 H5 腾讯地图 Key（`XZHBZ-4OUKA-SMSKV-CXXHB-OKOGQ-FSF6U`） |
|