地图集成

地图服务用于问卷、考试中的地理位置题，以及打卡签到中的地点搜索和地图选点。当前支持 高德地图 和 腾讯地图，管理员配置后，项目共用所选地图服务。

高德地图正式部署建议使用安全代理：地图 Key 填入卷王后台，配套的安全密钥保存在 Nginx 中。开发调试也可以直接在后台填写 Key 和安全密钥。

配置入口

进入 基础设施 → 配置管理，在左侧配置分类中选择 基础设施。页面地址为 /infra/config?group=infra。

配置项	如何填写
地图类型	选择高德地图或腾讯地图，对应配置值分别为 amap、tmap
地图 Key	所选地图供应商的 Web 端 JavaScript API Key
高德安全密钥	与高德 Key 配套的 securityJsCode；仅在高德直连模式使用
高德安全代理地址	使用高德代理时填写，例如 https://survey.example.com/_AMapService；直连时留空

点击对应卡片的编辑按钮修改并保存。修改地图 Key 或安全密钥时，需要开启 修改敏感值；保持现有值不会覆盖已保存的凭据。卡片显示“已配置”只表示保存过配置，不代表地图调用已经验证成功。

修改地图类型、Key、安全密钥或代理地址后，都需要完整刷新浏览器页面。 地图 SDK 在首次加载时读取配置，仅关闭再打开地图弹窗不会重新初始化全部配置。

高德地图

准备 Key 和安全密钥

1. 登录 高德开放平台控制台，在应用管理中创建应用或选择已有应用。
2. 添加 Key，服务平台选择 Web 端（JS API）。
3. 保存同一条 Key 对应的 Key 和 安全密钥，两者不能互换。
4. 如设置了域名白名单，将实际使用地图的管理端、填写端域名纳入授权范围。

申请流程和平台要求参见 高德 JS API 接入准备。下面示例只包含占位值，请使用自己申请的凭据。

正式部署：使用 Nginx 安全代理

采用与卷王站点相同域名的 HTTPS 代理，浏览器把地图服务请求发送到本站，由 Nginx 追加安全密钥后转发给高德。转发路径依据 高德安全密钥使用说明。

第一步：修改站点 Nginx 配置。

将以下内容放到卷王站点现有的 server { ... } 内，与 location /、后端接口等配置同级。可以放在前端路由配置前面；使用宝塔时，在对应网站的配置文件中添加。

把 YOUR_AMAP_SECURITY_CODE 替换为高德控制台的 安全密钥。这里填写的是 securityJsCode，不是地图 Key。

# 与后台地图 Key 配套的安全密钥，仅保存在部署服务器
set $amap_jscode "YOUR_AMAP_SECURITY_CODE";

# 自定义地图样式服务
location ^~ /_AMapService/v4/map/styles {
    set $args "$args&jscode=$amap_jscode";

    proxy_ssl_server_name on;
    proxy_set_header Host webapi.amap.com;
    # 地图供应商不需要本站的登录信息
    proxy_set_header Cookie "";
    proxy_set_header Authorization "";
    proxy_pass https://webapi.amap.com/v4/map/styles;

    access_log off;
}

# 地点搜索、地理编码等 Web 服务
location ^~ /_AMapService/ {
    set $args "$args&jscode=$amap_jscode";

    proxy_ssl_server_name on;
    proxy_set_header Host restapi.amap.com;
    proxy_set_header Cookie "";
    proxy_set_header Authorization "";
    proxy_pass https://restapi.amap.com/;

    access_log off;
}

保留 proxy_pass https://restapi.amap.com/; 末尾的 /，这样 /_AMapService/v3/... 才会转发为高德的 /v3/...。^~ 用于避免地图请求被其他正则路由接管。

示例关闭了地图代理的访问日志。如果需要保留日志，使用不记录查询参数的格式，例如记录 $request_method $uri $server_protocol；不要记录追加密钥后的 $args。同源代理会携带本站请求头，示例已清除不需要转发给高德的 Cookie 和 Authorization。

第二步：检查配置并重载 Nginx。

先在部署服务器执行语法检查：

nginx -t

只有检查成功后，才执行重载：

nginx -s reload

宝塔环境可使用对应的完整路径 /www/server/nginx/sbin/nginx 替代命令中的 nginx。

第三步：填写卷王后台地图配置。

配置项	代理模式填写示例
地图类型	高德地图
地图 Key	高德控制台中 Web 端（JS API）的 Key
高德安全密钥	可以留空；配置代理地址后，此项不参与认证
高德安全代理地址	https://survey.example.com/_AMapService

将 survey.example.com 替换为自己的卷王站点域名。代理地址必须是完整的 HTTP(S) 地址，且以 /_AMapService 结尾；末尾不要加 /，不要拼接 Key、安全密钥、查询参数或锚点。HTTPS 网站使用 HTTPS 代理。

