Cloud-Tour-to-Libo/docs/高德地图API配置说明.md

云游荔波：高德地图 API 配置说明

本文供项目同事在下载“云游荔波”代码后配置高德地图使用。仓库不会保存真实 Key，请由项目负责人通过私密渠道单独提供。

1. 地图展示需要的配置

http://localhost:8102/admin/plaza/overview 中的荔波地图使用高德 Web 端（JS API）Key，需要同时配置：

AMAP_JS_KEY=你的高德Web端JS_API_Key
AMAP_SECURITY_JSCODE=该Key对应的安全密钥

两个值必须来自同一个高德 Web 端（JS API）应用。只填写其中一个、Key 类型错误或安全密钥不匹配，地图都会加载失败。

项目还保留了下面这个配置：

AMAP_WEB_KEY=你的高德Web服务_Key

AMAP_WEB_KEY 用于服务端 POI 搜索、行政区查询和路径规划等采集任务，不是打开现有地图页面的必需项。只需要查看荔波地图时可以暂时留空。

2. 同事下载后的配置步骤

git clone https://git.nianxx.cn/xuelong/Cloud-Tour-to-Libo.git
cd Cloud-Tour-to-Libo
cp .env.example .env

打开项目根目录下的 .env，填写：

AMAP_JS_KEY=
AMAP_SECURITY_JSCODE=

然后启动项目：

docker compose up -d --build

如果项目已经启动，只修改了高德配置，可重新创建 API 容器：

docker compose up -d --force-recreate api

打开：

http://localhost:8102/admin/plaza/overview

进入“云游荔波”项目后，应能看到荔波县底图、POI 点位、公交路线和详情侧栏。

3. 高德控制台要求

在高德开放平台创建 Key 时应选择 Web 端（JS API），并取得该 Key 对应的安全密钥。若配置了域名白名单，请至少允许实际访问系统使用的域名；本地开发通常需要包含：

localhost
127.0.0.1

如果同事使用局域网 IP、测试域名或线上域名访问，还需要把对应域名加入高德控制台允许范围。

4. 常见问题

页面显示“高德 JS API Key 未配置”

检查 .env 是否位于项目根目录，并确认变量名完全一致：

AMAP_JS_KEY=
AMAP_SECURITY_JSCODE=

修改后重新创建 api 容器。

页面有地图容器，但底图为空

依次检查：

1. Key 是否为 Web 端（JS API）类型。
2. AMAP_SECURITY_JSCODE 是否与当前 Key 配套。
3. 高德控制台域名白名单是否包含当前访问域名。
4. 浏览器是否能访问 https://webapi.amap.com。
5. 浏览器开发者工具中是否出现 INVALID_USER_KEY、安全密钥错误或域名未授权提示。

地图能显示，但服务端采集不能运行

地图展示和服务端采集使用不同类型的 Key。服务端采集还需填写：

AMAP_WEB_KEY=

并确认该 Key 已开通相应的 Web 服务 API 配额。

5. 密钥安全

• 不要把真实 Key 写入本文件、.env.example、聊天截图或提交记录。
• .env 已被 Git 忽略，只保留在使用者本机。
• 同事所需真实值应通过密码管理器或其他私密渠道传递。
• 如 Key 曾经被提交到仓库或公开发送，应立即在高德控制台更换。
• 正式环境建议为开发、测试、生产分别创建 Key，并分别配置允许域名和调用额度。