企业官网建设流程全解析

做地图相关的功能，国内绕不开百度地图API。这个系列前两篇写了地图初始化和覆盖物、事件交互，不少朋友私信问路线规划怎么做、POI搜索怎么拿到真实业务数据、逆地理编码怎么把坐标转成中文地址。这三块功能在实际项目里出现频率极高，恰好构成“地图能力三件套”，所以第三篇专门把路线规划、POI检索、逆地理编码放一起拆解。

这篇延续前两篇的基调，从“能看地图”往“能用地图”推进一步。适合已经在页面里渲染出了百度地图、想继续做搜索和路线功能的开发者，也适合第一次接触百度地图API但对JavaScript比较熟的朋友。整篇会涉及BMap.DrivingRoute、BMap.TransitRoute、BMap.LocalSearch和BMap.Geocoder，配套的坑和调试思路都会写清楚。

1. 内容整体设计与思路拆解

1.1 为什么把路线规划、POI检索、逆地理编码放在一起

我的理解是，这三类能力在地图业务里从来不是孤立存在的。一个完整的选址类项目，用户要先输入关键词搜到目标地点，拿到经纬度坐标之后逆地理编码回填详细地址，最后还要规划从当前位置过去的路线。这三个动作串起来，才是“地图可用”的完整闭环。

单看百度地图JavaScript API的官方文档，每个类的示例都是独立页面，初学者很容易产生“各自为战”的错觉。我在实际项目中踩过的坑就是，地图能标注、能绕路，但业务数据始终接不进来，地图只停留在展示层。把检索、逆编码、路线规划组合起来之后，地图才真正变成业务系统的数据入口和交互面板。

另外，这三块API在调用模式上有高度一致性，都是“构造对象、传入参数、发起回调、在回调里消费结果”。理解任意一个，另外两个就能很快上手。这种结构上的相似性，决定了把它们放在同一篇里梳理是效率最高的方式。

1.2 三层能力模型：从“画出地图”到“算清路径”

接触百度地图API一段时间后，我习惯把它的能力分成三层理解：

• 展示层：地图实例、底图瓦片、自定义样式，解决“地图长什么样”。
• 交互层：覆盖物、事件监听、拖拽缩放，解决“用户怎么操作地图”。
• 业务数据层：POI检索、地理编码、逆地理编码、路线规划，解决“坐标和业务怎么互相翻译”。

前两篇基本覆盖了展示层和交互层，这一篇的重点全在业务数据层。路线规划的本质是“用坐标点发起计算并接收路线结果”，POI检索的本质是“把文字关键词转换成结构化POI列表”，逆地理编码的本质是“把坐标转成可读的省市区街道描述”。

三层并不互相独立。路线规划的起终点可以用POI检索结果填充，POI列表展示的地址可以用逆地理编码补全。实际开发时我一般先画数据流图，再动代码，避免写到最后把API的返回数据结构搞混。

1.3 前置知识回顾和环境约定

第三篇默认读者已经完成了前两篇的工作：

• 已经在页面中成功创建BMap.Map实例。
• 知道如何添加Marker、如何监听地图的click事件。
• 已经在本地运行过第一个百度地图项目。

本篇文章的代码基于百度地图JavaScript API 3.0版本，使用了全局加载方式。示例工程没有用现代前端框架，直接一个HTML加一个JavaScript文件，方便把API本身的行为看透彻。

2. 环境与接入准备：别在密钥配置上翻车

2.1 申请密钥与Referer白名单配置

虽然系列第二篇简单提过密钥，但这一篇的检索和路线规划接口对ak参数更敏感，值得重新强调一遍。百度地图开放平台后台申请密钥的流程不复杂，要重点注意的是“应用类型”和“Referer白名单”两个配置项。

我一般把应用类型选成“浏览器端”，Referer白名单填当前站点域名。本地开发的同学可以把http://localhost:8080加进白名单，后端联调环境则把测试域名一并放进去。白名单的好处是防止别人盗用你的ak，缺点是一旦忘了配，本地页面加载脚本会直接报错，F12看到的结果往往让人摸不着头脑。

