简介：这份资源是面向微信小程序开发者的百度地图 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 暴露的入口对象，构造时传入 ak；search方法内部会请求百度侧检索接口，返回的wxMarkerData已经转成了 map 组件 markers 能直接吃的字段。参数说明：query是检索关键词，location是“纬度,经度”字符串，顺序写反会定位到南极附近；success回调里的latitude/longitude是百度坐标系（bd09ll），直接塞给 map 组件没问题，但如果你要和自己数据库里的 GPS 坐标叠加，必须先转换。
2.3 wxml 里 map 组件与上下文的关系
<!-- pages/map/map.wxml --> <map id="shopMap" latitude="{{latitude}}" longitude="{{longitude}}" markers="{{markers}}" scale="14" show-location style="width: 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默认是 gcj02，GPS 原始是 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都是“纬度,经度”，且必须是 bd09ll；walkRoute返回的 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，三个都真机通过再动业务代码。这个页我留了三年，换项目直接复制，比看文档快。血泪经验是，地图类问题八成不是代码逻辑，是配置和坐标系，先把这两样对齐，后面都是体力活。希望帮到你。
本文还有配套的精品资源，点击获取
