vr-shopxo-uniapp/docs/map-api-key-configuration.md

# 地图 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`） |