最容易翻车的场景是：本地调试时把白名单配成了http://localhost，实际启动的端口是8080，结果页面死活拉不到地图脚本。排查时优先看Network面板里JavaScript文件有没有200，再看ak是否真的拼进了请求URL。这两种情况占了我遇到的接入问题八成以上。

2.2 JavaScript API脚本的加载方式与回调机制

百度地图API 3.0的脚本加载方式和主流地图SDK不太一样，它直接通过一个script标签引入全局脚本，并且把初始化逻辑挂在一个自定义全局函数上。示例代码如下：

<script type="text/javascript"> window.BMapLoadCallback = function () { var map = new BMap.Map("container"); var point = new BMap.Point(116.404, 39.915); map.centerAndZoom(point, 15); }; </script> <script type="text/javascript" src="https://api.map.baidu.com/api?v=3.0&ak=你的密钥&callback=BMapLoadCallback"></script>

注意callback参数必须和全局函数名保持一致。这个回调机制解决了一个经典问题：外部脚本加载完成的时机不可控，使用回调可以确保BMap对象完全可用后再执行地图初始化。

现代前端框架里集成百度地图时，这个callback方式反而比官方推荐的一些封装更适合。因为在webpack构建环境里，脚本会被打包成异步模块，你很难知道外部脚本何时挂载全局BMap。用callback手动控制初始化时序，比在mounted里直接调 new BMap.Map 更稳。

2.3 地图实例的快速初始化模板

第三篇所有功能都以一个初始化完成的地图实例为底座，所以先给一个可复用的模板。之后无论是加检索还是加路线，都在这个map实例上扩展：

function initMap() { var map = new BMap.Map("mapContainer", { enableMapClick: true }); var startPoint = new BMap.Point(116.397428, 39.90923); map.centerAndZoom(startPoint, 14); map.enableScrollWheelZoom(true); return map; }

enableMapClick这个参数要特别提一下。它是地图默认POI点击事件开关，如果业务上不想要点击建筑或POI时弹出气泡信息，建议关掉。我在一个展厅项目里就是因为没关，用户点击地图上的POI图标弹出了官方信息窗口，和自己的业务弹窗叠加，体验很混乱。这个参数按业务需要调整，不必照抄。

3. 路线规划：从A点到B点的三种姿势

3.1 驾车路线规划的基本使用

百度地图JavaScript API里驾车路线规划的核心类叫BMap.DrivingRoute。用法分三步：创建实例、设置起终点、调用search方法发起规划。代码可以浓缩成下面这个模板：

var driving = new BMap.DrivingRoute(map, { renderOptions: { map: map, autoViewport: true }, onSearchComplete: function (results) { if (driving.getStatus() === BMAP_STATUS_SUCCESS) { var plan = results.getPlan(0); var summary = plan.getRoute(0).getDistance(); console.log('总距离：', summary); } }, policy: BMAP_DRIVING_POLICY_LEAST_TIME }); var start = new BMap.Point(116.397428, 39.90923); var end = new BMap.Point(116.407526, 39.802708); driving.search(start, end);

这段示例里最容易忽略的是autoViewport: true。如果不设置，地图视野不会自动调整到路线覆盖范围，可能出现画面上只有一条线但起点终点都在视野外的情况。实测下来，加了这个参数后地图会自动适配边界，省去了手动计算视野的麻烦。

policy参数也是常被忽略的关键点。BMAP_DRIVING_POLICY_LEAST_TIME表示最短时间，BMAP_DRIVING_POLICY_LEAST_DISTANCE表示最短距离，还有避开高速的枚举。不同业务诉求要选择不同策略，比如送货车和私家车导航的偏好就完全不一样。

3.2 公交与步行路线规划的实现差异

公交路线和步行路线分别由BMap.TransitRoute与BMap.WalkingRoute负责，它们的整体结构和驾车路线非常相似，但有几个细节值得注意。

公交路线规划时必须指定城市参数，这个参数直接影响公交线路数据的检索范围：

