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

"app-plus": {
    "distribute": {
        "sdkConfigs": {
            "maps": {
                "amap": {
                    "name": "amapu9VF72Gg",
                    "appkey_ios": "f55e9099897821681f5c74051e4527bd",
                    "appkey_android": "ebe9f1d84f8ceb8b3c4ba6ead2bfa78b"
                }
            }
        }
    }
}

说明：

• name：高德地图应用名称
• appkey_android：Android 平台 Key
• appkey_ios：iOS 平台 Key

申请地址：高德开放平台

---

3.2 H5 腾讯地图配置

配置文件：manifest.json

"h5": {
    "sdkConfigs": {
        "maps": {
            "tencent": {
                "key": "XZHBZ-4OUKA-SMSKV-CXXHB-OKOGQ-FSF6U"
            }
        }
    }
}

说明：

• 使用腾讯位置服务 WebServiceAPI Key
• Key 需在腾讯位置服务控制台申请
• 支持 Web JS API 调用

申请地址：腾讯位置服务控制台

常见问题：

• "鉴权失败，请传入正确的 key" → Key 无效或未申请
• Key 的服务权限需包含 WebServiceAPI
• 生产环境需在控制台配置安全域名（可选）

---

3.3 微信小程序配置

3.3.1 默认模式（推荐）

微信小程序默认使用 uni.openLocation() → 调用微信内置地图，无需配置任何地图 API Key。

// App.vue open_location 函数中的默认逻辑
uni.openLocation({
    name: name,
    address: address,
    scale: scale,
    longitude: lng,
    latitude: lat,
});

优点：

• 无需申请地图 Key
• 用户体验流畅（调用微信原生地图）
• 无额外配置

缺点：

• 功能受限（无路线规划等高级功能）

3.3.2 插件模式（可选）

如果需要使用腾讯位置服务的路线规划功能，可在微信小程序后台添加插件：

配置步骤：

1. 登录 微信小程序后台
2. 设置 → 第三方设置 → 插件管理 → 添加插件
3. 搜索「腾讯位置服务路线规划」并添加

manifest.json 配置：

"mp-weixin": {
    "plugins": {
        "routePlan": {
            "version": "1.0.19",
            "provider": "wx50b5593e81dd937a"
        }
    }
}

代码调用（需开启 is_weixin_open_location_use_plugins = 1）：

// 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

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）：

// 获取配置（从缓存读取）
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. 登录 腾讯位置服务控制台 验证 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）