企业官网建设流程全解析

做小程序的人都知道，位置服务几乎是避不开的模块。无论是外卖配送的路线预览、门店到店导航、物流轨迹回放，还是同城服务的区域圈选，背后都要靠地图和路径规划撑着。前阵子我接到一个需求：在微信小程序里同时对接腾讯位置服务和高德地图，实现从用户当前位置到目标地址的路径规划展示。这个需求听起来不算难，但真正做起来有几个绕不开的坎：Key怎么申请和绑定、SDK怎么接、两个地图服务的数据结构差异、坐标系的坑、路线渲染的细节。这篇文章就把我整个对接过程和踩坑记录整理出来，给正在折腾地图服务的同行一些参考。

这个项目最核心的就三块：地图Key的申请与绑定、小程序SDK的接入、路径规划API的调用与路线绘制。我会把腾讯和高德两条线都走一遍，从账号配置讲到真机调试，尽量让看完的人能直接照着做。如果你只是想快速跑通一个Demo，或者已经在线上被地图服务的某个报错卡住，这篇内容应该都能帮上忙。

1. 项目背景与方案选型

1.1 为什么小程序的路径规划要单独对接

很多刚入门的人会问：小程序里不是有<map>组件吗？直接拿来用不就行了？这其实是个很大的误解。<map>组件只是提供了一个地图容器，能展示底图、标记点、线路，但它本身不会帮你算路线。路径规划需要从A点到B点算出一条可通行的路线，这要依赖地图服务商的路网数据和路径计算引擎，也就是通常说的路径规划API。

路径规划是典型的高计算量服务，底层涉及道路拓扑、交通流、通行限制等大量数据。小程序内置组件没这个能力，各家地图服务商也不愿意把这么核心的能力免费白给，而是通过Web API的形式开放给开发者。所以我们在小程序里做路径规划，常规做法就是：调起地图服务商的HTTP接口，拿到路线坐标点数组，再把这些点交给<map>组件的polyline画出来。

还有一个更现实的原因：不同业务方的地图供应商不一样。有的公司主体跟腾讯走得近，有的项目一开始就用高德的地图数据做数据分析，这时候小程序端就得跟着技术栈选同一家。我这次需求就是兼顾两边的，所以腾讯和高德都要接。

1.2 腾讯地图和高德地图怎么选

做方案选型时，我先列了一个对比维度，把两个服务在小程序场景下的表现拉出来看了下。

从实际开发感受来说，如果你的项目纯粹是微信小程序场景，腾讯位置服务会更顺手一点，毕竟同属腾讯生态，SDK的封装程度和文档的适配度明显更高。高德的优势在于数据积累和POI丰富度，在偏业务型的地图服务（比如门店搜索、周边生活服务）上有优势。

这次我的选择是：小程序端以腾讯为主路径，高德作为备份和对照方案，同时验证两边API的兼容性。这样做的好处是，万一某一家配额用尽或者临时故障，可以直接切换另一家，不至于业务瘫痪。

1.3 需求拆解与功能清单

对接之前，我把需求拆成几个功能点：

• 获取用户当前定位：通过wx.getLocation拿到经纬度。
• 目的地输入与检索：支持手动输入地址，通过地理编码转成经纬度。
• 路径规划：调腾讯或高德的路径规划API，拿到路线坐标。
• 路线绘制：在地图上用线把整条路画出来。
• 起终点标记与信息展示：起点、终点、全程距离、预计时间。
• 多模式切换：支持步行、驾车、骑行三种模式切换。

这样的拆分逻辑，其实是把小程序的UI层和地图服务的数据层解耦。UI层只管地图、标记、距离页面；数据层只负责根据起终点经纬度和模式，返回路线数据。后面不管是换地图商、加途经点，还是加一个公交查询，都只要改数据层。

2. 开发前准备与Key申请

2.1 腾讯位置服务Key申请流程

腾讯位置服务的接入地址是lbs.qq.com，先去注册账号，然后进入控制台创建应用。创建应用的时候会让你填应用名称、应用类型，记得选择“微信小程序”，然后填小程序的AppID。这一步很关键，如果类型选错或者AppID填错，后面SDK调用会被拒。

