9. 地图 SDK 接入与 LBS 定位

把这页想成"请个专业向导带你认路"：画地图、定位置、标红点这种活，你别自己干，直接请厂商的地图 SDK（高德 / 百度 / 腾讯）来做。接入套路是固定的四步：申请 key → 引入 SDK → 初始化地图 → 加标记。和接插件一个道理——按官方文档顺序来，别自己瞎调。

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

点击"下一步"逐步走一遍接入流程。

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

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

高德开放平台 → 控制台 → 应用管理 → 创建应用 → 添加 Key → 选择平台（Web端 / 小程序 / 服务端）→ 复制 Key 到代码里。注意：Key 是绑定域名的，前端用的 key 和后端用的 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;key=你的KEY值&amp;plugin=AMap.Scale,AMap.ToolBar"></script>  → key 换成你申请的，还顺手加载比例尺、工具条插件

<!-- 容器必须指定宽高，否则地图不显示 -->  → 跟 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 填这
  version: "2.0",                    // 用 2.0 版本
  plugins: ["AMap.Scale", "AMap.ToolBar"]  // 要哪些插件（比例尺、工具条）
}).then((AMap) => {                  // 加载成功，拿到 AMap 这个对象
  // 初始化地图：传容器 id + 中心点 + 缩放级别 → 在那个 div 上把地图画出来
  const map = new AMap.Map("map", {  // 在 id 为 map 的容器里建图
    zoom: 12, // 缩放级别（3-18，越大越近）→ 数字越大拉得越近
    center: [116.397428, 39.90923], // 中心点经纬度（北京天安门）→ [经度, 纬度]
    viewMode: "2D"                   // 用 2D 平面模式
  });
}).catch(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) // 往上偏移，避免遮住标记 → 把气泡往上抬一点，别挡住图钉
});
marker.on("click", => {             // 点这个标记时
  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），必须转成高德坐标（GCJ-02）！→ 不转会偏一条街
      const converted = AMap.convertFrom([lng, lat], "gps", (err, res) => {  // 把 GPS 坐标转成高德坐标
        const p = res.locations[0];  // 转好后的坐标
        map.setCenter(p); // 把地图中心移到定位点 → 地图自动移到用户那
        const marker = new AMap.Marker({ position: p });  // 在用户位置钉个标记
        map.add(marker);             // 把标记加上
      });
    },
    function (err) { console.log("定位失败", err); }, { enableHighAccuracy: true, timeout: 5000 }  // 失败回调 + 开高精度、5 秒超时
  );
}

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

9.7 常见问题

现象	原因	怎么解决
地图白屏	容器没有宽高	给容器写死 width / height
加载报错	key 错了 / 域名没配白名单	检查 key、平台类型、域名配置
标记位置偏了	坐标系没转换	用 convertFrom 转成 GCJ-02
地图被挡住 / 点不动	层级 / z-index 问题	给地图容器设好 z-index，弹窗放上面

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

SDK	特点	常见用途
高德	JS API 成熟，文档全，生态好	电商配送、出行、门店定位
百度	国内起步早，POI 数据丰富	搜索类、本地生活
腾讯	小程序集成方便	微信小程序里的地图

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

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

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

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

一句话：地图 = 申请 key → 引 SDK → 初始化（容器必须有宽高）→ 加 Marker；GPS 坐标记得用 convertFrom 转成 GCJ-02，否则红点会偏一条街。