var transit = new BMap.TransitRoute(map, { renderOptions: { map: map, autoViewport: true }, onSearchComplete: function (results) { if (transit.getStatus() === BMAP_STATUS_SUCCESS) { var plan = results.getPlan(0); var lineNum = plan.getNumRoutes(); console.log('该方案包含乘车段数：', lineNum); } }, policy: BMAP_TRANSIT_POLICY_LEAST_TIME, city: '北京市' }); transit.search(new BMap.Point(116.397428, 39.90923), new BMap.Point(116.407526, 39.802708));

公交路线返回的getPlan里会有多个子路线，例如“步行-公交-步行”。每个子路线类型不同，有的包含公交线路名称，有的只包含一段步行距离。我在写方案卡片时，需要遍历getRoute获取每一段信息，再拼接成“步行200米-乘坐355路-步行150米”这样的文案。如果用默认渲染，官方会把全程方案画在地图上，但业务卡片还是得自己处理数据结构。

步行路线规划BMap.WalkingRoute相对简单，因为步行不存在换乘逻辑，结果集里通常只有一个方案。适合用来做“从停车场到门店”“从地铁口到园区”这种最后几百米指引。

3.3 不依赖默认渲染：把路线方案数据抽出来自己做卡片

官方示例里最简单的方式是直接render到地图上，会在地图下方生成一个路线信息面板。但实际产品里，这个默认面板样式和设计稿通常对不上，更多时候需要自己渲染方案卡片。

这个时候核心思路是：不让renderOptions里的map属性生效，只通过onSearchComplete回调拿数据。在回调里把results的每个方案取出来，自己解析成结构化数据：