创建完应用后，在应用详情里添加Key。腾讯位置服务的Key体系是应用下挂多个Key，每个Key可以独立配置配额和域名白名单。我通常的做法是一个Key对应一个小程序环境，比如正式环境一个、测试环境一个，方便排查问题，也不会因为某个环境调用量异常把整体配额打爆。

拿到Key之后，先别急着写代码。腾讯的Key在控制台可以配置安全设置，包含小程序AppID绑定、Referer白名单等。虽然小程序端Key是必然暴露在代码里的，但绑定了AppID后，别人即使拿到Key，也没法直接仿冒你的小程序去消耗配额，这是最基本的防盗手段。这个环节不做好，上线后Key被人拿去刷接口，账单会很难看。

2.2 高德地图Key申请流程

高德的接入位置是console.amap.com，同样先注册开发者账号。这里有个要踩的坑：高德的账号分个人和企业，个人开发者实名认证后，部分接口的配额会比较低，路径规划的日调用量上限和企业版差距明显。如果只是开发测试，个人版够用，但如果准备商用上线，强烈建议提前申请企业认证，不然后面还要二次改造。

创建应用时，选择服务平台为“微信小程序”，然后系统会生成一个Key。高德的Key体系里，每个应用会有一个独立的Key，同一个应用下面还可以开通不同的API服务。我们在控制台把需要的服务开启即可，比如“路径规划API”“地理编码API”。注意高德在2021年之后升级了API Key的安全策略，部分新接口要求配合安全密钥（jscode）使用。小程序SDK老版本不需要，但如果直接用REST接口就会碰到，建议以官方最新文档为准。

高德那边有一个让我印象很深的细节：Key的配额是按“每日”计算的，而且有些免费配额是按“每日压测量”算，突然的大流量绝对会触发限流。后面我在线上遇到过一天中某个小时接口突然全部失败的情况，排查了半天发现是单小时并发触发了限流，这个后面单独说。

2.3 微信小程序后台域名配置

这是第一次接地图服务的人都容易忽略的环节。小程序运行的时候，API请求必须指向后台配置过的合法域名，否则真机上会直接报request:fail url not in domain list。

腾讯位置服务要配的域名是https://apis.map.qq.com，高德要配的是https://restapi.amap.com。在小程序后台的“开发管理-服务器域名”里，把对应域名加到request合法域名列表里即可。

开发阶段可以在开发者工具里勾选“不校验合法域名”，这样本地调试不会被拦截。但注意这只是权宜之计，上线之前一定记得把域名配上，并且在小程序后台把HTTPS证书检查开起来。有些人开发时用着没事，上线后却发现地图全挂，十有八九就是漏了这一步。

2.4 小程序的定位权限准备

路径规划的起点通常是用户当前定位，所以还要在app.json或页面配置里声明定位权限。微信小程序的定位接口是wx.getLocation，使用时需要在app.json的permission节点里说明用途：

{ "permission": { "scope.userLocation": { "desc": "你的位置信息将用于路径规划导航" } } }

这里的desc必须写得明确，微信审核时如果发现用途描述与实际功能不符，会被驳回。有些项目还涉及后台持续定位，那就需要申请scope.userLocationBackground，审核更严格，这次用不到就不展开了。

调用wx.getLocation的时候，参数里有一个type字段，强烈建议设置为'gcj02'。这里就牵出地图开发里最重要也最容易踩坑的概念——坐标系。

3. 坐标系与SDK接入

3.1 坐标系，很多人栽在这里

国内所有地图服务商对外输出的经纬度，基本都是GCJ-02坐标系，也就是俗称的“火星坐标系”。而手机GPS芯片原始返回的是WGS-84坐标系，也就是国际通用的标准经纬度。这两个坐标系之间存在偏移，通常会有几十米到几百米的差距，直接把GPS原始坐标怼到地图上，标记点位置就会偏到隔壁街甚至隔壁小区。

微信的wx.getLocation很贴心地支持直接返回GCJ-02坐标，所以我在代码里固定用：

