9. 地图 SDK 接入与 LBS 定位

地图 SDK 接入就是用百度/高德地图 API 在页面上显示地图和标注点。

核心三步：
① 申请密钥——去官网注册拿 AK
② 引 JS——script 标签带密钥
③ 初始化地图 + 加标注

坑：密钥要配置白名单、地图容器要有宽高、坐标经纬度别搞反。

9.1 先跑起来：四步接入流程演示

地图 SDK 需要真实的 key 才能联网把真地图显示出来，所以本页用"步骤演示 + 代码讲解"代替真实地图，让你先把四步流程在脑子里走一遍。真正上手时，照下面的代码换成你自己的 key 就行。

9.2 申请 Key（用地图服务的第一步）

key 就像是你调用地图服务的"门禁卡"。没有它，SDK 知道你是谁、该不该给你出图。一定要选对平台类型——Web 页面就选"Web端 JS API"，选错了照样加载不出来。

9.3 引入 SDK（JS API 方式）

<!-- 引入高德地图 JS API，把 key 换成你自己的 --> → 第一步：把地图 SDK 从 CDN 引进来
<
script src = "https:  // webapi.amap.com/maps?v=2.0&amp

  <
  !--容器必须指定宽高， 否则地图不显示 -->
→ 跟 ECharts 一样， 得给个有尺寸的窝
  <
  div id = "map"
style = "width:100%;height:400px;" > < /div> → 空 div 当地图容器，必须写死高度

和 ECharts 一模一样的坑：① 容器不写宽高 → 地图白屏；② key 填错或没配域名 → 加载失败。建议第一步先加载一张最小地图验证 key 通了，再往上加业务功能，别一上来就堆一堆代码。

9.4 初始化地图

// 高德 2.0 推荐用 Loader 方式加载 → 用官方加载器来引，更稳
// 拿到加载器
import AMapLoader from "@amap/amap-jsapi-loader";

// 开始加载地图
AMapLoader.load({
  // 把你的门禁卡 key 填这
  key: "你的KEY值",
  // 用 2.0 版本
  version: "2.0",
  // 要哪些插件
  plugins: ["AMap.Scale", "AMap.ToolBar"]
// 加载成功，拿到 AMap 对象（普通 function）
}).then(function (AMap) {
  // 初始化地图：传容器 id + 中心点 + 缩放级别 → 在那个 div 上把地图画出来
  // 在 id=map 的容器里建图
  const map = new AMap.Map("map", {
    // 缩放级别（3-18，越大越近）
    zoom: 12,
    // 中心点经纬度
    center: [116.397428, 39.90923],
    // 用 2D 平面模式
    viewMode: "2D"
  });
// 加载失败打错误（普通 function）
}).catch(function (err) { console.log("地图加载失败", err); });

初始化就三件事：容器、中心点（center）、缩放级别（zoom）。[经度, 纬度]，北京天安门的坐标是 [116.397428, 39.90923]，记不住没关系，文档里有。

9.5 添加标记（Marker）+ 信息窗体（InfoWindow）

// 地图加载成功后：→ 图出来了，开始往上面钉标记
// 1. 加一个红色标记点 → 就是钉个图钉
// 造一个标记
const marker = new AMap.Marker({
  // 标记位置 → 钉在哪（经纬度）
  position: [116.397428, 39.90923],
  // 鼠标悬停的标题 → 鼠标放上去显示啥
  title: "天安门"
});
// 把这个标记加到地图上
map.add(marker);

// 2. 点标记时弹一个信息窗体 → 点图钉，弹个气泡
// 造一个气泡框
const infoWindow = new AMap.InfoWindow({
  // 气泡里显示啥内容
  content: "<h3>天安门</h3><p>北京市中心</p>",
  // 往上偏移，避免遮住标记 → 把气泡往上抬一点，别挡住图钉
  offset: new AMap.Pixel(0, -30)
});
// 点这个标记时（普通 function）
marker.on("click", function () {
  // 在标记位置把气泡弹出来
  infoWindow.open(map, marker.getPosition);
});

标记点 AMap.Marker 负责"在地图上钉个图钉"，InfoWindow 负责"点图钉弹出一个气泡框"。这是地图上最常见的两个组合——标出门店、标出地址，都靠它们。

9.6 定位：浏览器定位 + 坐标纠偏（最容易踩的坑）

// 浏览器定位（需要用户点"允许"）→ 让浏览器告诉你用户现在在哪
// 先看浏览器支不支持定位
if (navigator.geolocation) {
  // 发起一次定位
  navigator.geolocation.getCurrentPosition(
    // 定位成功，拿到位置
    function (pos) {
      // 取出经度
      const lng = pos.coords.longitude();
      // 取出纬度
      const lat = pos.coords.latitude();
      // 重要：浏览器给的是 GPS 坐标（WGS-84）
      // 把 GPS 坐标转成高德坐标（普通 function）
      const converted = AMap.convertFrom([lng, lat], "gps", function (err, res) {
        // 转好后的坐标
        const p = res.locations[0];
        // 把地图中心移到定位点 → 地图自动移到用户那
        map.setCenter(p);
        // 在用户位置钉个标记
        const marker = new AMap.Marker({ position: p });
        // 把标记加上
        map.add(marker);
      });
    },
    // 失败回调 + 开高精度、5 秒超时
    function (err) { console.log("定位失败", err); }, { enableHighAccuracy: true, timeout: 5000 }
  );
}

这是地图定位最隐蔽的一个坑：坐标系不一样。浏览器给你的是 WGS-84（GPS 原始坐标），而国内地图用的是 GCJ-02（俗称"火星坐标"，加过密）。如果你直接把 GPS 坐标扔上去标记，点会偏出去几百米，看起来像"我人在这，红点在隔壁街"。必须用 AMap.convertFrom 转换一下。

9.7 常见问题

9.8 高德 vs 百度 vs 腾讯（选型参考）

9.9 实战：用在哪 / 常见坑 / 怎么解决

① 可能在什么地方用：外卖/打车的实时位置、门店选址地图、收货地址选点、物流轨迹、附近的人——凡是要在地图上"标出位置、画路线"的都是地图 SDK。

② 常见的问题：地图白屏（容器没宽高）；加载报错（key 错或域名没配）；红点位置偏了一条街（没做 WGS-84 → GCJ-02 坐标转换）；定位半天没反应（用户没点"允许"定位，或 https 环境限制）。

③ 解决思路：白屏就给容器写死高度；报错就去控制台看报错码、核对 key 和域名；位置偏就在取到经纬度后先调 AMap.convertFrom；定位不出来就确认页面是不是 https（浏览器定位要求安全环境）。记住四步：申请 key → 引 SDK → 初始化（容器要宽高）→ 加 Marker。

本页重点