miniprogramme/utils/map-setup.md

高德地图小程序集成配置说明

1. 申请高德地图API Key

1. 访问高德开放平台：https://lbs.amap.com/dev/
2. 注册开发者账号并实名认证
3. 创建应用，选择"微信小程序"平台
4. 获取API Key，复制到 config/config.js 的 amapKey 字段

2. 配置微信小程序合法域名

在微信小程序后台（mp.weixin.qq.com）的"开发设置"中添加以下合法域名：

request合法域名：

• https://restapi.amap.com

uploadFile合法域名：

• https://restapi.amap.com

downloadFile合法域名：

• https://restapi.amap.com

3. 位置权限配置

app.json 中已配置位置权限：

{
  "permission": {
    "scope.userLocation": {
      "desc": "你的位置信息将用于小程序位置接口的效果展示"
    }
  },
  "requiredBackgroundModes": ["location"],
  "requiredPrivateInfos": ["getLocation"]
}

4. 使用的功能

当前实现的地图功能包括：

基础功能

• GPS定位获取当前位置
• 高德地图逆地理编码（经纬度转地址）
• 地图标记显示
• 位置权限管理
• 定时位置更新

高级功能

• 好友位置显示
• 附近用户搜索
• 位置距离计算
• 地图区域自适应
• 位置隐私保护

API集成

• 与后端位置服务完整对接
• 支持位置上传和好友位置获取
• 附近用户搜索功能
• 位置历史记录

5. 文件结构

miniprogram/
├── libs/
│   └── amap-wx.js          # 高德地图SDK
├── utils/
│   ├── map-config.js       # 地图配置和工具类
│   └── api-client.js       # API客户端（已添加位置相关方法）
├── pages/map/
│   ├── map.js              # 地图页面逻辑
│   ├── map.wxml            # 地图页面模板
│   └── map.wxss            # 地图页面样式
└── config/
    └── config.js           # 配置文件（需要添加amapKey）

6. 注意事项

1. API Key安全：不要将API Key提交到公开仓库
2. 权限引导：首次使用时会引导用户授权位置权限
3. 网络环境：高德API需要网络连接，注意处理网络异常
4. 坐标系：使用GCJ02坐标系（高德地图标准）
5. 性能优化：位置更新采用30秒间隔，避免频繁请求

7. 测试建议

1. 真机测试位置权限和定位功能
2. 测试网络异常情况的处理
3. 验证好友位置显示是否正常
4. 检查地图标记和交互功能

8. 故障排除

定位失败

• 检查位置权限是否开启
• 确认网络连接正常
• 验证高德API Key是否有效

地址解析失败

• 检查合法域名配置
• 确认API Key额度是否充足
• 验证网络请求是否被拦截

地图显示异常

• 检查坐标数据格式
• 确认地图组件属性配置
• 验证标记数据结构是否正确

9. 扩展功能

可以根据需要添加更多功能：

• 路径规划和导航
• POI搜索
• 地理围栏
• 轨迹回放
• 多种地图图层