简介：这份资源是面向微信小程序开发者的百度地图 JavaScript API 接口包，适合需要在社交、旅游、打车等场景中嵌入地理位置服务的初中级开发者。包内共35个文件，以js脚本、wxss样式、json配置、wxml模板和png图片为主，压缩包约28KB，其中bmap-wx.js与bmap-wx.min.js为核心接口文件，demo目录提供了可直接参考的页面示例，README.md则给出基础说明。已有88人学习下载。借助这套接口，开发者可在小程序内实现地图展示、标记点与多边形等覆盖物添加、缩放移动、路径规划、地点检索、驾车导航、公交查询及周边检索，并支持实时位置分享，为社交与出行类应用提供位置能力支撑。文件包命名中的master表明其为主版本，稳定性较好，适合直接用于生产环境；配合官方文档与参数示例，可帮助开发者快速上手并高效排查调用问题。
1. 百度地图微信小程序 JSAPI 到底解决什么问题
很多团队第一次在微信小程序里做地图，第一反应是直接用微信原生的map组件。原生组件能显示地图、能打点、能画线，看起来够用。但真到业务里，问题就来了：想按关键字搜周边门店、想逆地理编码把经纬度换成中文地址、想算两个点之间的步行路线、想画一片多边形区域做电子围栏——这些原生组件都不直接给。于是就得自己接一套地图服务，而百度地图微信小程序 JSAPI 就是干这个的：它把百度地图的检索、逆地理、路线规划、坐标转换等能力，封装成能在小程序里直接调用的接口。
这个标题指向的是一份 JSAPI 的接入包，核心价值在于让小程序开发者不用从零搭地图后端，就能拿到搜索、定位、算路这些能力。适合两类人：一类是刚接手小程序地图需求、想快速跑通的新手；另一类是已经用了原生组件、但被检索和算路卡住的熟手。下面按「先跑通、再调参、再避坑」的顺序讲清楚。
2. 接入前的准备与最小可运行工程
2.1 申请密钥与配置合法域名
百度地图的接口调用都要带一个 AK（Access Key），这是身份凭证。申请流程在百度地图开放平台的控制台完成，创建应用时选「微信小程序」类型，填上小程序的 AppID，平台会生成对应的 AK。这里有个容易忽略的点：AK 是和小程序 AppID 绑定的，换一个小程序就得重新申请，不能混用。
拿到 AK 之后，还要在小程序后台配置服务器域名。百度地图的接口域名需要加进 request 合法域名列表，否则真机上请求会被拦截。常见要加的有api.map.baidu.com和api.map.baidu.com下的路径。开发阶段可以在开发者工具里勾选「不校验合法域名」，但上线前必须配好，不然线上直接白屏。
提示：AK 分浏览器端、服务端、小程序端几种类型，申请时选错类型会导致接口返回权限错误，这个坑后面避坑章节会细说。
2.2 引入 JSAPI 文件与初始化
这份 JSAPI 包通常是一个bmap-wx.js之类的文件，把它放到小程序工程的utils或libs目录下，然后在页面里 require 进来。初始化时传入 AK，创建一个 BMapWX 实例。
// utils/bmap-wx.js 是引入的 JSAPI 文件 const BMapWX = require('../../utils/bmap-wx.js'); // 初始化，ak 换成自己申请的值 const bmap = new BMapWX({ ak: '你的小程序端AK' }); Page({ data: { markers: [], address: '' }, onLoad() { // 页面加载时做一次逆地理，验证 AK 是否可用 this.reverseGeocode(116.404, 39.915); }, reverseGeocode(lng, lat) { bmap.regeocoding({ location: `${lat},${lng}`, // 注意顺序是纬度在前 success: (res) => { // res 里包含 address、business 等字段 this.setData({ address: res.originalData.result.formatted_address }); }, fail: (err) => { console.error('逆地理失败', err); } }); } });这段代码做了三件事：引入 JSAPI、用 AK 初始化实例、调用逆地理接口把经纬度转成地址。参数上，location的格式是「纬度,经度」，顺序反了会返回错误结果或空地址，这是新手最常翻车的地方。success回调里的originalData是百度返回的原始结构，formatted_address是格式化后的地址字符串。跑通这一步，说明 AK 和域名配置都没问题，可以往下做检索和算路。
3. 检索、逆地理与路线规划的落地写法
3.1 周边检索与关键字搜索的参数怎么设
周边检索（search）和关键字搜索是地图业务里用得最多的两个接口。周边检索以某个中心点为核心，按半径找 POI；关键字搜索则是在指定城市范围内按词找。两者的参数结构类似，但用途不同。
// 周边检索：找中心点 1000 米内的咖啡店 bmap.search({ query: '咖啡', location: '39.915,116.404', // 纬度,经度 radius: 1000, // 单位米，最大一般 50000 page_num: 0, // 页码从 0 开始 page_size: 10, // 每页条数，最大 20 success: (res) => { const pois = res.originalData.results.map(item => ({ name: item.name, address: item.address, lat: item.location.lat, lng: item.location.lng })); this.setData({ markers: pois }); }, fail: (err) => console.error(err) });参数里radius是半径，单位米，设太大返回结果会被截断，设太小又搜不到东西，一般按业务场景给 500 到 3000。page_num从 0 开始，翻页时递增，但要注意百度对总页数有限制，深翻页拿不到数据。page_size最大 20，想一次多拿只能靠翻页。返回的results数组里每条 POI 带location对象，里面是lat和lng，直接可以喂给地图组件的 markers。
关键字搜索多一个region参数，用来限定城市，比如region: '北京'。不传 region 时结果可能跨城，做本地生活类业务一定要传。
3.2 逆地理编码与坐标转换的配合
逆地理编码是把经纬度换成地址，前面已经跑通。但这里有个坐标系问题必须讲清楚：百度地图用的是 BD09 坐标系，而微信小程序wx.getLocation默认返回的是 GCJ02 坐标系。两者不转换直接用，位置会偏移几百米，这就是很多人说的「玄学偏移」。
// 把微信拿到的 GCJ02 坐标转成 BD09 bmap.translate({ from: 'gcj02', to: 'bd09', location: '39.915,116.404', success: (res) => { // res.originalData.result 里是转换后的坐标数组 const point = res.originalData.result[0]; console.log('转换后', point.y, point.x); // y 是纬度，x 是经度 }, fail: (err) => console.error(err) });translate接口的from和to支持wgs84、gcj02、bd09三种坐标系互转。注意返回结构里y对应纬度、x对应经度，和常见的lat/lng命名不一样，取值时别搞反。实际业务里，通常是先用wx.getLocation拿到 GCJ02 坐标，转成 BD09 后再去调检索或逆地理，这样结果才准。
3.3 路线规划接口的调用与结果解析
路线规划分驾车、步行、骑行、公交几种，接口名不同但参数结构接近。以驾车为例，传入起点和终点坐标，返回的是分段路径和总距离、总时长。
bmap.driving({ origin: '39.915,116.404', // 起点 纬度,经度 destination: '39.925,116.424', // 终点 success: (res) => { const route = res.originalData.result.routes[0]; console.log('总距离(米)', route.distance); console.log('总耗时(秒)', route.duration); // route.steps 是分段导航信息 route.steps.forEach(step => { console.log(step.instructions); // 每段文字指引 }); }, fail: (err) => console.error(err) });返回的routes是数组，一般取第一条。distance单位米，duration单位秒，展示时要自己换算成公里和分钟。steps里每段带instructions文字指引和path坐标串，画线时把 path 解析出来喂给 polyline 即可。公交规划返回结构更复杂，带换乘信息，解析时要多判空。
4. 避坑与常见问题排查
4.1 AK 类型选错导致接口全部报错
现象：所有接口都返回权限错误或状态码非 0，控制台提示 AK 无效。原因是申请时选了浏览器端或服务端类型，而小程序端必须用「微信小程序」类型的 AK。解决方式是回控制台重新创建应用，类型选对，把新 AK 换进初始化代码。这个坑很隐蔽，因为 AK 字符串本身看起来没问题，只有类型不对。
4.2 坐标系没转换导致位置偏移几百米
现象：地图上打的点和实际位置对不上，偏移量稳定在几百米。原因是微信定位返回 GCJ02，百度接口吃 BD09，中间少了转换。解决办法是在拿到定位坐标后先调translate转成 BD09，再用于检索、逆地理和打点。判断是否偏移，可以拿一个已知地标的坐标对比，偏几百米基本就是坐标系问题。
4.3 真机请求被拦截而开发者工具正常
现象：开发者工具里一切正常，真机上接口全部失败。原因是没在小程序后台配置 request 合法域名，工具里勾了「不校验合法域名」所以看不出来。解决方式是登录小程序后台，在开发设置里把百度地图的接口域名加进合法域名列表，然后重新编译真机预览。
4.4 翻页参数用错导致重复数据
现象：翻页拿到的 POI 和上一页重复，或者直接返回空。原因是page_num从 0 开始，有人从 1 开始传，导致第一页数据被跳过或重复。另外百度对深翻页有限制，翻到后面可能拿不到数据。解决办法是页码严格从 0 递增，并在业务上做去重，不要依赖接口保证唯一。
4.5 回调里 this 指向丢失
现象：在 success 回调里用this.setData报错，提示 this 是 undefined。原因是普通函数的 this 不指向页面实例。解决办法是把回调写成箭头函数，或者在调用前用const that = this缓存。这个是小程序开发的通用坑，不只是地图接口会遇到。
5. 进阶：把地图能力封装成可复用模块
跑通单个接口之后，真正影响维护成本的是怎么组织代码。我一般会把地图相关调用统一收进一个 service 层，页面只负责拿数据渲染，不直接碰 JSAPI。这样换 AK、改参数、加缓存都只动一个地方。
// services/mapService.js const BMapWX = require('../utils/bmap-wx.js'); const bmap = new BMapWX({ ak: '你的AK' }); // 统一封装成 Promise，页面里用 async/await function searchNearby(keyword, lat, lng, radius = 1000) { return new Promise((resolve, reject) => { bmap.search({ query: keyword, location: `${lat},${lng}`, radius, page_num: 0, page_size: 20, success: (res) => resolve(res.originalData.results || []), fail: reject }); }); } // 坐标转换也封装一层，避免页面里到处写 function gcj02ToBd09(lat, lng) { return new Promise((resolve, reject) => { bmap.translate({ from: 'gcj02', to: 'bd09', location: `${lat},${lng}`, success: (res) => { const p = res.originalData.result[0]; resolve({ lat: p.y, lng: p.x }); }, fail: reject }); }); } module.exports = { searchNearby, gcj02ToBd09 };封装成 Promise 之后，页面里的调用就干净很多：
const mapService = require('../../services/mapService.js'); Page({ async onLoad() { const loc = await this.getLocation(); const bd = await mapService.gcj02ToBd09(loc.latitude, loc.longitude); const pois = await mapService.searchNearby('超市', bd.lat, bd.lng, 2000); this.setData({ markers: pois }); }, getLocation() { return new Promise((resolve, reject) => { wx.getLocation({ type: 'gcj02', success: resolve, fail: reject }); }); } });这样做的收益在项目变大后特别明显：接口参数要调、AK 要换、要加失败重试，都只改 service 层。另外建议给检索结果加一层本地缓存，同一个中心点短时间内重复搜同一关键字，直接读缓存，能省调用量也能提速。缓存 key 用「关键字+坐标+半径」拼，设个几分钟过期就行。
验证封装是否可靠，我习惯写一个最小页面，只做「定位→转换→检索→打点」这一条链路，跑通再往业务里搬。真机上重点看三件事：定位准不准、点打的位置对不对、翻页数据重不重。这三样没问题，基本就能上线了。我自己踩得最狠的一次是忘了转坐标系，测试机上看着差不多，真机到现场偏了一条街，返工查了半天才定位到是 GCJ02 和 BD09 混用。后来养成习惯，凡是坐标进地图接口前，先问一句「这是哪个坐标系」。希望帮到你。
本文还有配套的精品资源，点击获取