wx.getLocation({ type: 'gcj02', success: (res) => { // res.latitude / res.longitude 已经可用于地图组件 } });

腾讯和高德的路径规划API，接收的起终点坐标也都是GCJ-02，所以只要你统一用wx.getLocation的 GCJ-02 结果，这条链路就不会出问题。真正会出问题的场景是：某些业务是从后台接口拿GPS数据，或者从第三方平台取了WGS-84坐标，直接传路径规划API，算出来的路线起点会偏离。

判断坐标是不是GCJ-02最简单的方式：拿坐标到腾讯或高德的地图页面上反查位置，如果地图上标的点和实际地点对不上，大概率就是WGS-84混进来的数据。这种情况要么在服务端做坐标转换，要么在前端用现成的转换算法处理。腾讯和高德都没直接提供在线的坐标转换API，前端的转换算法网上很多，我就不贴大段代码了，但提醒一句：每次转换都有精度损耗，能拿到GCJ-02就尽量别转。

3.2 腾讯地图小程序SDK接入

腾讯位置服务给小程序开发者提供了一个专门的SDK，叫做qqmap-wx-jssdk。下载下来之后，把文件放进小程序的libs目录，然后在页面或工具类里引用：

const QQMapWX = require('../../libs/qqmap-wx-jssdk.js'); const qqmapsdk = new QQMapWX({ key: '你的腾讯位置服务Key' });

这个SDK封装了地理编码、逆地理编码、路径规划、搜索等常用接口。路径规划对应的方法是direction，后面我会专门讲。

接入时有几个版本上的坑要注意。这个SDK的更新频率不算高，有些网上下载的是几年前的版本，接口行为跟当前腾讯WebService API不完全一致。我的建议是去腾讯位置服务的官网文档页下载最新版，别从博客或下载站找。还有，无论SDK版本怎么变，Key的读取方式都是一样的，初始化时传进去即可。

3.3 高德地图小程序SDK接入

高德给小程序用的SDK是amap-wx.js，同样放在libs目录下引用：

const amap = new AMapWX({ key: '你的高德Key' });

高德SDK的路径规划方法是getRoute。它的设计偏向于把REST API简单封装了一下，底层的参数和返回结构和腾讯风格不同，这个耐心看文档就好。

高德SDK有一个让人难受的点：官方文档里的示例代码有时候和老SDK版本不匹配。我发现网上很多教程贴的代码是用amapFile加载方式，而新版已经改成了AMapWX直接实例化。抄别人的代码之前，一定先对着官方文档过一遍方法名。我在这里也踩过坑，照着旧文章跑出来的代码各种报Undefined is not a function，浪费了一个下午。

3.4 组件模式、JS API模式和REST模式的区别

在小程序里使用地图服务，其实有三条路线：

• 组件模式：直接用微信的<map>组件，纯展示地图和覆盖物，不定制点线面。
• SDK模式：用腾讯或高德的小程序SDK调用Web API，拿到数据后再交给<map>组件绘制。
• REST模式：自己用wx.request直接请求地图服务商HTTP接口，完全掌控数据链路。

SDK模式是我们这次主要用的，因为它省去了自己拼URL、处理签名、解析JSON的重复劳动。但我不建议把SDK当成黑盒，因为SDK内部也在发普通的HTTP请求，最终数据格式还是跟REST API一致的。如果遇到SDK里解决不了的问题，比如某个新功能SDK没封装，直接切到REST模式反而更快。

4. 路径规划API调用实战

4.1 路径规划API首先搞清楚一件事

调用路径规划之前，先想明白一件事：你要算的是两点之间的“直线”还是“可行路线”？很多人会把测距工具和路径规划混在一起。腾讯和高德都提供测距接口，那个算出来的是球面距离，纯数学计算；路径规划则是基于路网数据算出来的，会考虑道路走向、单行道、禁止转弯等因素。两者的结果差异很大，用途也不同。我这次是用在小程序的到店导航预览上，必须走路径规划接口。

路径规划接口本质上是一类“交通网络计算”任务，服务端要做的是：根据起点、终点坐标，结合当前路网的拓扑关系，搜索出一条满足通行规则的路线。所以它的核心参数就是三个：起点坐标、终点坐标、出行方式。有些接口还支持途经点、避让区域、路线偏好等高级参数，先用基础参数跑通，再慢慢加。

4.2 步行路径规划的实现

步行路线是最简单的，不涉及道路单向限制，只走人行道路网。腾讯的direction方法写法如下：

qqmapsdk.direction({ mode: 'walking', from: `${startLat},${startLng}`, to: `${endLat},${endLng}`, success: (res) => { // 从 res.result.routes 拿路线数据 }, fail: (err) => { console.error('路线规划失败', err); } });

高德对应的getRoute写法：

amap.getRoute({ mode: 'walking', origin: `${startLng},${startLat}`, destination: `${endLng},${endLat}`, success: (res) => { // 从 res.routes 拿路线数据 }, fail: (err) => { console.error('路线规划失败', err); } });

注意一个关键差异：腾讯的from和to顺序是纬度,经度，高德的origin和destination顺序是经度,纬度。这个顺序搞反了，接口不会报错，但你会发现自己规划的路线起点在另一个城市，或者路线直接画歪了。我第一次对接高德的时候就栽在这个地方，排查了半天才发现是经纬度顺序问题。

高德返回的路线数据里，res.routes[0].steps是一系列“路段”（step），每个step有自己的polyline字段，是一个字符串。这个字符串形如：

"116.397428,39.90923;116.397428,39.90923;116.397489,39.909058"

需要自己按分号和逗号拆分成坐标点数组。腾讯的SDK在新版本里已经帮我们把polyline解析成数组了，但如果直接调REST接口，拿到的还是一串需要解码的编码字符串。腾讯用的编码方式和Google的Encoded Polyline Algorithm相同，网上有现成的解码JS实现。开发时我在工具函数里把两种数据源统一处理成相同结构，这样上层渲染逻辑就不用关心底层是腾讯还是高德。

4.3 驾车路径规划的实现与参数细节

驾车路线比步行复杂，因为要考虑道路方向、限行、拥堵等因素。腾讯的驾车模式是mode: 'driving'，直接传起终点坐标。高德的驾车模式是mode: 'driving'，但在getRoute里需要额外的city参数，代表终点城市名字或城市编码。这个参数在文档里标的是“可选”，但实测如果漏了，有些城市会返回规划失败或者绕远路。我的经验是：尽量传上，不确定城市编码就传中文城市名，比如city: "北京市"。

如果你要支持“多条路线备选”，腾讯返回的routes里可能包含多条路线，SDK默认只返回一条主路线。高德的getRoute不直接提供多方案，需要走REST接口并传strategy参数才能拿到多条。做“路线对比”功能的话，我建议两边都走REST模式，因为SDK对多方案的支持比较有限。

我实际接线上项目时，驾车路线还会涉及一个“路线偏好”的问题。比如有的用户走高速优先，有的用户避免拥堵。腾讯的 direction 里可以传policy，高德可以传strategy。参数值各家不同，每次对接时查一下最新文档，我不建议背参数值，因为服务商会不定时调整枚举值。

4.4 骑行路径规划的实现

骑行和步行很像，但路网数据不同。骑行走的是自行车道，很多骑行道是单向或禁行自行车的，所以结果跟步行路线不完全一致。腾讯骑行模式是mode: 'bicycling'，高德也是mode: 'bicycling'，调用方式跟步行几乎一样。

我在开发骑行功能时发现一个有意思的现象：有时候骑行的预计时间比步行还长。原因是骑行路线会绕开部分步行快速通道（比如天桥、地下通道），反而兜圈子。如果产品上只展示“预计时间”，这种反直觉的结果会被用户吐槽，最好在UI文案上标注“骑行路线根据自行车道规划”。

4.5 统一封装，避免业务代码重复

既然要同时兼容腾讯和高德，我在项目里做了一个统一的路线服务封装。对外暴露方法时，只关心三个输入：

• 起点经纬度
• 终点经纬度
• 出行模式

内部再去判断当前用的是腾讯还是高德，拼参数、发请求、解析结果。这样页面层完全不用关心地图服务商是谁。

封装之后的调用大概是这种感觉：

async function getRouteWithMode(provider, mode, start, end) { if (provider === 'tencent') { return requestTencentRoute(mode, start, end); } if (provider === 'amap') { return requestAmapRoute(mode, start, end); } throw new Error('不支持的路线服务商'); }

每家返回的路线数据结构不一样，建议在解析层统一输出成这样的对象：

{ "distance": 1500, "duration": 1200, "points": [ { "latitude": 39.90923, "longitude": 116.397428 } ] }

distance的单位是米，duration的单位是秒。这样后面无论是地图渲染、距离展示、时间格式化，全都基于一套数据结构，省掉大量if else。

5. 地图渲染与路径展示

5.1 用map组件把地图铺起来

路线数据拿到之后，就是展示环节。微信小程序的地图展示直接用<map>组件：

<map id="routeMap" style="width: 100%; height: 400px;" latitude="{{centerLat}}" longitude="{{centerLng}}" markers="{{markers}}" polyline="{{polyline}}" include-points="{{includePoints}}" />

latitude和longitude控制地图中心，markers用来显示起点和终点标记，polyline用来画路线，include-points可以自动调整视野把所有点装进屏幕。

这里要注意一个渲染顺序的问题：一开始先拿到定位，把地图中心设在起点附近，再请求路径规划，拿到路线后更新polyline和includePoints。如果一次性想设置多个数据，建议用setData一起更新，减少渲染次数。

5.2 polyline画路线的正确姿势

polyline是<map>组件中用数组方式配置的一组线。一个路线对象大概长这样：

{ "points": [ { "latitude": 39.90923, "longitude": 116.397428 } ], "color": "#1A7FFF", "width": 6, "arrowLine": true }

这里最容易犯的错就是把腾讯或高德返回的原始字符串直接塞给points。组件要的是对象数组，不是字符串。我之前在代码里就出现过：

polyline: [{ points: res.routes[0].steps.map(step => step.polyline) }]

这样写看起来没什么问题，但如果是高德的数据源，step.polyline是一串字符串，整条线路就变成了一段抽风的折线。必须在解析层就把字符串拆成坐标数组，并拼接成一条完整的点序列。

上面这个坑还引申出另一个问题：路线的点数太多，setData的数据量大，页面渲染会卡。一条城市级的驾车路线，坐标点可能有上千个，不加处理直接渲染，低端手机会明显掉帧。我的处理方案是“抽稀”——每隔几个点取一个，保持路线形状的同时大幅减少数据量。对于折线型路线，抽稀对视觉效果影响很小，但对性能帮助很大。

5.3 起终点标记和气泡信息

起点和终点分别加一个marker，体验会好很多。markers的配置形如：

{ "id": 0, "latitude": 39.90923, "longitude": 116.397428, "title": "起点", "iconPath": "/assets/start.png", "width": 30, "height": 30 }

iconPath支持项目内的本地图片路径，建议直接用PNG格式的小图，尺寸控制在32像素以内，太大会挡住路线。官方文档里说大尺寸图标在某些机型上会出现锯齿，实测确实如此。

如果你还想展示距离和时间，可以在地图下方放一个卡片，卡片数据就是从封装层统一输出的distance和duration。这里有一个体验细节：距离大于1公里时用公里，小于1公里时用米，时间超过60分钟显示“X小时X分钟”。这些格式化逻辑很琐碎，但做好的话，产品质感会明显提升。

5.4 把视野调整到能看到整条路线

路线画好之后，地图视野要能容纳整条路线。实现方式有两种：

• 组件上直接传include-points="{{includePoints}}"，把所有路线坐标点放进去。
• 通过MapContext.includePoints动态调整。

用MapContext的时候，要先通过wx.createMapContext('routeMap', this)拿到上下文实例，然后调用：

mapContext.includePoints({ points: routePoints, padding: [35, 35, 35, 35], success: () => {} });

padding是用来控制路线距离屏幕边缘的留白，单位是像素，建议设置至少15像素以上，不然路线会贴边，看起来憋屈。这里还有一个注意点：如果路线点数太多，把整条路线的所有点都传给includePoints，部分安卓机型会出现缩放不平滑，甚至白屏。优化办法是先抽稀，再传给includePoints。

6. 高频问题与排坑实录

6.1 一张表搞定常见问题

我把这段时间碰到的问题整理成了一张速查表，方便排查。

表格没法写太细，我挑几个重要的展开说。

6.2 注意Key的防盗与配额管理

小程序端的Key是无法真正隐藏的，任何前端代码反编译后都能拿到。所以我能做的是外部防盗和内部限流两头堵。外部防盗就是前面说的绑定AppID，别人拿你的Key去请求接口，因为AppID对不上会被拒绝；如果服务商支持“IP白名单”，还可以再加一道限制。内部限流是在自己的后端加一层调用计数，比如每个用户每天最多规划20次，超了就走缓存或降级方案。

还有一个很少被人提的点：Key的配额是按“服务维度”分别计算的。路径规划和你用的地理编码、逆地理编码，各自消耗各自的额度。很多项目路径规划没超量，但地理编码超了，整个服务商接口可能在短时间内都无法访问。建议在后台给每个服务分别设置配额告警，超额的第一时间收到短信或邮件通知，别等到用户反馈才去查。

6.3 线上真机调试与性能优化

真机调试时，我习惯在开发者工具里打开Network面板，专门看一下地图服务请求的耗时、返回大小。有一次我发现腾讯的路径规划响应只有几十KB，但高德返回了近300KB，原因是高德会把每一步的详细指引文本、图标信息一并返回，而我只想画个线。这种冗余数据在小屏设备上会影响解析和渲染速度。

我的优化策略是：

• 不需要路段指引文字时，直接只提取polyline坐标点。
• 对路线点做抽稀，减少setData数据量。
• 避免频繁调用路径规划，用户拖动地图时不要实时重算，只在起点、终点变化后重算。
• 加一层简单的内存缓存，相同起终点和模式的路线在短时间内不重复请求。

路径规划服务本身是耗资源的，一个小程序如果用户量大，一天几万次调用很正常，做好缓存对配额和用户体感都重要。

6.4 线上应急切换的心得

我在项目里做了一个小开关，可以在远端配置当前地图服务商是“腾讯”还是“高德”。这个开关平时不常用，但真到腾讯某个时段接口限流或者高德配额告急时，后端只需要改一个配置，小程序端下次请求就会全部切到另一家。

最开始我还没做这个开关的时候，线上出过一次问题：某天下午路线规划接口开始大面积超时，用户反馈导航用不了。因为当时代码写死了只用高德，我只能发版修复，整整折腾了大半天。后来加了动态配置和失败自动降级，再遇到类似问题就从容多了。

这种“双服务商保底”的思路，本质上是用冗余换可用性。对于位置服务这种高度依赖第三方API的业务，我强烈建议有条件的话都做一版。

结个尾：我踩过这些坑之后的体会

我已经有一个多月没碰这个项目了，但回头再看，最想分享的不是某个函数怎么调，而是“地图服务对接本质上是数据对接，不是UI对接”这个认知。腾讯和高德虽然做的都是地图生意，但接口参数、返回结构、坐标系处理、配额规则各有各的脾气。你花在调试上的大量时间，往往不是地图画不出来，而是：腾讯要纬度在前，高德要经度在前；腾讯SDK已经把polyline解好了，高德还给你留一串字符串；腾讯的骑行路线绕天桥，高德的步行路线穿公园。这些差异才是真正决定开发体验的东西。

如果让我给一个新项目提建议，我会说：先用腾讯位置服务跑通整个Demo，因为它跟微信小程序的契合度确实更高；然后花一天时间把高德的getRoute也跑通，做一个切换开关放后端兜底；最后把Key、域名、坐标、polyline这四个最容易出问题的环节写进团队代码规范里，别让后面接手的人再踩一遍。做小程序地图就是一场细心活，希望你少走点弯路。