卷王会自动将代理地址传给地图 SDK，无需另外修改前端 HTML。启用代理后，系统不会再把“高德安全密钥”配置下发给浏览器；修改安全密钥应更新 Nginx 配置并重载。

开发调试：直接填写安全密钥

没有配置代理的开发环境，可以按以下方式填写：

配置项	直连模式填写内容
地图类型	高德地图
地图 Key	高德 Web 端（JS API）Key
高德安全密钥	与该 Key 配套的 securityJsCode
高德安全代理地址	留空

保存并完整刷新页面即可。直连模式会将安全密钥提供给浏览器，用于 SDK 认证，因此适合开发调试；正式部署按上面的代理方式配置。如果之前使用过代理，切换直连时需清空代理地址，否则系统仍优先使用代理。

腾讯地图

1. 在 腾讯位置服务控制台 创建应用和 Key，按 JavaScript API GL 接入指南 准备浏览器端使用的 Key。
2. 在卷王后台将 地图类型 设为 腾讯地图，将 地图 Key 改为对应的腾讯 Key。
3. 高德安全密钥 和 高德安全代理地址 不用于腾讯地图，可留空。
4. 保存并完整刷新页面，验证地图显示、地点搜索和定位。

当前卷王的腾讯地图接入直接使用腾讯 Key，不使用上面的 /_AMapService 代理。地图显示与地点搜索、地址解析需要分别验证，相关服务权限、域名限制和调用额度以腾讯位置服务控制台为准。

在项目中验证

先在一个测试项目中分别验证地图和定位，避免仅凭底图显示正常就判断所有功能可用。

1. 在问卷或考试中添加地理位置题，打开填写页，检查地图显示和获取当前位置。
2. 在打卡签到项目的地点设置中搜索一个公开地点，选择搜索结果或点击地图，检查地点名称、经纬度和范围是否正确回填。
3. 使用手机访问正式 HTTPS 填写链接，允许系统和浏览器获取位置，检查定位结果及打卡范围提示。
4. 使用高德代理时，在浏览器开发者工具的 Network 中筛选 _AMapService。触发地点搜索后，请求应发往配置的本站代理地址，响应应为地图服务数据。

高德安全代理负责相应的服务请求，浏览器仍需要加载地图供应商的 SDK 和地图资源。仅配置 Nginx 代理不能让地图在完全断网的环境中运行。

浏览器定位需要安全上下文和用户授权。手机访问时使用设备信任的 HTTPS 证书，并开启系统定位及浏览器的站点定位权限；仅配置地图 Key 不能替代这些条件。相关要求参见 浏览器定位接口说明。

常见问题

现象	排查方式
地图类型显示“未识别的地图类型”	编辑地图类型，从下拉框重新选择高德地图或腾讯地图并保存，再刷新。实际配置值应为 amap 或 tmap，不要把供应商中文名称、Key 或其他内容填为类型
显示“已配置”，但地图仍不可用	核对地图类型与 Key 是否匹配，确认配置保存成功并完整刷新页面，再检查实际请求的错误信息
INVALID_USER_KEY	检查 Key 是否填写完整、有效，是否属于当前所选地图供应商
USERKEY_PLAT_NOMATCH	确认高德 Key 的服务平台为 Web 端（JS API），不要混用 Web 服务、Android 或 iOS 的 Key
INVALID_USER_SCODE，或底图正常但搜索报安全校验失败	确认 Key 与安全密钥配套。直连检查后台安全密钥；代理模式检查 Nginx 是否追加正确的 jscode、配置是否重载，以及后台代理地址是否生效
INVALID_USER_DOMAIN	检查地图 Key 的域名白名单是否包含当前实际访问域名，注意管理端与填写端可能使用不同域名
USER_DAILY_QUERY_OVER_LIMIT 或 SERVICE_NOT_AVAILABLE	在供应商控制台核对调用额度和服务开通状态
代理返回 404，或返回卷王页面的 HTML	检查 location 是否加在实际处理该域名的 server 内，路径是否大小写一致，以及是否被其他重写规则或前端路由接管
代理返回 502	检查部署服务器的 DNS、到高德服务的 HTTPS 连接及 Nginx 错误日志，核对对应上游 Host 和 SNI 配置
切换供应商后仍请求旧服务	完整刷新页面，使 SDK 按新配置重新加载；同时确认地图 Key 已换成新供应商的 Key
地图可显示，但手机获取位置失败	检查 HTTPS 证书是否受信任、系统定位开关、浏览器站点定位权限和设备网络
后台没有安全密钥或代理地址配置项	核对前后端是否都已升级到支持该配置的版本；仅更新前端页面不能替代后端配置支持

地图供应商的服务授权、配额和计费以其控制台及最新说明为准。出现授权提示时，应核对该 Key 的服务授权，Nginx 代理不会改变供应商的授权范围。