简介这份资源是面向微信小程序开发者的百度地图 JavaScript API 接口包适合需要在轻量级小程序中嵌入地图能力的初中级前端开发者用于解决地图展示、定位、路径规划与地点检索等常见需求。压缩包共35个文件约28KB以js脚本、wxss样式、json配置、wxml模板和png图片为主其中bmap-wx.js与压缩版构成核心调用逻辑配套的app.json、app.js及pages目录则给出可直接参考的示例工程结构另有README.md说明文档辅助上手。目前已有88人学习下载。借助包内接口开发者可在小程序内实现标记点、线段、多边形等覆盖物绘制以及驾车导航、公交查询、周边检索和实时位置分享等进阶功能配合官方文档中的参数定义与调用示例能较快完成从环境引入到功能落地的过程为旅游、社交、打车等场景提供稳定的地理位置服务支撑。1. 百度地图微信小程序 JSAPI 接入从零跑通一个能定位、能选点的地图页很多团队第一次做微信小程序地图都会卡在同一个地方小程序原生map组件能显示地图但一旦要做「拖动选点、逆地理编码、周边搜索、路线规划」原生组件的能力就不够用了。这时候百度地图微信小程序 JSAPI 就成了一个绕不开的选项——它把 Web 端那套成熟的定位、检索、算路能力封装成小程序能直接调用的 SDK你不需要自己搭后端转发也不用去啃各家坐标系转换的细节。这篇笔记讲的就是怎么把这个 JSAPI 真正落地从申请密钥、配置合法域名到封装一个可复用的地图工具模块再到逆地理编码、POI 检索、路线规划这几个高频场景的完整代码。适合两类人一类是刚接手小程序地图需求、想快速跑通最小可用版本的开发者另一类是已经用了原生组件、但被「选点精度」「地址回填」折磨过、想换一套更完整方案的人。下面所有代码都是可以直接抄进项目里改参数用的坑我也一并标出来。2. 接入前的三件事密钥、域名与坐标系2.1 为什么不能直接在小程序里用 Web 版 JSAPI百度地图 Web 端的 JSAPI 依赖window、document这些浏览器对象而微信小程序的逻辑层运行在一个没有 DOM 的 JS 引擎里两者根本不是一套运行环境。所以官方单独出了一套小程序版 SDK它把地图渲染交给小程序的map组件把定位、检索、算路这些能力做成纯 JS 接口通过request走 HTTPS 请求百度地图的服务端。这里有个关键认知小程序版 JSAPI 并不是「把地图画出来」的库地图渲染始终是小程序原生map组件干的活SDK 负责的是「数据」——坐标、地址、POI、路线。理解这一点后面很多设计就顺了你要在map组件上叠加标记标记的坐标得由 SDK 算出来你要做选点得监听map的regionchange事件再把中心点坐标丢给 SDK 做逆地理编码。常见做法是新建一个libs目录放 SDK 文件再建一个utils目录放自己的封装。目录结构大概长这样project/ ├── libs/ │ └── bmap-wx.js // 百度地图小程序 SDK ├── utils/ │ └── mapHelper.js // 自己的封装 ├── pages/ │ └── map/ │ ├── map.js │ ├── map.wxml │ └── map.json2.2 申请密钥与配置 request 合法域名第一步是去百度地图开放平台创建应用应用类型选「微信小程序」填上小程序的 AppID拿到一个 AKAccess Key。这个 AK 是后面所有接口的通行证泄露了别人就能拿你的额度刷请求所以别硬编码在会提交到公开仓库的文件里。拿到 AK 之后微信这边还要放行请求域名。小程序的网络请求有白名单机制没配的域名一律请求失败。百度地图小程序 SDK 主要走这两个域名用途域名主服务接口https://api.map.baidu.com部分静态资源https://maponline0.bdimg.com配置位置在微信公众平台后台「开发管理 → 开发设置 → 服务器域名 → request 合法域名」把上面两个加进去。注意必须用 HTTPS且不能带路径只填到域名。提示开发阶段可以在微信开发者工具里勾选「不校验合法域名」但上线前一定要配好否则真机上直接请求失败而且报错信息很含糊容易误判成 AK 问题。2.3 坐标系这件事绕不过去国内地图服务涉及三套坐标系GPS 原始坐标WGS84、国测局加密坐标GCJ02、百度自有坐标BD09。微信小程序的wx.getLocation默认返回的是 GCJ02而百度地图 SDK 内部用的是 BD09。如果你直接把wx.getLocation的经纬度丢给百度 SDK 去标点位置会偏几百米——这就是很多人遇到的「定位点飘到马路对面」的玄学问题。解决办法有两个一是调用 SDK 提供的坐标转换接口把 GCJ02 转成 BD09二是让 SDK 自己去做转换。我一般会在封装层统一处理所有外部传入的坐标先转成 BD09 再进 SDK避免每个调用点都记一遍。转换接口后面会给代码。3. 封装一个可复用的地图工具模块3.1 初始化 SDK 与全局单例SDK 初始化只需要一次重复初始化会浪费内存也可能导致回调错乱。我习惯在mapHelper.js里做一个惰性单例第一次调用时才创建实例。// utils/mapHelper.js const BMap require(../libs/bmap-wx.js); let instance null; /** * 获取 SDK 单例 * param {string} ak 百度地图 AK * returns {object} SDK 实例 */ function getInstance(ak) { if (!instance) { instance new BMap.BMapWX({ ak: ak }); } return instance; } module.exports { getInstance };逻辑说明BMapWX是 SDK 暴露的构造函数传入ak后返回的实例上挂着geocoder、search、suggestion等能力对象。用单例是因为这些能力对象内部会维护一些状态多次 new 出来各自为政回调容易串。参数只有一个ak从配置里读不要写死。3.2 逆地理编码把坐标变成人能看懂的地址逆地理编码是选点场景的核心用户拖动地图中心点坐标一直在变你要实时把这个坐标翻译成「XX 路 XX 号」这样的地址回填到输入框。// utils/mapHelper.js 续 const BMap require(../libs/bmap-wx.js); /** * 逆地理编码坐标 - 地址 * param {object} sdk SDK 实例 * param {number} latitude 纬度BD09 * param {number} longitude 经度BD09 * returns {Promiseobject} 地址信息 */ function reverseGeocode(sdk, latitude, longitude) { return new Promise((resolve, reject) { sdk.geocoder({ location: ${latitude},${longitude}, success(res) { // res 里包含 formatted_address、business 等字段 resolve(res); }, fail(err) { reject(err); } }); }); } module.exports { getInstance, reverseGeocode };逻辑说明geocoder接收的location是「纬度,经度」的字符串顺序不能反反了会返回空结果或者错误地址。success回调里的res结构大致是{ formatted_address, business, addressComponent }其中formatted_address是完整地址addressComponent里有省市区街道分级信息做地址回填时通常用formatted_address就够。参数上唯一要注意的是坐标必须是 BD09。如果你手上是wx.getLocation拿到的 GCJ02得先转。转换接口在 SDK 里叫convertor用法是传from、to和坐标数组这里不展开思路是统一在调用reverseGeocode之前转好。3.3 监听地图拖动做防抖选点页最怕的就是用户每拖一下都发一次请求既费额度又卡。正确做法是监听map组件的regionchange事件等用户停下来再请求。// pages/map/map.js const mapHelper require(../../utils/mapHelper.js); const AK 你的AK; Page({ data: { latitude: 39.915, longitude: 116.404, address: , markers: [] }, onLoad() { this.sdk mapHelper.getInstance(AK); this.timer null; }, // 地图区域变化 onRegionChange(e) { // 只在拖动结束时处理避免过程中频繁触发 if (e.type ! end) return; // 防抖300ms 内只发一次 clearTimeout(this.timer); this.timer setTimeout(() { this.fetchCenterAddress(); }, 300); }, // 获取地图中心点并逆地理编码 fetchCenterAddress() { const mapCtx wx.createMapContext(myMap); mapCtx.getCenterLocation({ success: (res) { mapHelper.reverseGeocode(this.sdk, res.latitude, res.longitude) .then((data) { this.setData({ latitude: res.latitude, longitude: res.longitude, address: data.formatted_address }); }) .catch((err) { console.error(逆地理编码失败, err); }); } }); } });逻辑说明regionchange事件的type有begin和end两种只在end时处理能省掉大量中间态请求。getCenterLocation是小程序原生MapContext的方法拿到的坐标是 GCJ02严格来说这里应该先转 BD09 再传给reverseGeocode示例里为了突出主流程省略了转换实际项目务必补上。防抖时间 300ms 是个经验值太短用户还没停稳就发请求太长地址回填有明显延迟感。如果地图上还要显示标记可以在setData里同步更新markers标记坐标用同一个中心点即可。4. POI 检索与路线规划把「附近」和「怎么走」做出来4.1 周边检索找附近的加油站、餐厅POI 检索分两种一种是以某个坐标为中心搜周边一种是按关键词搜全城。选点场景常用前者。// utils/mapHelper.js 续 /** * 周边 POI 检索 * param {object} sdk SDK 实例 * param {string} keyword 关键词如「加油站」 * param {number} latitude 中心点纬度 * param {number} longitude 中心点经度 * param {number} radius 搜索半径单位米 * returns {PromiseArray} POI 列表 */ function searchNearby(sdk, keyword, latitude, longitude, radius 1000) { return new Promise((resolve, reject) { sdk.search({ query: keyword, location: ${latitude},${longitude}, radius: radius, success(res) { // res 里 originalData 才是真正的 POI 数组 resolve(res.originalData || []); }, fail(err) { reject(err); } }); }); }逻辑说明search的query是关键词location同样是「纬度,经度」radius是半径。返回结构里有个坑res本身不是数组真正的 POI 列表在res.originalData里每一项包含title、address、location含lat、lng等字段。很多人第一次用直接遍历res会拿到一堆 undefined就是没注意这层包装。半径参数别设太大超过 5000 米结果会稀疏且不准一般 1000 到 3000 米比较合适。如果要做分页SDK 的search支持page和pageCapacity但小程序场景下用户很少翻很多页通常取前 20 条就够。4.2 路线规划驾车、步行、骑行路线规划接口返回的是路径点序列你要自己把它画到map组件的polyline上。// utils/mapHelper.js 续 /** * 驾车路线规划 * param {object} sdk SDK 实例 * param {object} from {latitude, longitude} * param {object} to {latitude, longitude} * returns {Promiseobject} 路线数据 */ function drivingRoute(sdk, from, to) { return new Promise((resolve, reject) { sdk.driving({ from: ${from.latitude},${from.longitude}, to: ${to.latitude},${to.longitude}, success(res) { resolve(res); }, fail(err) { reject(err); } }); }); }逻辑说明driving的from和to都是「纬度,经度」字符串。返回的res里通常有routes数组每条路线包含steps每个 step 里有path点序列。要把路线画出来需要把这些点抽出来拼成一个坐标数组再转成polyline需要的格式// 把路线数据转成 polyline 需要的点数组 function routeToPolyline(routeData) { const points []; const routes routeData.routes || []; if (routes.length 0) return points; routes[0].steps.forEach((step) { step.path.forEach((p) { points.push({ latitude: p.lat, longitude: p.lng }); }); }); return points; }参数上driving还支持waypoints途经点和policy算路策略比如避开高速。步行和骑行分别是walking和riding用法一致。注意路线规划返回的点也是 BD09直接喂给polyline即可不用再转。4.3 把检索结果标到地图上拿到 POI 列表后要转成map组件的markers格式// 把 POI 列表转成 markers function poiToMarkers(poiList) { return poiList.map((poi, index) ({ id: index, latitude: poi.location.lat, longitude: poi.location.lng, title: poi.title, width: 24, height: 24, callout: { content: poi.title, display: BYCLICK, padding: 6, borderRadius: 4 } })); }逻辑说明markers每项必须有id、latitude、longitudeid要唯一用索引即可。callout是点击标记时弹出的气泡display: BYCLICK表示点击才显示避免地图上全是气泡糊成一片。width和height控制图标大小不设的话默认图标可能过大。5. 避坑与排查那些让我返工三次的问题5.1 定位点偏移几百米现象用wx.getLocation拿到的坐标直接标点位置明显偏有时偏到河对岸。原因wx.getLocation返回 GCJ02百度 SDK 用 BD09两套坐标系不兼容。解决在调用任何百度接口前先用 SDK 的坐标转换能力把 GCJ02 转成 BD09。如果懒得转也可以在wx.getLocation里指定type: gcj02后自己写转换公式但更稳的是用 SDK 自带的转换接口避免公式写错。5.2 逆地理编码返回空地址现象geocoder的success回调里formatted_address是空字符串。原因八成是location的经纬度顺序写反了或者传了 GCJ02 坐标。百度接口对顺序敏感纬度在前经度在后。解决打印一下传给geocoder的location字符串确认是「纬度,经度」且坐标是 BD09。另外海上、荒漠等区域本身就没有地址数据返回空是正常的要做兜底提示。5.3 真机上请求全部失败开发者工具却正常现象开发者工具里一切正常真机预览时所有地图接口报错。原因request 合法域名没配或者配了但没生效有缓存。解决去公众平台确认api.map.baidu.com已加入白名单然后重新编译、清缓存。真机调试时可以在vConsole里看具体报错如果是url not in domain list就是域名问题。5.4 POI 检索结果为空但关键词没错现象搜「加油站」返回空数组换个词又能搜到。原因radius设得太小或者中心点坐标本身有问题比如传了 GCJ02。解决先把radius调到 3000 试再确认坐标。另外百度对某些敏感或冷门关键词会限流返回空不一定是代码问题换个通用词验证一下接口通不通。5.5 地图拖动时页面卡顿现象拖动地图时掉帧地址回填延迟明显。原因regionchange触发太频繁每次都setData大对象。解决只在type end时处理加防抖setData只更新变化的字段别整个data重设。如果标记很多考虑用includePoints一次性调整视野而不是逐个更新。6. 进阶把地图能力抽成独立模块的几个技巧做到这里基本功能已经能跑了。但如果你要在多个页面复用或者团队里其他人也要用就得再往前走一步把地图能力抽成一个不依赖具体页面的模块。我的习惯是定义一个MapService类把 AK、SDK 实例、常用方法都收进去页面只调方法不碰 SDK。这样换 AK、加缓存、改超时都只改一个地方。下面是一个精简版// utils/mapService.js const BMap require(../libs/bmap-wx.js); class MapService { constructor(ak) { this.sdk new BMap.BMapWX({ ak }); this.cache new Map(); // 简单的地址缓存 } // 带缓存的逆地理编码 async geocode(lat, lng) { const key ${lat.toFixed(5)},${lng.toFixed(5)}; if (this.cache.has(key)) { return this.cache.get(key); } const result await new Promise((resolve, reject) { this.sdk.geocoder({ location: ${lat},${lng}, success: resolve, fail: reject }); }); this.cache.set(key, result); return result; } // 周边搜索统一返回精简结构 async nearby(keyword, lat, lng, radius 1000) { const res await new Promise((resolve, reject) { this.sdk.search({ query: keyword, location: ${lat},${lng}, radius, success: resolve, fail: reject }); }); return (res.originalData || []).map((poi) ({ title: poi.title, address: poi.address, latitude: poi.location.lat, longitude: poi.location.lng })); } } module.exports MapService;逻辑说明缓存用坐标保留 5 位小数做 key因为再精确的差异对地址结果没影响这样能挡掉大量重复请求。nearby里把 SDK 的原始结构转成自定义的精简结构页面就不用关心originalData这层包装了。参数上radius给了默认值调用方不传也能工作。再补一个验证方法写完模块后别急着接页面先在onLoad里跑一遍「定位 → 逆地理编码 → 周边搜索 → 算路」的完整链路把每步结果console.log出来。链路通了再往 UI 上接能省掉大量「到底是数据问题还是渲染问题」的排查时间。最后说个我踩过的坑早期我把 AK 直接写在页面 js 里后来要换 AK 得全局搜替换漏了一处就出诡异 bug。现在一律走配置文件页面只 import 模块。这个习惯帮我省了不止一次后悔药。地图这块接口多、坐标系绕、真机环境又和工具不一样能封一层就封一层别让业务代码直接裸奔在 SDK 上。希望帮到你。本文还有配套的精品资源点击获取