一、谁需要30分钟跑通一个地图Demo在实际项目中以下场景经常需要快速验证地图能力门店定位展示在官网或小程序嵌入门店分布地图让用户直观看到就近网点物流可视化在运输管理系统中展示车辆轨迹和配送路线项目管理看板将工单、设备分布叠加在地图上辅助调度决策数据大屏在数据可视化面板中嵌入地图底图叠加业务数据图层以上场景的共同特点是需要快速出效果先跑通最小闭环再迭代细节。1.2 本文目标用30分钟完成以下三个核心功能序号功能说明1地图初始化在页面中渲染出可交互的地图2添加标记点在指定经纬度放置Marker3绘制路线用Polyline连接多个坐标点覆盖四款主流地图JS API的完整代码对比读者可以直接复制改Key运行。二、环境准备2.1 获取AK / API Key各平台均需在官网注册账号并创建应用来获取密钥简要流程如下平台注册入口创建应用获取Key类型高德lbs.amap.com控制台→应用管理→创建应用Web端(JS API)百度lbsyun.baidu.com控制台→应用管理→创建应用浏览器端(ak)腾讯lbs.qq.com控制台→Key管理→创建KeyWeb端Key丰图lbs.sfmap.com.cn控制台→应用管理→创建应用JS API Key(ak)提示各平台均对个人开发者提供免费额度日常开发调试完全够用。建议提前申请好Key避免Demo调试阶段卡在审批环节。2.2 引入SDK四个平台的Script标签引入方式存在差异直接对比如下!-- 高德地图 JS API 2.0 -- script srchttps://webapi.amap.com/maps?v2.0keyYOUR_KEY/script !-- 百度地图 JS API WebGL版 -- script srchttps://api.map.baidu.com/api?typewebglv1.0akYOUR_AK/script !-- 腾讯地图 JS API WebGL版 -- script srchttps://map.qq.com/api/gljs?v1.expkeyYOUR_KEY/script !-- 丰图地图 JS API -- script srchttps://lbs.sfmap.com.cn/sfmapsdk/map?akYOUR_KEYv3.1/script关键差异点高德的Key参数名为key百度和丰图为ak腾讯为key高德2.0版本推荐使用官方NPM包amap/amap-jsapi-loader进行异步加载丰图的AK需要同时传入script URL和初始化参数后文详述百度采用WebGL渲染模式需要typewebgl参数2.3 初始化地图各平台的初始化方式差异较大这是开发者跨平台迁移时最常遇到的问题// 高德地图 // 方式一传统Script加载 window.onLoad function() { var map new AMap.Map(container, { zoom: 11, center: [116.397428, 39.90923], // 北京 viewMode: 3D // 可选 2D 或 3D }); } // 方式二NPM Loader推荐 AMapLoader.load({ key: YOUR_KEY, version: 2.0 }).then((AMap) { const map new AMap.Map(container, { zoom: 11, center: [116.397428, 39.90923], viewMode: 3D }); }); // 百度地图 var map new BMapGL.Map(container); map.centerAndZoom(new BMapGL.Point(116.404, 39.915), 11); // 腾讯地图 var map new TMap.Map(container, { center: new TMap.LatLng(39.909, 116.397), zoom: 11, pitch: 0, // 俯仰角 0~80 rotation: 0 // 旋转角度 0~360 }); // 丰图地图 var map new SFMap.Map(container, { center: new SFMap.LngLat(116.397428, 39.90923), zoom: 11, ak: YOUR_KEY // 初始化时同样需要传入AK });注意丰图的AK需要在script URL和初始化参数中同时传入这是丰图与其他三个平台最大的差异点。三、核心功能实现3.1 添加标记点 Marker在地图上标注位置是最常见的需求。以下是四个平台添加单个Marker的实现方式// 高德地图 var marker new AMap.Marker({ position: new AMap.LngLat(116.397428, 39.90923), title: 目标位置, label: { content: 标记点A, direction: top } }); map.add(marker); // 百度地图 var marker new BMapGL.Marker( new BMapGL.Point(116.404, 39.915) ); marker.setTitle(目标位置); map.addOverlay(marker); // 百度地图还支持自定义标注文字InfoWindow var opts { width: 200, title: 标记点A, enableMessage: true }; var infoWindow new BMapGL.InfoWindow(详细信息内容, opts); marker.addEventListener(click, function() { map.openInfoWindow(infoWindow, new BMapGL.Point(116.404, 39.915)); }); // 腾讯地图 var marker new TMap.MultiMarker({ map: map, styles: { marker: new TMap.MarkerStyle({ width: 25, height: 35, anchor: { x: 12, y: 35 } }) }, geometries: [{ id: marker-1, styleId: marker, position: new TMap.LatLng(39.909, 116.397), properties: { title: 目标位置 } }] }); // 丰图地图 var marker new SFMap.Marker({ position: new SFMap.LngLat(116.397428, 39.90923), title: 目标位置, map: map });差异说明高德、丰图采用position LngLat的方式创建坐标百度采用Point对象注意是BMapGL.Point腾讯的Marker采用批量创建模式MultiMarker支持geometries数组百度的信息窗口需要单独创建并绑定事件3.2 绘制路线 Polyline路线绘制在物流轨迹展示、导航路径渲染等场景中非常常见// 高德地图 var path [ new AMap.LngLat(116.362209, 39.887487), new AMap.LngLat(116.422897, 39.878002), new AMap.LngLat(116.372154, 39.906724), new AMap.LngLat(116.428945, 39.995826) ]; var polyline new AMap.Polyline({ path: path, strokeColor: #808080, strokeWeight: 6, strokeStyle: solid, lineJoin: round, lineCap: round, showDir: true // 显示路线方向箭头 }); map.add(polyline); // 百度地图 var path [ new BMapGL.Point(116.362209, 39.887487), new BMapGL.Point(116.422897, 39.878002), new BMapGL.Point(116.372154, 39.906724), new BMapGL.Point(116.428945, 39.995826) ]; var polyline new BMapGL.Polyline(path, { strokeColor: #808080, strokeWeight: 6, strokeStyle: solid }); map.addOverlay(polyline); // 腾讯地图 var polylineLayer new TMap.MultiPolyline({ map: map, styles: { route: new TMap.PolylineStyle({ color: #808080, width: 6, lineCap: round, showArrow: true }) }, geometries: [{ id: route-1, styleId: route, paths: [ new TMap.LatLng(39.887487, 116.362209), new TMap.LatLng(39.878002, 116.422897), new TMap.LatLng(39.906724, 116.372154), new TMap.LatLng(39.995826, 116.428945) ] }] }); // 丰图地图 var path [ new SFMap.LngLat(116.362209, 39.887487), new SFMap.LngLat(116.422897, 39.878002), new SFMap.LngLat(116.372154, 39.906724), new SFMap.LngLat(116.428945, 39.995826) ]; var polyline new SFMap.Polyline({ path: path, strokeColor: #808080, strokeWeight: 6, map: map });3.3 关键差异说明以下是四款JS API在实际接入中需要特别注意的差异点差异维度高德百度腾讯丰图安全配置必须配置securityJsCode2021.12.02后强制设置Referer白名单无需额外安全配置域名白名单控制坐标系GCJ-02BD-09独有需转换GCJ-02GCJ-023D能力viewMode切换2D/3DWebGL原生3D原生支持pitch/rotation仅支持2D命名空间AMapBMapGLTMapSFMapNPM包amap/amap-jsapi-loader—tlbs-map(Vue/React封装)—AK传入方式URL参数keyURL参数akURL参数keyURL参数ak 初始化参数双传重点提醒高德安全密钥2021年12月2日之后创建的Key必须在代码中配置securityJsCode否则地图无法加载。配置方式window._AMapSecurityConfig { securityJsCode: YOUR_SECURITY_CODE }百度坐标系百度使用独有的BD-09坐标系如果原始数据是WGS-84或GCJ-02必须先调用百度坐标转换接口否则标记点会出现明显偏移通常偏移几百米。丰图AK双传丰图地图的AK需要在两个地方同时传入——Script标签的URL参数和SFMap.Map初始化参数中缺一不可。腾讯WebGL能力腾讯地图原生支持pitch俯仰角和rotation旋转角适合需要2.5D视角展示的场景。四、完整可运行Demo高德版以下是一个完整的HTML单文件Demo使用高德地图JS API实现地图展示标记点路线绘制。替换YOUR_KEY和YOUR_SECURITY_CODE即可直接运行!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title地图JS API Demo - 30分钟跑通/title style * { margin: 0; padding: 0; } #container { width: 100%; height: 600px; border: 1px solid #ccc; } .panel { padding: 12px 16px; background: #f5f5f5; border-bottom: 1px solid #ddd; font-family: Microsoft YaHei, sans-serif; } .panel button { margin-right: 8px; padding: 6px 16px; cursor: pointer; border: 1px solid #999; border-radius: 4px; background: #fff; } .panel button:hover { background: #e8e8e8; } /style /head body div classpanel strong地图Demo/strong button onclickaddMarker()添加标记点/button button onclickdrawRoute()绘制路线/button button onclickclearAll()清除全部/button /div div idcontainer/div script // 安全密钥配置2021.12.02后的Key必须配置 window._AMapSecurityConfig { securityJsCode: YOUR_SECURITY_CODE }; /script script srchttps://webapi.amap.com/maps?v2.0keyYOUR_KEY/script script // 初始化地图 var map new AMap.Map(container, { zoom: 11, center: [116.397428, 39.90923], viewMode: 3D }); var overlays []; // 存储所有覆盖物引用 // 添加标记点 function addMarker() { var positions [ [116.397428, 39.90923], [116.427520, 39.938720], [116.346826, 39.867813] ]; positions.forEach(function(pos, index) { var marker new AMap.Marker({ position: new AMap.LngLat(pos[0], pos[1]), title: 标记点 (index 1), label: { content: Point- (index 1), direction: top } }); map.add(marker); overlays.push(marker); }); } // 绘制路线 function drawRoute() { var path [ new AMap.LngLat(116.362209, 39.887487), new AMap.LngLat(116.422897, 39.878002), new AMap.LngLat(116.372154, 39.906724), new AMap.LngLat(116.428945, 39.995826) ]; var polyline new AMap.Polyline({ path: path, strokeColor: #3366FF, strokeWeight: 6, strokeStyle: solid, lineJoin: round, lineCap: round, showDir: true, borderWeight: 1 }); map.add(polyline); overlays.push(polyline); // 自动调整视野以包含路线 map.setFitView([polyline], false, [50, 50, 50, 50]); } // 清除全部覆盖物 function clearAll() { overlays.forEach(function(overlay) { map.remove(overlay); }); overlays []; } /script /body /html其他平台替换关键代码百度地图替换方案script srchttps://api.map.baidu.com/api?typewebglv1.0akYOUR_AK/script script var map new BMapGL.Map(container); map.centerAndZoom(new BMapGL.Point(116.404, 39.915), 11); function addMarker() { var marker new BMapGL.Marker(new BMapGL.Point(116.404, 39.915)); map.addOverlay(marker); } function drawRoute() { var points [ new BMapGL.Point(116.362209, 39.887487), new BMapGL.Point(116.422897, 39.878002), new BMapGL.Point(116.372154, 39.906724) ]; var polyline new BMapGL.Polyline(points, { strokeColor: #3366FF, strokeWeight: 6 }); map.addOverlay(polyline); } /script丰图地图替换方案script srchttps://lbs.sfmap.com.cn/sfmapsdk/map?akYOUR_KEYv3.1/script script // 注意丰图AK需在script URL和初始化参数中同时传入 var map new SFMap.Map(container, { center: new SFMap.LngLat(116.397428, 39.90923), zoom: 11, ak: YOUR_KEY // 此处必须再次传入AK }); function addMarker() { var marker new SFMap.Marker({ position: new SFMap.LngLat(116.397428, 39.90923), map: map }); } function drawRoute() { var path [ new SFMap.LngLat(116.362209, 39.887487), new SFMap.LngLat(116.422897, 39.878002), new SFMap.LngLat(116.372154, 39.906724) ]; var polyline new SFMap.Polyline({ path: path, strokeColor: #3366FF, strokeWeight: 6, map: map }); } /script五、踩坑记录以下是实际接入过程中高频出现的问题及解决方案按踩坑频率排序坑1高德安全密钥未配置导致地图白屏现象页面加载后地图容器为空白控制台报错SecurityError或提示securityJsCode is invalid。原因2021年12月2日起高德对JS API的安全策略升级新创建的Key必须在代码中配置安全密钥。解决方案// 在引入地图JS之前先配置安全密钥 window._AMapSecurityConfig { securityJsCode: 你控制台获取的安全密钥 }安全密钥在高德控制台应用管理→Key对应设置中获取注意不是Key本身而是Key绑定的安全密钥。坑2丰图AK传入不完整导致初始化失败现象地图加载出来但没有瓦片数据或控制台提示权限错误。原因丰图的AK需要双传——既在script URL中传入也在SFMap.Map初始化参数中传入缺一不可。解决方案!-- Script标签中传入AK -- script srchttps://lbs.sfmap.com.cn/sfmapsdk/map?akYOUR_KEYv3.1/script script // 初始化参数中同样传入AK var map new SFMap.Map(container, { ak: YOUR_KEY, // 必须不能省略 center: new SFMap.LngLat(116.397, 39.909), zoom: 11 }); /script坑3丰图REST API的AK传入方式与JS API不同现象用JS API的AK通过URL query参数调用REST接口返回401或鉴权失败。原因丰图REST API要求AK放在请求Header中而非URL参数中。这与JS API的传入方式不同。解决方案// ❌ 错误方式AK放在URL参数 fetch(https://gis-apis.sf-express.com/route?akYOUR_KEYorigin...) // ✅ 正确方式AK放在Header中 fetch(https://gis-apis.sf-express.com/route, { headers: { ak: YOUR_KEY }, // ...其余参数 })这是丰图平台特有的设计与其他三个平台的REST API传参方式有本质区别跨平台迁移时务必注意。坑4百度地图坐标偏移现象标记点与实际位置有几百米偏移尤其在城市密集区域更为明显。原因百度使用独有的BD-09坐标系而GPS设备采集的原始数据通常是WGS-84坐标系其他平台多为GCJ-02坐标系。解决方案方案一使用百度官方提供的坐标转换API将WGS-84/GCJ-02转换为BD-09方案二在项目初期就统一使用GCJ-02坐标存储仅对百度地图做前端转换// 百度坐标转换示例GCJ-02 → BD-09 var gcjPoint new BMapGL.Point(116.404, 39.915); BMapGL.Convertor.translate(gcjPoint, 3, function(point) { // point 就是转换后的BD-09坐标 var marker new BMapGL.Marker(point); map.addOverlay(marker); });坑5地图容器高度为0现象地图初始化无报错但页面上看不到地图。原因地图容器没有设置明确的高度。div idcontainer/div默认高度为0。解决方案#container { width: 100%; height: 500px; /* 必须指定明确高度 */ /* 不能用 height: 100% 除非父容器也有明确高度 */ }这个问题看似简单但在实际开发中非常常见尤其是使用Flex或Grid布局时子元素高度容易被忽略。各平台官方文档是获取最新API参考的最佳来源平台文档地址高德地图 JS API概述-地图 JS API 2.0 | 高德地图API百度地图 JS APIjspopular | 百度地图API SDK腾讯地图 JS API| 腾讯位置服务丰图地图 JS API丰图科技开放平台 - 开发者首选的地图服务商提供行业解决方案建议各平台API版本会持续迭代本文代码基于撰写时的稳定版本。实际接入前建议查阅官方文档确认最新版本号和参数变更。本文通过完整的代码对比帮助开发者在30分钟内完成地图JS API的最小闭环集成。核心要点回顾Script引入注意各平台Key参数名差异key vs ak安全配置高德必须配securityJsCode百度设Referer白名单丰图配域名白名单坐标系百度BD-09与其他平台GCJ-02不同需要转换丰图特殊点AK双传机制REST API的AK放Header容器高度别忘了给地图容器设置明确的CSS高度掌握以上要点后可以快速在不同平台间切换和迁移。后续文章将继续深入各平台的进阶能力包括海量点渲染、自定义图层、热力图等高阶用法。