在微信小程序里做地图可视化时，原生 <map> 组件确实提供了几个开关，但把卫星底图、实时路网和业务侧的自定义瓦片层放在同一个视野中，并不是把属性全部打开就能完成。卫星图与路网图可以通过组件属性直接开启，而自定义瓦片层必须通过 MapContext 的 addCustomLayer 方法注入，并且需要单独管理它的 URL 模板、显示级别和叠加顺序。本文会围绕这一组合叠加场景，说明原生能力边界、XYZ 瓦片规范以及可直接落地的代码实现。
一、先分清卫星图、路网图与自定义图层的控制方式
原生 <map> 组件支持多个布尔属性，但它们的渲染层级并不对外暴露。enable-satellite 负责把底图切换成卫星影像，enable-traffic 负责加载实时交通路况，二者由腾讯地图引擎内部绘制。自定义瓦片层则完全不同，它通过 MapContext.addCustomLayer 这个命令式接口加载，因此初始化时机是在页面 onReady 之后拿到地图上下文再调用。
自定义图层的 position 参数决定它是贴在地面上还是浮在覆盖物上方。ground 类型会随着地图缩放和平移而变化，适合展示区域边界、热力区块、禁停区等与地理坐标强相关的数据；overlay 类型则更像一层固定蒙层，不随地图拖拽产生额外偏移，但在小程序地图中较少用于地理数据。实际做业务叠加时，优先选 ground。
层级控制是很多人困惑的地方。addCustomLayer 的 index 只用于自定义图层之间排序，数字越大越靠上，但它不直接控制原生卫星图和路网图的层级。原生卫星影像通常位于最底部，实时路网在底图之上，而自定义 ground 图层处于底图与路网之间的逻辑层级。若希望自定义瓦片盖住路网，需要把 index 调高，但真机上不同基础库可能表现略有差异。
二、自定义瓦片服务必须符合 XYZ 规范
自定义瓦片层加载的不是一张大图，而是按缩放级别切分的切片。常见切图规范为 XYZ，即 z 表示缩放层级，x 表示列号，y 表示行号，左上角为原点。地图平移和缩放时，SDK 会按照可视范围请求对应的 z/x/y 图片，因此 URL 模板必须把这些占位符暴露出来。
在写 src 时，通常写成 https://tiles.ipipp.com/biz/{z}/{x}/{y}.png 这种形式。addCustomLayer 会在请求瓦片时自动替换 {z}、{x}、{y}。如果你的瓦片服务使用 GCJ-02 坐标体系，还需要确认切图源是否与腾讯地图一致；若切图源是 WGS-84 标准墨卡托，直接叠加可能出现几十到几百米的偏移。此时需要在服务端重新投影，或者使用支持 GCJ-02 的瓦片服务。
除了 URL 模板，还要限制可用缩放级别。可以在业务逻辑中根据地图 scale 判断是否调用 addCustomLayer，避免在很小的级别加载大量无意义切图。一般建议在 10 到 18 级之间展示业务瓦片，具体范围以瓦片服务实际能力为准。
三、完整实现：WXML 配置与 JS 初始化
先在 WXML 中放置 <map> 组件，并给它一个稳定 id。卫星图和路网图使用组件布尔属性开启，中心点和缩放级别通过数据绑定控制。代码如下：
<view class="map-wrap">
<map
id="hybridMap"
class="map"
latitude="{{latitude}}"
longitude="{{longitude}}"
scale="{{scale}}"
enable-satellite="{{true}}"
enable-traffic="{{true}}"
show-location
></map>
</view>
JS 侧的核心逻辑在 onReady 里执行，因为只有页面渲染完成后才能通过 wx.createMapContext 获取地图上下文。调用 addCustomLayer 时，layerId 必须唯一，后续更新或移除都依赖这个 id；src 填写瓦片模板；position 设置为 ground；index 可以先给 2。代码如下：
Page({
data: {
latitude: 39.908823,
longitude: 116.397470,
scale: 14
},
onReady: function () {
this.mapCtx = wx.createMapContext('hybridMap', this);
this.addBizTileLayer();
},
addBizTileLayer: function () {
this.mapCtx.addCustomLayer({
layerId: 'biz-tiles',
src: 'https://tiles.ipipp.com/biz/{z}/{x}/{y}.png',
position: 'ground',
index: 2,
success: function (res) {
console.log('custom layer added', res);
},
fail: function (err) {
console.error('custom layer failed', err);
}
});
},
removeBizTileLayer: function () {
this.mapCtx.removeCustomLayer({
layerId: 'biz-tiles',
success: function (res) {
console.log('layer removed', res);
},
fail: function (err) {
console.error('remove failed', err);
}
});
}
});
这段代码中的 addCustomLayer 是异步接口，success 回调只代表图层加入成功，不代表所有瓦片已经下载完成。若瓦片服务地址配置了白名单，需要在微信公众平台配置 request 合法域名，同时确保 HTTPS 证书有效。动态更新图层时可调用 updateCustomLayer，隐藏时用 removeCustomLayer，避免页面卸载后残留图层引用。
四、常见问题：层级错乱、坐标偏移与性能调优
层级错乱最典型的表现是打开自定义图层后，卫星图被完全挡住，或者路网显示在自定义图层下方。前者通常是 index 设置得过高，后者则需要调整图层类型和层级。不要指望通过修改 WXML 属性来控制自定义图层，必须回到 MapContext 的 index 与 position 参数。真机预览时尤其要注意，iOS 和 Android 对 ground 图层的合成策略可能不同。
瓦片加载失败一般有两个原因：一是域名未配置到小程序后台的 request 合法域名，二是瓦片服务返回了 403 或 404。可以在开发者工具中打开调试面板，查看请求状态码。对于缓存问题，建议瓦片 URL 中带上版本参数，或者服务端设置合理的 Cache-Control，避免业务更新后仍然命中旧瓦片。
性能方面，自定义瓦片层会增加地图的请求数量，在快速缩放时尤其明显。优化思路包括：限制最小和最大缩放级别、降低瓦片图片体积、使用 WebP 格式、开启 CDN 加速，以及在图层不需要交互时临时隐藏。不要在一个地图实例上叠加过多自定义图层，通常保持 1 到 2 个地面图层足够大多数业务场景使用，过多的图层不仅增加渲染压力，还容易触发真机内存告警。