简介这份资源是面向微信小程序开发者的百度地图 JavaScript API 接口包用于在微信小程序环境中快速接入地图展示、路径规划、地点检索与定位服务等能力适合具备一定小程序开发基础、需要为应用补充地理位置功能的开发者使用。压缩包共35个文件约28KB以js脚本、wxss样式、json配置、wxml模板及png图片为主其中js文件承载核心地图接口逻辑wxss与wxml负责页面结构与样式json用于页面与项目配置整体结构贴合微信小程序的工程规范。目前已有88人学习下载。包内提供bmap-wx.js及其压缩版本并附带demo示例页面与README说明文档读者可参照示例快速完成地图初始化、覆盖物添加、路径规划与周边检索等功能的接入同时借助文档理解接口参数与调用方式降低调试成本为旅游、社交、打车等场景的位置服务开发提供可直接复用的参考实现。1. 百度地图微信小程序 JSAPI 到底能做什么从一次导航失败说起有次在模拟项目里做门店自提页用户点“导航到店”开发者工具里一切正常真机上一按就弹“发起导航失败请前往百度地图确认权限”。这个报错几乎每个接过百度地图微信小程序 JSAPI 的人都见过它暴露的不是代码写错而是整条链路里坐标系、域名白名单、密钥配额、真机权限四件事没对齐。百度地图微信小程序 JSAPI 本质是一套跑在微信小程序环境里的地图能力封装你在 wxml 里放一个 map 组件用 js 调它的上下文对象完成标记、路线、逆地理、步行导航唤起底图瓦片和检索能力由百度侧提供。它适合谁适合要做门店分布、配送轨迹、到店导航、选址看板这类轻量地图场景的小程序团队尤其是已经用百度地图开放平台做过 Web 或车机端、想复用到小程序端的。它不适合做重 GIS 分析也不适合想完全离线跑瓦片的项目。下面按“先跑通、再调参、再避坑”的顺序拆开讲。2. 跑通最小地图页密钥、域名与 map 上下文三件套2.1 申请密钥与配置合法域名百度地图微信小程序 JSAPI 的调用链是小程序请求百度侧接口百度侧校验你的 ak 和当前小程序 appid 是否绑定。所以第一步不是写代码是去开放平台控制台建应用选“微信小程序”类型填上小程序 appid拿到 ak。然后在微信公众平台后台把https://api.map.baidu.com加进 request 合法域名把https://maponline0.bdimg.com这类瓦片域名加进 downloadFile 合法域名。少配一个开发者工具可能因为“不校验合法域名”选项而正常真机直接白屏或报网络错误。提示开发者工具里勾了“不校验合法域名”能跑通不代表真机能跑通这是最常见的自欺欺人。2.2 引入 JSAPI 并初始化地图上下文百度地图微信小程序 JSAPI 不是 npm 包常见做法是把官方提供的bmap-wx.js放到 utils 目录用相对路径 require。下面是最小可运行页面。// pages/map/map.js const BMap require(../../utils/bmap-wx.js) // 官方 JSAPI 文件放 utils 下 Page({ data: { ak: 你的小程序专用ak, // 必须与当前小程序 appid 绑定 markers: [], latitude: 39.915, longitude: 116.404 }, onLoad() { // 实例化百度地图微信小程序 JSAPI 对象 this.bmap new BMap.BMapWX({ ak: this.data.ak }) this.fetchNearby() }, fetchNearby() { const that this // 逆地理 POI 检索验证 ak 与域名是否打通 this.bmap.search({ query: 便利店, location: ${this.data.latitude},${this.data.longitude}, success(res) { const pois res.wxMarkerData || [] that.setData({ markers: pois.map((p, i) ({ id: i, latitude: p.latitude, longitude: p.longitude, title: p.name, iconPath: /images/pin.png, width: 24, height: 24 })) }) }, fail(err) { // 真机失败先看这里err 里通常带状态码 console.error(百度地图检索失败, err) } }) } })逻辑说明BMapWX是 JSAPI 暴露的入口对象构造时传入 aksearch方法内部会请求百度侧检索接口返回的wxMarkerData已经转成了 map 组件 markers 能直接吃的字段。参数说明query是检索关键词location是“纬度,经度”字符串顺序写反会定位到南极附近success回调里的latitude/longitude是百度坐标系bd09ll直接塞给 map 组件没问题但如果你要和自己数据库里的 GPS 坐标叠加必须先转换。2.3 wxml 里 map 组件与上下文的关系!-- pages/map/map.wxml -- map idshopMap latitude{{latitude}} longitude{{longitude}} markers{{markers}} scale14 show-location stylewidth: 100%; height: 60vh; /map这里有个容易混的点map 组件本身是微信原生组件百度地图 JSAPI 负责的是“数据与能力”不是替换这个组件。也就是说底图渲染仍走微信侧百度侧提供检索、路线、逆地理这些接口。理解这一点后面排查“地图能显示但标记不出来”就有方向了——底图正常说明组件没问题标记不出来基本是 JSAPI 请求失败。3. 把导航、路线和坐标转换接进业务页3.1 唤起百度地图 App 导航的正确姿势“发起导航失败请前往百度地图确认权限”这个报错九成出在wx.openLocation或 JSAPI 导航接口的坐标系与权限上。微信小程序唤起外部导航稳妥做法是用wx.openLocation它接受的是 gcj02 坐标。// 从门店数据唤起导航 goNavigate(e) { const shop e.currentTarget.dataset.shop // 假设后台存的是 bd09ll先转 gcj02 const gcj this.bd09ToGcj02(shop.lat, shop.lng) wx.openLocation({ latitude: gcj.lat, longitude: gcj.lng, name: shop.name, address: shop.address, scale: 18, fail(err) { // 真机上这里才会暴露权限或坐标问题 wx.showToast({ title: 导航唤起失败, icon: none }) console.error(err) } }) }参数说明latitude/longitude必须是 gcj02传 bd09ll 会偏移几百米name/address是展示用不影响定位scale控制缩放级别。真机失败常见原因是用户没装地图类 App或系统权限里定位被关。开发者工具里wx.openLocation行为与真机不一致别拿工具结果当结论。3.2 坐标转换bd09ll、gcj02、wgs84 三者别混用百度地图 JSAPI 返回的是 bd09ll微信wx.openLocation和wx.getLocation默认是 gcj02GPS 原始是 wgs84。三者混用就是“标记飘到河里”的元凶。下面是一段常用的 bd09 转 gcj02。// utils/coord.js const X_PI (Math.PI * 3000.0) / 180.0 function bd09ToGcj02(bdLat, bdLng) { const x bdLng - 0.0065 const y bdLat - 0.006 const z Math.sqrt(x * x y * y) - 0.00002 * Math.sin(y * X_PI) const theta Math.atan2(y, x) - 0.000003 * Math.cos(x * X_PI) return { lng: z * Math.cos(theta), lat: z * Math.sin(theta) } } module.exports { bd09ToGcj02 }逻辑说明这是公开的近似转换公式精度在米级够门店导航用。参数说明入参是百度经纬度出参是 gcj02。如果你要做配送轨迹回放建议统一在入库时就转成 gcj02别等到渲染再转否则每条轨迹都要算一遍还容易漏。3.3 用 JSAPI 做逆地理与步行路线逆地理是把经纬度换成地址步行路线是给“最后 500 米”用的。这两个能力在 JSAPI 里都有封装调用方式和 2.2 的 search 类似。// 逆地理坐标转地址 this.bmap.geocoder({ location: ${lat},${lng}, success(res) { // res.result 里含 addressComponent console.log(res.result.addressComponent.district) } }) // 步行路线起点到终点 this.bmap.walkRoute({ origin: ${fromLat},${fromLng}, destination: ${toLat},${toLng}, success(res) { // res.result.routes[0].steps 是分段指引 console.log(res.result.routes[0].distance) } })参数说明origin/destination都是“纬度,经度”且必须是 bd09llwalkRoute返回的 steps 里含 instruction 和 distance可以直接渲染成步骤列表。注意这两个接口都算配额别在 onShow 里无脑调容易把日配额刷爆。4. 避坑与排查真机、配额、坐标系、组件层级4.1 开发者工具正常、真机接口失败现象工具里检索、逆地理都返回数据真机一片空白或报网络错误。原因request 合法域名没配全或 ak 没绑定当前小程序 appid。解决把api.map.baidu.com加进 request 域名确认开放平台里应用类型选的是微信小程序且 appid 一致。改完要重新编译真机预览才会生效。4.2 标记偏移几百米现象marker 落在马路对面或河里。原因bd09ll 和 gcj02 混用或location参数里经纬度顺序写反。解决统一坐标系入库转 gcj02渲染前确认顺序是“纬度,经度”。用 3.2 的转换函数过一遍再对比。4.3 日配额被刷爆现象某天下午开始所有接口返回配额超限。原因在 onShow、onPageScroll 这类高频钩子里调检索或逆地理。解决加节流把结果缓存到 data 或本地 storage同一坐标短时间内不重复请求。配额是按接口分的逆地理和检索各自独立别只看一个。4.4 map 组件被原生层级盖住现象自定义弹窗、悬浮按钮在真机上被地图盖住。原因map 是原生组件层级最高。解决用 cover-view 包住需要浮在地图上的元素或把弹窗做成独立页面。这是微信小程序原生组件的通用限制不是百度地图 JSAPI 的问题。4.5 导航唤起失败但没报错现象点导航没反应fail 回调也不进。原因部分机型对wx.openLocation的权限校验在系统层失败时静默。解决在调用前用wx.getSetting查定位权限没授权先引导授权同时给按钮加 loading 态避免用户重复点。5. 进阶把 JSAPI 包成可复用模块与验证清单到这一步最小页能跑导航能唤起坐标也统一了。接下来值得做的是把 JSAPI 包成一个业务无关的模块让门店页、配送页、选址页共用。我一般会建一个utils/mapService.js对外只暴露searchNearby、geocode、walkRoute、openNavigation四个方法内部统一处理 ak、坐标系转换、节流和错误上报。这样换 ak 或换坐标系时只改一处不会满项目找new BMapWX。验证清单我习惯按下面这张表过一遍每次发版前跑一次比事后救火省事。检查项验证方式通过标准ak 与 appid 绑定真机调一次 search返回 wxMarkerData 非空request 域名真机看 network无“不在合法域名列表”报错坐标系标记与门店实际位置对比偏移小于 50 米导航唤起真机点导航按钮能拉起地图 App 并定位到店配额看开放平台用量日用量低于配额 70%原生层级真机看悬浮元素不被地图盖住最后说个我自己的习惯每次接百度地图微信小程序 JSAPI先不写业务只写一个“打点页”——一个按钮调 search一个按钮调 geocoder一个按钮调 openLocation三个都真机通过再动业务代码。这个页我留了三年换项目直接复制比看文档快。血泪经验是地图类问题八成不是代码逻辑是配置和坐标系先把这两样对齐后面都是体力活。希望帮到你。本文还有配套的精品资源点击获取