上周在客户现场调试一块数据大屏需求本身听着很简单地图页要能一键切换标准图、卫星图、卫星带路网还得单独能开实时路况和楼块显示。结果真正落地的过程中图层 API 的命名关系、Vue 生命周期里地图实例的创建时机、还有几个容易忽略的 zIndex 问题来来回回折腾了一整天。我顺手把这套东西梳理成了这篇实战笔记主要面向在 Vue 2 / Vue 3 项目里接高德地图、需要做多图层切换的开发者。文中会从加载方式选择、地图实例初始化、五类图层的底层关系一直讲到图层切换的完整实现和踩坑记录代码都是可以直接复制改用的水平。1. 高德地图 JSAPI 版本选择与脚本加载1.1 为什么直接上 JSAPI 2.0高德的 JS API 目前是 1.4.x 和 2.0 并存的状态。1.4 是上古时代的东西API 挂载到全局AMap对象上文档老、写法老对新特性支持也不到位。2.0 从 2020 年底发布到现在已经很稳定了我实测下来它在渲染性能、图层接口的一致性上比 1.4 强不少。如果你的项目是新的或者是老项目准备重构直接选 2.0 就行没必要再看 1.4 的历史包袱。要注意的是2021 年 12 月之后在控制台申请的新 key必须搭配安全密钥jscode使用。很多教程还停留在只用 key的阶段照着写会发现地图一直白屏。下面代码里我会把这个配置位放出来你们记得换成自己的安全密钥。1.2 用官方 loader 管理脚本加载接入方式有三种直接在 index.html 里写script标签、自己封装一个异步加载函数、用官方 npm 包amap/amap-jsapi-loader。最推荐的是第三种。理由很直接loader 内部做了脚本去重多次调用不会重复注入同一个 script返回 Promise配合async/await写初始化逻辑非常顺版本参数写在一个地方升级 JSAPI 版本只改一处。安装命令npm install amap/amap-jsapi-loader --save加载示例import AMapLoader from amap/amap-jsapi-loader; async function loadAMap() { const AMap await AMapLoader.load({ key: 你的高德Key, version: 2.0, plugins: [], // 按需挂载插件原生图层类不需要额外插件 }); return AMap; }securityJsCode如果不全局设置也可以在 loader 参数里直接传。不过我更习惯在入口文件顶部用window._AMapSecurityConfig统一配置因为有些老项目可能局部引入地图组件安全密钥集中声明比较好排查。提示如果项目里有多处需要地图能力建议把这个 loadAMap 函数放到独立的utils/amap.js里做一层 Promise 缓存。否则两个组件同时触发加载即使 loader 去重了也还是会多一次初始化判断。示例// utils/amap.js import AMapLoader from amap/amap-jsapi-loader; let amapPromise null; export function getAMap() { if (!amapPromise) { amapPromise AMapLoader.load({ key: 你的高德Key, version: 2.0, }); } return amapPromise; }这样不管项目里几个组件调用getAMap()最终只会执行一次真正的地图 SDK 加载。2. 初始化地图实例生命周期、容器尺寸与响应式陷阱2.1 为什么初始化必须放在 mounted 里地图实例必须绑定到一个真实存在于 DOM 中的容器节点上。Vue 的模板编译、指令渲染完成后DOM 才真正插入文档所以创建AMap.Map的代码必须放在mounted钩子里Vue 3 对应onMounted。放created里的话document.getElementById(mapContainer)多半是null直接报错。2.2 地图实例别塞进 data()这是新手最容易踩的坑也是 Vue 项目里比较隐蔽的问题。Vue 2 的data()里声明的对象会被Object.defineProperty递归劫持。AMap 的地图实例内部属性特别多、引用关系复杂把它放进data会导致 Vue 在初始化响应式属性时反复遍历实例内部对象轻则初始化卡顿重则直接栈溢出。Vue 3 里如果是reactive()包一个对象再往里塞地图实例一样会有类似的性能问题。正确做法是地图实例、图层实例这些非响应式的东西放在组件实例的普通属性上。Vue 2 写法export default { data() { return { activeLayer: normal, // 这个是可以响应式的 }; }, created() { // 在这里挂一个普通属性不会被响应式系统跟踪 this.map null; this.layers {}; }, mounted() { this.initMap(); }, methods: { async initMap() { const AMap await getAMap(); this.map new AMap.Map(mapContainer, { viewMode: 3D, zoom: 12, center: [116.397428, 39.90923], }); }, }, };created里给this直接挂属性是不走data的响应式转化的所以后面赋地图实例没有性能风险。Vue 3 的setup里就更好办用一个普通的let map null变量或者shallowRef/markRaw包一层都可以。2.3 基础初始化参数怎么选常用初始化参数我整理成表格参数说明我的推荐值viewMode2D 平面模式 / 3D 透视模式大屏或需要楼块效果用3Dzoom初始缩放级别范围由zooms决定城市尺度用11~13center中心点经纬度按业务场景定zooms可缩放级别范围默认[2, 20]做全球展示可以放宽pitch俯仰角3D 模式生效楼块视角建议45~60mapStyle个性化地图样式 ID默认即可高德控制台可自定义viewMode: 3D并不是必须的。如果你只做标准切换2D 也完全够。我之所以默认开 3D是因为标题里那个楼块图层要出效果必须配合 3D 视角和一定的pitch否则楼块就是个纯色色块看不出高度。2.4 组件销毁时释放地图地图实例会挂事件、发请求、渲染 canvas 和瓦片图片组件销毁后如果不释放等于一直白占内存。Vue 2 在beforeDestroy里执行Vue 3 在onBeforeUnmount里执行beforeDestroy() { if (this.map) { this.map.destroy(); this.map null; } }AMap.Map.destroy()会注销事件、清空容器 DOM是最干净的方式。比单纯map null靠谱得多。3. 从 API 命名看懂五类图层底图与叠加层的组合规则3.1 别把图层类和实例搞混高德把这五类图层封装成不同构造器名字分层级AMap.TileLayer标准瓦片图层AMap.TileLayer.RoadNet路网图层叠加在底图上显示道路名称、路网结构AMap.TileLayer.Satellite卫星底图AMap.TileLayer.Satellite.RoadNet卫星图 路网标注官方已经把两者合并封装AMap.TileLayer.Traffic实时路况图层AMap.Buildings楼块图层3D 白模/色块注意AMap.TileLayer.Satellite.RoadNet不是两个类它是一个组合类。它和卫星图 路网图层叠加在效果上类似但它内部已经做了级别映射和透明度处理直接用new AMap.TileLayer.Satellite.RoadNet()就行不需要你同时建两个图层去管理。3.2 核心概念底图与叠加层的区分这五个图层不是平等关系。我习惯把它们拆成两层底图层标准图默认自带或卫星图二选一叠加层路网、实时路况、楼块可以叠加在底图之上。搞清这个关系切换逻辑就顺了。很多项目把五个选项做成并列的单选切换时无脑remove所有图层再add选中的结果发现路况和楼块被覆盖掉了。正确思路是先切底图再按需叠加叠加层。3.3 五个图层的适用场景与 zIndex图层构造器典型场景注意点标准图层AMap.TileLayer()日常地图展示地图初始化就自带不用额外 add实时路况AMap.TileLayer.Traffic()交通监控、出行类场景支持自动刷新卫星图AMap.TileLayer.Satellite()土地、工程、农业展示底图较暗叠加路网后更易读卫星路网AMap.TileLayer.Satellite.RoadNet()兼顾地理细节与路名底层原理 卫星 道路标注楼块AMap.Buildings()3D 城市展示需viewMode: 3D才出效果高德的图层系统给各个内置图层预设了 zIndex 区间正常用map.add(layer)时生成顺序已经能让叠加层盖在底图上。比如新建一个AMap.TileLayer.Satellite()再用map.add(roadNetLayer)路网会自动显示在卫星图上方。只有当你手贱去手动改 zIndex 时才会出现路网被卫星图盖住这类问题。3.4 实时路况图层的刷新参数交通路况是动态数据高德默认支持自动刷新const trafficLayer new AMap.TileLayer.Traffic({ autoRefresh: true, // 是否自动刷新 interval: 180, // 刷新间隔秒 });我的经验实时路况设 3 分钟刷新一次足够。如果是演示大屏、非实时监控场景把autoRefresh关掉只在事件驱动时手动trafficLayer.reload()刷新数据能省不少请求。4. 图层切换功能完整实现底图 add/remove 与叠加层 show/hide4.1 把图层实例统一缓存所有图层实例只创建一次后面只做显示/隐藏或者 add/remove避免反复创建开销。组件里我用一个this.layers {}普通属性来存。created() { this.map null; this.layers {}; }, methods: { async initMap() { const AMap await getAMap(); this.map new AMap.Map(mapContainer, { viewMode: 3D, zoom: 13, center: [116.397428, 39.90923], pitch: 45, }); this.layers { normal: null, // 默认标准图层由 map 自动创建这里不新建 roadNet: new AMap.TileLayer.RoadNet(), satellite: new AMap.TileLayer.Satellite(), satelliteRoad: new AMap.TileLayer.Satellite.RoadNet(), traffic: new AMap.TileLayer.Traffic({ autoRefresh: true, interval: 180, }), building: new AMap.Buildings({ merge: true, zIndex: 120, }), }; }, }关于标准图层new AMap.Map(...)初始化时内部已经自动创建了一个标准瓦片图层放在地图最底层。所以标准图层这个选项不需要新建实例只需要把其他图层隐藏/移除就能回到标准模式。如果你的代码里再add一个new AMap.TileLayer()其实是叠了两层标准瓦片浪费请求还有可能造成闪烁。4.2 用 show/hide 还是 add/remove图层实例有两个操作维度layer.setMap(map)或map.add(layer)/map.remove(layer)控制是否挂载到地图layer.show()/layer.hide()控制自身可见性。hide只是隐藏图层仍挂在地图上。从效果上讲隐藏和移除对用户没区别性能上看show/hide不做瓦片销毁重建切换更快但从资源释放角度长期不用的图层remove掉更省。我实际项目的折中方案是底图类标准、卫星、卫星路网用 add/remove 切换叠加类路况、楼块、路网标注用 show/hide 切换。这样既保证切换响应快也不会叠加多层底图。4.3 五选项切换函数methods: { switchLayer(type) { const { map, layers } this; // 1. 先把底图类全部摘掉 map.remove([layers.satellite, layers.satelliteRoad]); // 2. 按选项挂载对应底图 if (type normal) { // 不做任何 add默认标准底图自然显示 } else if (type satellite) { map.add(layers.satellite); } else if (type satelliteRoad) { map.add(layers.satelliteRoad); } // 3. 叠加层按需显示/隐藏 if (type traffic) { layers.traffic.show(); } else { layers.traffic.hide(); } if (type building) { layers.building.show(); } else { layers.building.hide(); } this.activeLayer type; }, }这个函数的核心逻辑就三句话先清底图再挂选中底图最后处理叠加层。路网标注是 satelliteRoad 自带的一部分所以单独使用AMap.TileLayer.RoadNet()的场景通常只有标准底图 路网叠加如果你业务上有这个选项在上面代码的normal分支里加一行map.add(layers.roadNet)就行。4.4 完整组件示例template div classmap-wrap div idmapContainer classmap-container/div div classlayer-switch span v-foritem in layerOptions :keyitem.value :class{ active: activeLayer item.value } clickswitchLayer(item.value) {{ item.label }} /span /div /div /template script import { getAMap } from /utils/amap; export default { data() { return { activeLayer: normal, layerOptions: [ { value: normal, label: 标准 }, { value: satellite, label: 卫星 }, { value: satelliteRoad, label: 卫星路网 }, { value: traffic, label: 路况 }, { value: building, label: 楼块 }, ], }; }, created() { this.map null; this.layers {}; }, mounted() { this.initMap(); }, methods: { async initMap() { const AMap await getAMap(); this.map new AMap.Map(mapContainer, { viewMode: 3D, zoom: 13, center: [116.397428, 39.90923], pitch: 45, }); this.layers { satellite: new AMap.TileLayer.Satellite(), satelliteRoad: new AMap.TileLayer.Satellite.RoadNet(), traffic: new AMap.TileLayer.Traffic({ autoRefresh: true, interval: 180, }), building: new AMap.Buildings({ zIndex: 120, }), }; this.switchLayer(normal); }, switchLayer(type) { const { map, layers } this; map.remove([layers.satellite, layers.satelliteRoad]); if (type satellite) { map.add(layers.satellite); } else if (type satelliteRoad) { map.add(layers.satelliteRoad); } layers.traffic[type traffic ? show : hide](); layers.building[type building ? show : hide](); this.activeLayer type; }, }, beforeDestroy() { if (this.map) { this.map.destroy(); this.map null; } }, }; /script style scoped .map-wrap { width: 100%; height: 100%; position: relative; } .map-container { width: 100%; height: 100%; } .layer-switch { position: absolute; top: 16px; right: 16px; background: #fff; border-radius: 6px; box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15); display: flex; flex-direction: column; padding: 6px; z-index: 10; } .layer-switch span { padding: 8px 16px; cursor: pointer; text-align: center; border-radius: 4px; font-size: 14px; } .layer-switch span.active { background: #1890ff; color: #fff; } /style这段代码我直接用在过两张大屏项目里改一下中心点和业务字段就能跑。Vue 3 的话把mounted/beforeDestroy换成onMounted/onBeforeUnmountgetAMap()和图层逻辑完全不用动。5. 实测中容易踩的六个坑5.1 容器高度塌陷导致白屏高德地图容器必须有明确高度它不会像普通 div 那样根据内容自动撑开。常见写法height: 100%如果父级没有给高度最后计算结果是auto地图组件拿到高度 0渲染出来一片空白或者只有 logo。排查套路打开控制台看#mapContainer的计算样式给地图容器加一个固定高度比如600px测试如果正常了就是父级高度链路断了。大屏项目里最稳妥的做法是让地图容器绝对定位铺满父层.map-wrap { position: relative; width: 100%; height: 100%; } .map-container { position: absolute; inset: 0; }5.2 安全密钥未配置导致初始化和图层都无响应2021 年 12 月之后申请的 key不配securityJsCode直接无法正常加载地图。症状是 loader 能 load 成功AMap.Map也不报错但地图区域全灰network 里能看到请求返回错误码或 403。解法是在入口位置提前声明window._AMapSecurityConfig { securityJsCode: 你的安全密钥, };有些老项目可能挂在main.js里和 key 写死在一起也可以。关键是这个赋值必须在初始化地图之前执行。5.3 地图实例放进 data 导致页面卡死前面说过原因。这里给一个更明显的判断信号如果你的页面在mounted卡住控制台报类似Maximum call stack size exceeded的错十有八九是把map或 layer 对象写进了data()。检查一下 data 里有没有地图实例、marker 集合、图层数组这类东西。5.4 keep-alive 场景下重复初始化地图后台管理系统喜欢用keep-alive缓存页面路由切换时组件不会销毁beforeDestroy不触发。结果是用户切换几次菜单后组件里同时存在多个地图实例内存一路涨。我的处理方案不用 keep-alive 缓存带地图的页面或者监听activated钩子做重新激活逻辑activated() { if (this.map) { this.map.resize(); // 从缓存重新激活时强制重算容器尺寸 } }, deactivated() { // 可以在这里暂停路况自动刷新 this.layers.traffic this.layers.traffic.hide(); },如果业务不允许去掉 keep-alive至少要在deactivated里把自动刷新的图层停掉避免路由切走了还在持续请求瓦片。5.5 hide 之后图层残影不消失个别浏览器加高德版本下layer.hide()后瓦片没有立刻消失尤其是楼块图层会留下半透明的块状残影。这种情况别纠结直接换成layer.setMap(null)或者map.remove(layer)移除是最彻底的。所以我上面完整示例里底图切换用的是 remove/add只有叠加层用 show/hide如果遇到残影把叠加层也换成 setMap(null) 即可。5.6 高频率切换触发的瓦片洪水用户快速点击卫星、路况、标准、楼块几个按钮时底层会同时发出多个瓦片请求而且大多数是重复的。我加了一个简单防抖clearTimeout(this.timer); this.timer setTimeout(() this.switchLayer(type), 200);另外切走一个底图时高德并不会立刻终止已发出的瓦片请求所以对于一些对流量敏感的 3G/4G 场景我会在map.remove前置条件里判断目标底图和当前底图不同才执行减少无谓切换。6. 图层管理的封装思路与后续扩展6.1 抽一个 LayerManager 类如果项目里多个页面都要用这组图层把图层实例和切换逻辑抽成一个类会更清爽。我通常这样组织// utils/layerManager.js export default class LayerManager { constructor(map) { this.map map; this.layers {}; } add(name, layer) { this.layers[name] layer; return this; } setBase(name) { const baseNames [normal, satellite, satelliteRoad]; baseNames.forEach((key) { if (key normal) return; if (this.layers[key]) { this.map.remove(this.layers[key]); } }); if (name ! normal) { this.map.add(this.layers[name]); } } toggle(name, visible) { if (!this.layers[name]) return; if (visible) { this.map.add(this.layers[name]); this.layers[name].show(); } else { this.layers[name].hide(); } } reset() { this.setBase(normal); Object.values(this.layers).forEach((layer) layer.hide()); } }组件里只保留 UI 状态图层的存在与否交给类内部管理后续加新图层只需要在initMap里layerManager.add(xxx, new AMap.xxx())一行。6.2 和业务数据图层的叠加顺序实际项目通常不止这五个图层还会叠加轨迹线、热力图、海量点。一个经验法则是数据图层矢量的 zIndex 区间控制在 100-200确保它们在底图之上、在 UI 控件之下。AMap.Buildings默认 zIndex 是 120和轨迹线并存时容易互相遮挡建议把楼块 zIndex 调低到 100 左右轨迹线设 110 以上用户交互时点击命中率会高很多。6.3 大屏项目的额外建议最后说个大屏项目的细节地图容器在浏览器窗口 resize 时高德地图虽然会自动 resize但如果你是从菜单收起这类布局变化触发的尺寸变化偶尔会漏帧。可以手动补一下window.addEventListener(resize, () { if (this.map) this.map.resize(); });还有楼块图层对 GPU 要求不低老机器上开楼块 3D 视角 实时路况三件套帧率会明显下降。如果客户机器配置一般我通常默认只开标准底图 楼块路况按需呼出比全开体验好得多。