简介这份微信小程序地图 demo 面向移动端小程序开发者以完整可运行的示例工程演示如何在微信小程序中集成地图组件、添加自定义气泡标签以及通过 addPolyline 按地理坐标绘制两点间线路适合初学地图组件、希望快速搭建地图页面的开发者参考。资源共 24 个文件压缩包仅 296KB其中 6 个 JS 承载页面逻辑和地图 API 调用4 个 WXML 与 5 个 WXSS 分别负责页面结构与样式4 个 JSON 管理全局和页面配置另含少量示例图片与辅助模块目录清晰便于局部查阅。项目已有 568 人学习下载核心代码覆盖 wx.createMapContext、marker 的 callout 气泡配置、polyline 折线绘制等关键写法并包含 toast 提示与工具类等可复用部分。借助这份示例读者可以快速搭出地图应用骨架在此基础上继续扩展实时定位、标记交互与路径规划等功能。1. 微信小程序地图 demo十分钟能跑但定位和 marker 才是真门槛如果你打开这份微信小程序地图 demo第一反应大概率是“就这么点代码也值得打包”但真自己从零写一遍地图页你会在定位授权、坐标系、marker 更新和路线规划四个地方反复翻车。这个资源的核心价值不是地图渲染——map 组件本来就是现成的——而是它把从授权拿坐标到地图上画点、画路线、做交互的这一整条链路替你跑通了一遍。适合三类人刚接触小程序地图开发的新手、要给现有项目快速加地图模块的开发者、以及想找一份能直接改参数复用的地图功能代码的人。下面按我从这份 demo 里拆出来的关键链路逐段说连参数和坑一起。2. 定位与坐标获取getLocation 的授权流程和坐标系选择2.1 授权不是 wx.getLocation 一个 API 的事很多初学者以为调一下 wx.getLocation 就能拿到坐标实际跑起来才会发现第一次调用会弹授权框用户拒绝后第二次直接进 fail 回调而且此时 wx.authorize 也救不回来。这份 demo 的做法是先检查 wx.getSetting再用 wx.authorize 提前申请 scope.userLocation最后才调 wx.getLocation——三步缺一不可。// app.json 里需要声明 // permission: { // scope.userLocation: { // desc: 你的位置信息将用于地图定位展示 // } // } Page({ onLoad() { this.initLocation(); }, async initLocation() { // 第一步检查是否已授权 const setting await wx.getSetting(); if (setting.authSetting[scope.userLocation]) { this.getLocation(); return; } // 第二步主动发起授权避免首次调用 getLocation 时被动弹窗 const authRes await wx.authorize({ scope: scope.userLocation }); if (authRes.errMsg.includes(ok)) { this.getLocation(); } else { wx.showModal({ title: 提示, content: 需要定位权限才能显示地图位置, confirmText: 去设置, success: (res) { if (res.confirm) wx.openSetting(); } }); } }, getLocation() { wx.getLocation({ type: gcj02, // 国测局坐标直接给 map 组件用 isHighAccuracy: true, highAccuracyExpireTime: 3000, success: (res) { this.setData({ latitude: res.latitude, longitude: res.longitude }); }, fail: (err) console.error(定位失败, err) }); } });这里有两个逻辑要点。第一wx.getSetting 必须放在 wx.authorize 之前否则用户已经拒绝过后你再次 authorize 会直接走 fail。第二type 参数我默认写 gcj02——国内地图坐标体系map 组件直接消费如果后端要做距离计算或对接国外地图才需要考虑 wgs84。参数方面isHighAccuracy 在 Android 上会触发 GPS 辅助定位响应会慢一些但精度更好highAccuracyExpireTime 是精度衰减的过期时间超过这个毫秒数后会退出高精度模式。实际跑 demo 时如果发现定位结果偏离几百米优先检查是不是 type 写错了或者手机没开 GPS 开关。2.2 关于坐标系gcj02 和 wgs84 的差异不是文档里那两句话文档只说 type 支持 wgs84 和 gcj02但没说混用的后果。我见过有人把后端返回的 wgs84 坐标直接丢给 map 组件结果地图上的点偏了大概 200 到 500 米——在市区道路场景下直接偏到隔壁街。这份 demo 内部统一用的 gcj02如果后端需要 wgs84可以在传给地图前做一次转换。坐标系混用是地图开发里最隐蔽的坑比 API 调用失败难排查得多。提示在国内用 map 组件入参坐标必须是 gcj02。如果你从第三方服务拿到的坐标是 wgs84先转换再渲染别图省事直接塞给地图。3. map 组件初始化center、scale 和 markers 的绑定逻辑3.1 center 不是只设一次就完事map 组件的 center 参数有两个特点一是初始加载时必须同时给 latitude 和 longitude缺一个地图就黑屏二是后续如果想移动视野不能只改 setData 里的 latitude那样地图会按原有缩放级别做一个生硬的视角跳变没有平移动画。控制地图视野正确的方式是用 MapContext 的 moveToLocation 或 translateMarker。demo 里的做法比较直接在 onLoad 阶段拿到定位后一次性把 latitude、longitude、scale 一起 setData之后不再单独修改 center。data: { latitude: 39.908823, // 默认值避免 map 组件首次渲染时为 undefined longitude: 116.397470, scale: 16, markers: [] }, onReady() { // 获取 map 上下文后续控制视野都走这个实例 this.mapCtx wx.createMapContext(map, this); // 等定位更新后再把视野移到当前坐标 this.updateCenter(); }, updateCenter() { this.mapCtx.moveToLocation({ latitude: this.data.latitude, longitude: this.data.longitude }); }这里 key 点在于给初始数据设置默认经纬度。map 组件如果第一次渲染时拿不到 center 坐标不会报错但会渲染成一张空白网格地图很多新人会误以为是 key 或域名配置问题。做法上我在写类似功能时习惯给 latitude 和 longitude 一个城市中心坐标做兜底然后等定位成功后再移动视野。scale 参数范围是 3 到 2016 对应街道级别能看到街区和小路如果做城市级别的点分布展示scale 放到 11 到 13 更合适。moveToLocation 不带参数时会默认移动到当前位置但显式传经纬度更稳妥——尤其是当你要把视野切到某个业务坐标如店铺位置而非用户位置时。3.2 markers 数据绑定数组更新是重灾区map 组件上的 markers 接收的是数组但这份 demo 里踩过一个大坑直接 push 到 this.data.markers 再 setData 不会生效。原因是 setData 的 diff 机制对数组的原生方法修改不敏感你必须重新构造一个新数组再赋值。另外 markers 里每个对象的 id 是必填项controls、circles 里也有类似要求——id 缺了点击事件和更新操作都会失灵。addMarker(point) { // 错误做法this.data.markers.push(point) 然后 setData(markers, this.data.markers) // 正确做法生成新数组 const newMarkers this.data.markers.concat([{ id: Date.now(), // 必填唯一标识 latitude: point.latitude, longitude: point.longitude, title: point.title, iconPath: /assets/marker.png, // 自定义图标路径不能是网络地址 width: 30, height: 30, callout: { content: point.title, color: #333333, fontSize: 13, borderRadius: 4, bgColor: #ffffff, padding: 6, display: BYCLICK // 点击才显示气泡默认是 BYCLICK }, label: { content: point.title, color: #000000, anchorX: -20, anchorY: -30 } }]); this.setData({ markers: newMarkers }); }参数说明集中在 iconPath、callout 和 label 三块。iconPath 不能用网络 URL只能放本地路径或 base64callout 的 display 支持 BYCLICK 和 ALWAYS 两种ALWAYS 会一直显示气泡适合标注少量关键点label 和 callout 的区别是 label 是文字标签贴在 marker 旁边而 callout 是气泡样式能加背景色和圆角。data 里的 markers 如果超过几十个建议用 includePoints 批量调整视野而不是手动算 scale——后面第 4 章会展开。4. 交互与路线规划marker 点击、includePoints 和 polyline 的实现4.1 marker 点击事件和 bindcallouttap 的配合demo 里给 map 组件挂了 bindmarkertap 和 bindcallouttap 两个事件。bindmarkertap 在点击 marker 图标时触发bindcallouttap 在点击气泡时触发。两者的回调参数里都带 markerId通过它找到对应的业务数据。这里要注意如果 marker 没有配 calloutbindcallouttap 永远不会触发如果配了 callout 但不设 id触发后你也不知道点的是哪个 marker。onMarkerTap(e) { const { markerId } e.detail; const marker this.data.markers.find(item item.id markerId); if (!marker) return; // 点击 marker 后移动到该点并放大地图 this.mapCtx.moveToLocation({ latitude: marker.latitude, longitude: marker.longitude }); this.mapCtx.setScale({ scale: 18 }); // 注意 setScale 不是 scale wx.showModal({ title: marker.title, content: 坐标${marker.latitude.toFixed(6)}, ${marker.longitude.toFixed(6)}, showCancel: false }); }, onCalloutTap(e) { const { markerId } e.detail; wx.showToast({ title: 气泡点击 ${markerId}, icon: none }); }说说 MapContext 的几个方法。moveToLocation 移动视野中心setScale 改缩放级别——缩放的基准点默认是地图中心不会因为某个 marker 的位置而调整。如果想让视野同时包含多个 marker用 includePoints 更合适它会自动算出一个包含所有点的视野边界和缩放级别比起手动算经纬度范围再 setScale 要省事得多。onMarkerTap 里我用的是 moveToLocation 加 setScale 的组合因为只关注单个点。如果是多个点的视野适配直接走 includePoints。4.2 includePoints 适配视野polyline 画路线includePoints 接收一个 points 数组框架会自己计算视野范围不需要你去想 scale 设多少。它和 moveToLocation 的区别是moveToLocation 是以某点为视野中心includePoints 是让这些点都在视野内。两者常常组合使用区域概览用 includePoints点击某个 marker 后用 moveToLocation 聚焦。fitAllMarkers() { if (!this.data.markers.length) return; this.mapCtx.includePoints({ points: this.data.markers.map(m ({ latitude: m.latitude, longitude: m.longitude })), padding: [60, 60, 60, 60] // 上、右、下、左的边距单位 px }); }, drawRoute(destLat, destLng) { const route [{ latitude: this.data.latitude, longitude: this.data.longitude }, { latitude: destLat, longitude: destLng }]; this.setData({ polyline: [{ points: route, color: #1E90FF, width: 6, dottedLine: false, arrowLine: true // 沿线绘制箭头指向前进方向 }] }); }polyline 的 points 至少要有两个点否则不渲染。color 用的是十六进制width 单位是像素。dottedLine 是虚线——在模拟器上看不出来真机上和箭头的兼容性也一般所以 demo 里直接关掉。arrowLine 画出来的箭头是等距分布在路线上的小箭头比较适合导航语义如果只是静态展示路径可以不开。polyline 数组也是和 markers 一样的更新原则——整体 replace不要原地 push。5. 避坑与排查地图 demo 跑不通的五个常见原因5.1 现象地图组件一片空白连网格都没有原因map 组件的经纬度没给初始值或者给了 null/undefined。解决在 data 里预置默认坐标我在第 3 章代码里已经写了一份默认值。这个坑在真机上不一定会暴露因为定位可能很快但开发者工具冷启动时经常能看到空白地图一闪而过。预防办法就是始终有兜底坐标。5.2 现象wx.getLocation 一直走 failerrMsg 是 getLocation:fail the api need to be declared in requiredPrivateInfos field原因这是真机调试最常见的翻车原因。基础库 2.25.0 之后getLocation 需要在 app.json 里声明 requiredPrivateInfos: [getLocation]不声明直接报错而且开发者工具里不报、真机上才报。解决在 app.json 里加 requiredPrivateInfos 配置同时确认 permission 字段也写好了 scope.userLocation 的说明。这个坑文档里写得比较靠后很多人都是报错后搜半天才看到。注意配置 requiredPrivateInfos 后小程序需要重新编译才能生效。在开发者工具里改了 app.json 但没重新编译会以为配置没起作用。5.3 现象marker 显示出来了但点击事件不触发原因marker 对象里没写 id。map 组件的点击事件靠 markerId 区分目标id 缺失时事件可能直接中断。解决每次生成 marker 时用 Date.now() 或自增计数器保证 id 唯一。另外检查 bindmarkertap 是不是写在 map 标签上而不是内部某个 view 上——事件绑定位置错了也触发不了。5.4 现象真机上定位偏差几百米模拟器上却完全正常原因开发工具用的是 IP 定位精度能到街区级就不错了真机定位结果取决于 GPS 和网络辅助定位的配合。解决确认 getLocation 的 type 为 gcj02isHighAccuracy 设 true检查手机定位服务是否开启Android 上还要确认 App 的定位权限是仅使用时允许。我在调试这种问题时习惯先用系统自带地图定位看手机本身定位准不准排除硬件因素再查代码。5.5 现象marker 更新了但地图上的旧 marker 还在原因setData 传了新的 markers 数组但新数组里的 id 和旧数组里的 id 有重复map 组件会认为这是同一个 marker复用旧状态。解决更新 marker 时确保 id 全新生成。这条坑发生在点一个按钮往现有 markers 里追加一个点的场景——如果 id 用固定的 1、2、3第二次追加时 id 重复旧点被覆盖而不是新增。用时间戳做 id 基本能避免。6. 把 demo 往前再推一步通过用户偏好动态调整 scale 并联动视野map 组件默认的 scale 是 16但不同业务场景需要的 scale 不一样——展示几个门店需要能看清街道展示城市范围内的点位则要看到全貌。demo 的 scale 是写死的我在复用它时做了一件事把 scale 的选择权交给数据量让视野自适应。calculateScale(markerCount) { if (markerCount 1) return 16; if (markerCount 3) return 14; if (markerCount 6) return 12; return 10; // 点多就缩小视野看全局 }, refreshMapView() { const markers this.data.markers; const nextScale this.calculateScale(markers.length); this.mapCtx.setScale({ scale: nextScale }); this.mapCtx.includePoints({ points: markers.map(m ({ latitude: m.latitude, longitude: m.longitude })), padding: [50, 50, 50, 50] }); }这个逻辑的落点是每次 markers 数据变化后调用 refreshMapView视野先按数量级调整 scale再用 includePoints 框住所有点。你会发现 setScale 和 includePoints 连续调用不会冲突——includePoints 本来就会覆盖视野范围scale 只是先给了个初始缩放。这套做法我之前在某跨平台系统里用过数据从 2 个点涨到 50 个点时视野不会突然缩到看不到细节也不会因为点太少拉得太远。另外还有一个容易忽略的细节setScale 是异步的紧接着调用 includePoints 时地图可能还在上一次的状态里。如果不能接受这个跳变可以把 includePoints 放进 setScale 的 success 回调里或者反过来先 includePoints 再根据回调里的 scale 微调。我一般先 includePoints 后不管 scale——它自己算出来的视野通常比手动指定的合理。从那以后我每次写地图页都强制走一遍这套流程先确认坐标系统一为 gcj02再检查 requiredPrivateInfos 和 permission 配齐然后才写 map 组件和 markers 的绑定。地图开发的问题大多不在渲染而在数据链路——这条经验从这份 demo 里验证过无数次了希望帮到你。本文还有配套的精品资源点击获取