var driving = new BMap.DrivingRoute(map, { onSearchComplete: function (results) { if (driving.getStatus() !== BMAP_STATUS_SUCCESS) return; var planCount = results.getNumPlans(); for (var i = 0; i < planCount; i++) { var plan = results.getPlan(i); var route = plan.getRoute(0); var time = plan.getDuration(true); // 格式化成"...小时...分钟" var distance = route.getDistance(true); // 格式化成公里文本 var description = plan.getDescription(); // 这里可以把 time / distance / description 渲染到自己的卡片里 } }, policy: BMAP_DRIVING_POLICY_LEAST_DISTANCE });

如果不想让官方自动在地图上画路线，可以不把map传入renderOptions，甚至把renderOptions整个省略。但要注意，这样官方就不会帮你显示路线和标注，后续你需要自己往地图上加Marker和Polyline。我一般还是会把map传进去，让官方画线，再额外渲染业务卡片，这样就实现了代码量最小、样式又可控。

经验提醒：多次调用search之前，最好先调用clearResults()清空上一次的路线条目，否则连续搜索会叠加很多旧轨迹，视觉上非常杂乱。

3.4 路线规划里的数据解析经验

路线规划结果的数据结构层级比较多，文档又写得零散，我梳理过一份“取数链路”，分享给读者：

• results.getNumPlans()：方案数量，驾车通常有多个备选方案，公交也有多个方案。
• results.getPlan(index)：获取第index个方案。
• plan.getNumRoutes()：该方案包含的路线段数量。
• plan.getRoute(index)：获取第index条子路线，驾车时一般就是一条完整路线，公交时会有多段。
• route.getDistance()：该路线的距离，单位是米。
• plan.getDuration()：方案总耗时，返回秒数或者格式化文本取决于参数。

项目里我习惯统一做一个解析函数，把plan对象转成前端友好对象，包含总距离、总耗时、多条子路线描述，然后输出到列表组件渲染。这样地图层和业务层之间就多了一个稳定的数据适配层，后续换地图SDK时只需要替换适配层。

4. POI检索与逆地理编码：把坐标变成业务语言

4.1 本地搜索：用关键词找到POI点

BMap.LocalSearch是百度地图API里最常用的POI搜索类，支持在当前地图视野、指定区域或者城市里搜关键词。创建实例后调用search，回调里拿到的results结构同样遵循“实例状态+结果集”模式：

var localSearch = new BMap.LocalSearch(map, { pageCapacity: 10, onSearchComplete: function (results) { if (localSearch.getStatus() === BMAP_STATUS_SUCCESS) { var total = results.getCurrentNumPois(); // 当前页POI数量 for (var i = 0; i < total; i++) { var poi = results.getPoi(i); console.log(poi.title, poi.point.lng, poi.point.lat, poi.address); } } } }); localSearch.search('便利店');

搜索关键词默认跟着地图当前视野区域走。如果不调用setBounds或setSearchInBounds，它会优先搜索当前视野范围内的结果。这个设计初看有点反直觉，但对“附近的门店”这类需求其实非常契合。

我还发现一个细节：pageCapacity默认是10，如果项目里需要搜索结果超过10条，需要主动调整。一旦搜索结果很多，回调里的getCurrentNumPois会受分页影响，建议用getPageCapacity和getPageIndex一起控制分页展示。

4.2 周边检索与行政区划检索的不同场景

LocalSearch提供了两种定位搜索范围的思路：

• 周边搜索：以某个坐标点为圆心，radius参数指定半径。
• 区域内搜索：setSearchInBounds，以矩形区域约束视野。

周边搜索比较典型的使用场景是“查某坐标附近3公里内的公交站”，我经常配合逆地理编码实现“用户图上选点，然后查看点位周边信息”的交互：

var point = new BMap.Point(116.403, 39.915); var localSearch = new BMap.LocalSearch(map, { onSearchComplete: function (results) { /* 处理结果 */ } }); localSearch.searchNearby('餐厅', point, 3000);

searchNearby的第三个参数是半径，单位是米。实测中半径超过5000米时，搜索范围过大，返回结果噪声较多，建议控制在3000米以内并根据业务场景细分关键词。

行政区域检索则更适合“在某某区找所有学校”这种需求，与周边检索在接口触达上没有重合，可以根据业务目标直接选型，不必两套都写。

4.3 逆地理编码：从经纬度到中文地址

BMap.Geocoder是逆地理编码的核心工具，支持两种使用方式。一是getPoint把地址字符串解析成坐标，这个属于地理编码。二是getLocation把坐标解析成地址对象，这是项目里更常用的场景：

var geocoder = new BMap.Geocoder(); geocoder.getLocation(new BMap.Point(116.403, 39.915), function (result) { if (result) { var address = result.address; // 完整地址 var province = result.addressComponents.province; var city = result.addressComponents.city; var district = result.addressComponents.district; var street = result.addressComponents.street; console.log(address, province, city, district, street); } });

result.addressComponents是地道的最常用解构，省市区街道信息全在这里。需要注意，这个接口返回的address是拼接好的地址串，但偶尔会出现门牌号精度不足的情况，不要假设地址串永远完美，业务展示时最好配合自定义区域名做二次加工。

做“点击地图拾取位置”功能时，我通常把逆地理编码放在地图click事件里。用户点一个点，地图打上Marker，弹窗显示逆编码得到的中文地址。这个交互在地图选点场景里几乎是标配。

4.4 完整示例：POI搜索列表联动地图定位和地址展示

把POI检索、Marker、逆地理编码串起来做一个完整示例，效果最直观。下面这个小型Demo实现：输入关键词搜索POI，列表展示搜索到的地点；用户点击列表项时，地图定位到该点到视野中心、添加高亮Marker，并同步显示逆地理编码的地址。

var map = initMap(); var marker = null; var localSearch = new BMap.LocalSearch(map, { pageCapacity: 10, onSearchComplete: function (results) { var listBox = document.getElementById('resultList'); listBox.innerHTML = ''; if (localSearch.getStatus() !== BMAP_STATUS_SUCCESS) return; var count = results.getCurrentNumPois(); for (var i = 0; i < count; i++) { var poi = results.getPoi(i); var li = document.createElement('li'); li.innerHTML = poi.title; li.onclick = (function (poi) { return function () { map.centerAndZoom(poi.point, 16); if (marker) { map.removeOverlay(marker); } marker = new BMap.Marker(poi.point); map.addOverlay(marker); var geocoder = new BMap.Geocoder(); geocoder.getLocation(poi.point, function (result) { document.getElementById('addressInfo').innerHTML = result.address; }); }; })(poi); listBox.appendChild(li); } } });

这一段代码最简单，却也最容易踩到闭包的坑。li.onclick绑定的函数如果不立即执行并传入当前的poi对象，最终所有列表项点击时拿到的都是最后一个poi。我在第一次写这个功能时也踩过，后来习惯在循环里用自执行函数或者let声明来把poi固定住。

搜索完成回调里连续执行了定位、加Marker、逆编码三个动作，这在地图交互中非常常见。需要注意的是，Marker和逆编码的结果响应是有先后顺序的，不要在POI检索回调里依赖逆编码的地图“立即”更新，实测中异步回调的时序是完全可以处理的，只要不强行做同步赋值就没问题。

5. 常见问题与排查技巧实录

5.1 高频问题与解决对照表

实际开发里，地图API的问题往往不是API本身有多难，而是接入细节和异步时序导致的各种奇怪现象。下面这张表是从我自己的项目笔记里整理的，按现象、原因、解法三条线索对照。

这张表里的问题，前三个是把页面从原生地图服务调试到API正常调用时最常见的，后三个则是真正在业务迭代中发生的逻辑问题。

5.2 从F12到源码的调试顺序

遇到地图问题时，我的习惯是先确认“脚本有没有加载”，再看“代码逻辑有没有执行到”。F12的Network面板里找到baidu地图API的js文件，确认状态码是200；然后在代码的回调函数里打一个console.log，确认回调有没有触发。这两步走完，超过一半的问题已经能定位。

如果回调没触发，再去检查getStatus()返回的状态码。百度地图API文档里列了不少状态常量，比如BMAP_STATUS_SUCCESS是0，BMAP_STATUS_CITY_LIST是1，BMAP_STATUS_UNKNOWN_LOCATION是2。状态码非0时，按文档对应的含义排查坐标和参数比瞎改代码高效得多。

另外一个比较隐蔽的问题是全局回调函数名冲突。页面里如果有两个百度地图实例，都注册了同一个window回调，后面的覆盖前者，可能导致第一个实例永远初始化不了。解决办法是每个实例使用独一无二的回调名。

5.3 两个容易被忽略的隐藏坑

第一个隐藏坑是多次点击地图选点时，Marker不会自动消失。如果每次点击都addOverlay一个Marker，不手动删除旧的，页面会积累大量覆盖物，拖动地图时明显卡顿。更合理的做法是维护一个单一Marker引用，每次添加前removeOverlay掉旧的那个。

第二个隐藏坑是逆地理编码结果在部分新区或工业园区里可能显示为“内部道路”这类比较模糊的地址。做展示问题不大，如果要做表单回填，最好配合POI点标题和自定义行政区字段做二次清洗，不要直接把result.address写入数据库，避免脏数据流入下游。

提示：如果项目里同时用到驾车、公交、步行多个路线实例，建议每个实例独立命名并分开监听各自的onSearchComplete。共用回调时状态和结果很容易互相干扰，排查起来也费劲。

6. 第三篇到这里，后续还能怎么做

路线规划、POI检索、逆地理编码都跑通之后，项目里的地图能力基本已经覆盖了从展示到数据交互的大部分场景。按我以往的实践经验，接下来可以往两个方向深入：一是大量Marker场景下的性能优化，比如利用点聚合库把几千个点位渲染得流畅；二是自定义个性化地图样式，把底图和自己的品牌视觉统一起来。

我个人做地图类项目比较习惯“先跑通示例、再改造样式、最后抽象成公共模块”。百度地图官方文档提供了非常多可用示例，但直接粘进业务里往往不合适，需要改造的点通常是回调、数据结构封装和默认渲染的替换。这篇写到的几个示例，都可以直接作为公共功能模块的骨架。

如果你正在做一个需要选点、搜索、展示路线的页面，不妨把这篇文章的代码按顺序跑一遍，然后把回调里的数据打印出来仔细看看。地图API的返回结果虽然层级繁琐，但打印一遍之后，后续再碰到任何数据结构问题都能很快定位。