企业官网建设流程全解析

1. 从一次"弹窗里地图白屏"的排查说起

vue 项目里嵌地图，elementUI 负责表单与弹窗，腾讯地图负责底图渲染——这套组合在国内的门店管理、物流调度、设备巡检、政企后台类系统里出现频率相当高。原因也不复杂：elementUI 在 Vue2 时代几乎是后台管理系统的默认组件库，而腾讯地图在地址解析、行政区划、微信生态打通上确实顺手。但这三个东西凑一块，问题就来了：地图实例是命令式的、依赖真实 DOM 尺寸的、生命周期完全不受 Vue 控制的原生对象，而 elementUI 的弹窗、标签页又习惯用display: none来做显隐。两套逻辑一撞，最典型的表现就是"弹窗打开了，地图区域一片白"。

我第一次遇到这个场景是在做一个门店选址的模块：左侧 el-form 填地址，右侧弹窗里出地图选点。代码逻辑看着没问题，mounted里new TMap.Map()一把梭，结果弹窗打开后白屏，控制台干干净净没有任何报错。折腾了小半天才发现，问题根本不在代码写错了，而在初始化时机——new TMap.Map()执行的那一刻，弹窗容器还没展开，宽高都是 0，地图渲染引擎拿到的是一块 0×0 的画布。

所以这篇东西不打算只给你一段能跑起来的代码，那种东西网上一搜一大把。我想把压在这套组合下面的东西翻出来讲清楚：key 该怎么申请才不返工、地图实例该挂在 Vue 的哪个位置、elementUI 的几个常见组件和地图同框时到底哪里会出问题、坐标系为什么总差那么几百米。看完你至少能少走我走过的那些弯路。

1.1 为什么 vue 加 elementUI 再挂腾讯地图，坑比想象中多

先把三者的脾气说清楚，后面很多"怪现象"就都有解释了。

腾讯地图 JS API GL 是命令式的、有状态的、生命周期自管的。你new出来一个TMap.Map实例，它就自己接管了一块容器 DOM，自己挂了 canvas、自己监听了一堆事件、自己维护了渲染循环。它不管你 Vue 组件什么时候销毁，也不会因为你的data变了就自动刷新。你要销毁它，得显式调destroy()。

Vue 是声明式的、响应式的、以数据驱动视图的。它的核心假设是"视图是数据的映射"。而地图实例恰恰不是数据，是一个庞大的第三方对象，里面可能有几千个内部属性、几十个 DOM 引用、还有闭包和定时器。如果你不小心把它塞进data()，Vue2 会递归遍历这个对象、给每个属性加getter/setter，轻则卡顿，重则直接栈溢出。

elementUI 的显隐逻辑则更微妙。el-dialog默认走的是v-show语义，第一次打开前 DOM 已经存在，但是display: none；el-tabs的非激活面板同样是display: none。而display: none的元素，offsetWidth和offsetHeight都是 0，getBoundingClientRect()返回全 0。地图初始化时如果读到 0 尺寸，渲染引擎根本不知道要画多大，白屏或者只画出一小块。

这三者单拎出来都没毛病，凑在一起就要求你在"什么时候初始化、什么时候销毁、什么时候通知重新计算"这三个时间点上格外清醒。下面所有的坑，本质上都是这三个时间点没对齐。

1.2 先把职责边界划清楚，再动手写代码

在动手之前，我建议先把分工写下来贴在心里，能省掉大量无效排查：

把这张表记住，很多问题你自己就能定位。比如"地图不显示"，先问三个问题：容器有尺寸吗？初始化时机对了吗？key 通过校验了吗？三问下来，八成能命中。

提示：如果你所在的团队还在用 Vue3，思路完全一样，只是"非响应式"这一件事从"不要写进 data"变成了"记得用 markRaw 或普通变量包一下"，后面会细说。

2. 密钥申请与控制台配置：动手前必须定下来的三件事

很多教程上来就是一行<script src="https://map.qq.com/api/gljs?v=1.exp&key=你的KEY">，把 key 当成一个随便填的字符串。实际上腾讯位置服务的 key 是分产品的，选错类型后面全是返工；白名单配置不对，本地开发阶段就会一直报校验失败；至于网上那些"免费共享 key"，坑比你想的深。这三件事都定下来，再写代码才踏实。

2.1 key 的产品类型选错了，后面全是返工

腾讯位置服务的 key 按使用端分成好几类，前端项目和你在后端调的是两码事：

前端渲染用的一定是JavaScript API GL这个类型。常见误区是拿 WebService 的 key 去前端加载 gljs，结果一直提示 key 无效；或者反过来，把 GL 的 key 拿到后端调 WebService，同样不通。同一个账号下可以建多个 key，分别用于不同端，也可以在一个 key 上勾选多个可用产品——具体在控制台的 key 管理页面里能看到"可用产品"的勾选项，申请时就把该勾的勾上，省得后面改。

还有一个容易忽略的点：同一个 key 同时被多个项目复用会造成配额互相挤占。腾讯位置服务对个人开发者和企业开发者给的日调用量、并发上限是不一样的，测试环境和生产环境如果共用一个 key，压力测试一跑，线上就报配额超限。我的习惯是至少分三个 key：本地调试、测试环境、生产环境，各自独立配置白名单，出问题一眼就能判断是哪个环境在刷量。

2.2 域名白名单在开发阶段怎么放行才不挖坑

白名单这件事，本质上是一个防滥用机制。你在控制台给 key 配置了允许的域名（Referer），浏览器在加载地图脚本时，服务端会校验请求来源，不匹配就拒绝。这个设计是对的，但配置方式不对就会白白浪费时间。

我的配置习惯是这样的：

• 生产环境只填正式域名，精确到二级域名，不要用泛域名一把梭。
• 测试环境填测试域名。
• 本地开发这个 key 里填localhost和127.0.0.1，另外如果你用的是局域网 IP 调试真机，还要把形如192.168.x.x的地址也填进去。

注意：本地调试最常见的报错是"key 校验失败"或者"域名未授权"，此时先别怀疑代码，去控制台看一眼白名单，八成是漏了localhost或者用了 IP 访问但没配 IP。

另外，很多人的项目现在流行用构建工具做代理，本地开发时页面实际跑在localhost:8080，但请求地图脚本时走的是代理路径。这种情况下白名单校验的是浏览器地址栏里的域名，不是代理后的目标域名，所以还是填localhost。这个逻辑搞清楚，能少排查一轮。

2.3 关于来路不明的"共享 key"，把话说透

网上确实流传着各种"公共 key""测试 key""第三方共享 key"，搜索热词里这类内容也不少。我不建议用，理由不是道德说教，而是纯粹的工程风险：

第一，配额不受你控制。共享 key 的调用量是全互联网共用的，可能某天早上你的地图突然加载不出来，只是因为别人把日配额刷爆了。你查日志查半天，最后发现根本不是自己的问题。

第二，随时可能失效。提供方一句话就能把 key 下线，你的线上系统会在你最不希望的时候挂掉，而你还完全不知道发生了什么。

第三，存在数据风险。你的地图请求、地理编码结果都会经过对方配置的域名体系，业务坐标、地址数据在不在你的掌控里，很难说清楚。

正路只有一条：自己注册、自己申请、按环境分开配 key。这件事花不了十分钟，但能省掉未来无数个深夜的应急电话。

3. 把地图实例安全地塞进 vue 组件

key 拿到手，接下来就是代码结构。这一块是两个问题：怎么加载地图脚本，以及地图实例该放在 Vue 组件的哪个位置。第二个问题如果做错了，性能问题和诡异 bug 会一直缠着你。

3.1 script 全局加载与 npm 引入的取舍

腾讯地图 GL 版本官方主推的是 script 标签全局加载：

<script src="https://map.qq.com/api/gljs?v=1.exp&key=YOUR_KEY"></script>

加载完成后，全局会挂一个TMap对象，所有 API 都从它身上取。这种方式最稳，官方的文档和示例全是基于它的。

但在 Vue 项目里，直接在index.html里写死 script 有几个不便：key 会硬编码进模板、首屏会多一次同步阻塞、如果你只想在某个路由下用地图，那其他页面白白承担了加载成本。所以更推荐的做法是动态注入脚本 + Promise 封装：

// utils/loadTMap.js let loaderPromise = null export function loadTMap(key) { if (loaderPromise) return loaderPromise loaderPromise = new Promise((resolve, reject) => { if (window.TMap) { resolve(window.TMap) return } const script = document.createElement('script') script.src = `https://map.qq.com/api/gljs?v=1.exp&libraries=service&key=${key}` script.async = true script.onload = () => resolve(window.TMap) script.onerror = () => reject(new Error('腾讯地图脚本加载失败')) document.head.appendChild(script) }) return loaderPromise }

这里有几个细节值得说。libraries=service是显式声明要加载服务类模块（搜索、地理编码、路线规划都在里面），不写的话部分版本调TMap.service会是 undefined；loaderPromise做单例缓存，防止多个组件同时挂载时重复注入脚本、导致同一份 API 被加载两次；window.TMap的存在性判断是为了兼容热更新和组件重挂载的场景。

有些人喜欢用 npm 包的方式引入，但腾讯地图 GL 并没有一个官方长期维护的 npm 包，第三方封装质量参差不齐，版本也容易滞后。我的建议是老老实实用动态脚本注入，配一层自己的封装，可控性最高。

3.2 地图实例为什么绝对不能放进 data

这是我认为整套组合里最容易被忽视、后果又最严重的一个坑。

// 反例：不要这么写 export default { data() { return { map: null // 危险 } }, async mounted() { this.map = new TMap.Map(this.$refs.container, { zoom: 12 }) } }

问题出在 Vue2 的响应式机制上。data里声明的属性会被Object.defineProperty递归处理，Vue 会遍历对象的所有自有属性、逐个套上 getter/setter，为的是能追踪变化。但TMap.Map实例内部结构极其庞大——里面挂着渲染器、图层管理器、事件派发器、几十上百个内部引用，甚至还有指向 DOM 和 canvas 的引用。Vue 一旦递归进去，轻则初始化明显卡顿几百毫秒，重则因为循环引用直接报栈溢出，或者在地图内部频繁改动自身状态时触发大量无意义的依赖更新。

正确做法是让地图实例活在响应式系统之外：

export default { name: 'MapPanel', data() { return { // 只放真正需要驱动视图的数据 markers: [], centerLabel: '' } }, created() { // 不在 data 里声明，赋值到实例上就是普通属性，无响应式开销 this.map = null this.markerLayer = null }, methods: { async initMap() { const TMap = await loadTMap(process.env.VUE_APP_TMAP_KEY) this.map = new TMap.Map(this.$refs.mapContainer, { center: new TMap.LatLng(39.98412, 116.307484), zoom: 12, pitch: 0, rotation: 0, viewMode: '2D' }) } } }

在 Vue2 里，只要map没有在data()的返回值里预先声明，通过this.map = ...赋的值就是非响应式的普通属性，Vue 不会碰它。这里要特别注意：别在data()里写map: null占位，很多人为了"规范"这么做，结果前功尽弃。

到了 Vue3 情况变了，ref和reactive用的是 Proxy，任何挂进去的对象都会被代理，所以务必用markRaw：

import { markRaw, ref } from 'vue' const map = ref(null) map.value = markRaw(new TMap.Map(el, options))

或者干脆别用响应式容器，用模块级的普通变量或者shallowRef。核心原则只有一句话：地图实例是外部世界的东西，别让框架去管它。

3.3 容器高度与生命周期：白屏的三个直接诱因

白屏这个现象看着玄学，其实诱因基本就三个。

第一是容器没有明确高度。div默认高度由内容决定，而地图容器初始化时里面什么都没有，算出来就是 0。所以必须显式给高度，可以是固定像素，也可以是父级 flex 布局下的flex: 1加上height: 100%，但整条链路上每一级父元素都得有确定高度：

.map-container { width: 100%; height: 100%; min-height: 400px; } .map-wrapper { height: 600px; position: relative; }

第二是初始化时机太早。如果在mounted里立刻初始化，而容器所在的父组件还在做v-if切换、动画还没结束，尺寸可能是错的。稳妥的做法是初始化前先确认clientWidth和clientHeight都大于 0。

第三是初始化后容器尺寸变了但没通知地图。比如侧边栏折叠、浏览器窗口缩放、父容器从隐藏变显示，这时候地图内部的渲染尺寸还是旧的，表现为"地图画到一半就没了"或者"右下角有一块空白"。腾讯地图 GL 实例提供了resize()方法，容器尺寸变化后调一下，它会重新测量并重绘。

onResize() { if (this.map && typeof this.map.resize === 'function') { this.map.resize() } }

配合一个监听窗口尺寸的处理：

mounted() { this._onResize = () => this.onResize() window.addEventListener('resize', this._onResize) }, beforeDestroy() { window.removeEventListener('resize', this._onResize) }

顺手把监听解绑，这是我见过最多人忘的一步。

4. 和 elementUI 组件同框时的真实痛点

到了这一步，地图本身能正常显示了。真正折磨人的是和 elementUI 组件配合的部分。el-dialog、el-tabs、el-select、el-table这四个组件和地图同框时，几乎每个都会带来一个专属问题。

4.1 el-dialog 里初始化地图，时机比代码本身更重要

el-dialog的默认行为是：内容 DOM 在首次渲染时就存在，但不打开的时候被display: none藏着。这意味着如果你在组件mounted里就初始化地图，那一刻弹窗还没开，容器尺寸是 0。

解决方案有三种，我按推荐程度排：

方案一，用@opened事件。opened是弹窗展开动画结束之后触发的，此时容器已经有了真实尺寸，是最保险的时机：

<el-dialog title="选择门店位置" :visible.sync="dialogVisible" width="720px" @opened="handleDialogOpened" @closed="handleDialogClosed" > <div ref="mapContainer" class="map-container"></div> </el-dialog>

methods: { async handleDialogOpened() { if (this.map) { this.map.resize() return } await this.initMap() this.bindMapEvents() }, handleDialogClosed() { // 弹窗关闭时保留实例，下次打开 resize 即可，避免反复创建 // 若内存敏感，也可以在这里 destroy } }

这里做了一个取舍：不销毁，只 resize。因为弹窗开关很频繁，每次销毁重建地图的代价（重新拉瓦片、重建图层）比 resize 大得多。但如果你的弹窗里地图非常重、而且开关频率极低，销毁重建反而更省内存，这个要看具体场景。

方案二，加destroy-on-close加v-if。弹窗关闭时销毁子内容，下次打开重新创建 DOM，这样可以在mounted里直接初始化。缺点是每次打开都重建，体验上会有一次可见的加载空档。

方案三，手动$nextTick加尺寸轮询。不太推荐，属于兜底手段，容易写出脆弱代码。

提示：有一种情况特别容易踩坑——弹窗配合append-to-body使用时，地图容器会被移到body下，如果你在弹窗内部用相对样式定位其他覆盖物，位置可能会错乱。要么不用append-to-body，要么把定位样式改用视口坐标系。

4.2 el-tabs 切换后地图错位，resize 之前先想清楚

el-tabs的机制和弹窗类似，非激活面板是display: none。所以常见现象是：地图在第二个标签页里，第一次切过去时地图只画了一部分，或者干脆是空白的。

处理思路是监听标签页切换，在切换之后调用resize()。但这里有个细节：切换动画和数据渲染是异步的，直接在tab-click里调resize()，容器可能还没真正显示出来尺寸。稳妥写法是套一层$nextTick，再加一个极短的延迟兜底：

handleTabClick(tab) { if (tab.name !== 'map-tab') return this.$nextTick(() => { setTimeout(() => { this.map && this.map.resize() }, 50) }) }

那个 50 毫秒看着很不优雅，但确实是我试过最稳的。原因是一些动画和布局重排在下一个宏任务才完成，纯$nextTick有时还是早了一步。如果你用的是无动画配置或者用了lazy模式，可以省掉这段延迟。

另一条路是把地图放在默认激活的标签页里，或者让地图所在的标签页用v-if延迟渲染。做法虽然笨，但确实省心——很多"为什么切回来地图就歪了"的问题，本质上都是第一次显示时尺寸不对。

4.3 el-select 搜索联动与 el-table 固定列的层叠冲突

这两个问题放在一起说，因为它们都涉及"地图和 elementUI 组件的层叠与数据联动"。

先说 el-select 搜索联动。典型场景是：下拉框里输入关键字，调腾讯地图的搜索服务拿到候选地点，选中后地图飞到那个点并落一个标记。这里要注意的是搜索请求要防抖，不然用户每敲一个字符就发一次请求，配额很快见底：

data() { return { keyword: '', searchTimer: null, options: [] } }, watch: { keyword(val) { clearTimeout(this.searchTimer) if (!val) { this.options = [] return } this.searchTimer = setTimeout(() => this.doSearch(val), 350) } }, methods: { async doSearch(keyword) { if (!this.map) await this.initMap() const TMap = window.TMap const search = new TMap.service.Search({ pageSize: 10 }) const res = await search.search(keyword) this.options = (res.data || []).map(item => ({ label: item.title, value: item.id, location: item.location })) } }

选中后的处理就是拿location.lat和location.lng飞过去：

handleSelect(item) { const TMap = window.TMap this.map.setCenter(new TMap.LatLng(item.location.lat, item.location.lng)) this.map.setZoom(16) this.markerLayer.setGeometries([ { id: 'selected', styleId: 'marker', position: new TMap.LatLng(item.location.lat, item.location.lng) } ]) }

再说 el-table 固定列的问题。搜索热词里有个"elementui 报表的固定列有时候会变透明"，这个现象在"地图加表格上下同屏"的布局里确实会碰到，表现形式是固定列背景变透明，下面的地图 canvas 透过来，看着像渲染错乱。

根因通常是层叠上下文和 z-index 的组合问题。地图容器里的 canvas 会形成一个独立的绘制层，而 el-table 的固定列通过绝对定位加transform实现，一旦两者的层叠上下文关系没理清楚，就可能互相穿透。另外也有渲染引擎层面的偶发 bug，表现为滚动瞬间闪一下。

排查和修复的顺序我一般是这样的：

1. 检查地图容器的父级，确保它和表格不在同一个position: relative但 z-index 未定义的层里。
2. 给地图容器显式声明z-index: 1，给表格容器声明更高的z-index，别让它们处于同一层。
3. 给固定列补上明确背景色，避免依赖主题变量被覆盖：

.el-table__fixed-right, .el-table__fixed { background-color: #fff; z-index: 3; } .el-table__fixed-right::before, .el-table__fixed::before { display: none; }

4. 如果确认是浏览器渲染层的问题，可以给固定列加transform: translateZ(0)强制提升为独立合成层，通常能消除闪烁和穿透。

注意：不要用无脑调大 z-index 的方式去压，压住一个组件往往会引发其他弹层（比如 el-select 下拉、el-tooltip）的遮挡问题。层叠问题的正解永远是"理清层叠上下文"，而不是"比大小"。

5. 业务核心交互：标记、信息窗口与坐标体系

地图能显示、能嵌进组件之后，业务上真正要用的是这些东西：落点标记、点击弹信息、定位、路线。这一块是腾讯地图 GL API 用得最频繁的部分，也是相对稳定的部分，但坐标系这个坑必须单独拿出来说。

5.1 MultiMarker 与 InfoWindow 的标准配合

单点用Marker也行，但项目里一旦超过几个点，就该用MultiMarker统一管理。它的好处是图层化，批量更新、按 id 增删都很方便，性能也比一个个new Marker好得多。

initMarkerLayer() { const TMap = window.TMap this.markerLayer = new TMap.MultiMarker({ map: this.map, styles: { default: new TMap.MarkerStyle({ width: 24, height: 34, anchor: { x: 12, y: 34 }, src: 'https://mapapi.qq.com/web/lbs/javascriptGL/demo/img/markerDefault.png' }), active: new TMap.MarkerStyle({ width: 32, height: 44, anchor: { x: 16, y: 44 }, src: 'https://mapapi.qq.com/web/lbs/javascriptGL/demo/img/markerDefault.png' }) }, geometries: [] }) this.infoWindow = new TMap.InfoWindow({ map: this.map, position: new TMap.LatLng(39.98412, 116.307484), offset: { x: 0, y: -40 }, enableCustom: false }) this.infoWindow.close() }

这里有个anchor参数特别值得说。默认情况下，标记图片的位置是按左上角对齐坐标点的，结果就是"图钉尖没扎在点上，而是整个图标偏到右下"。anchor定义的是图标中哪个像素点对准坐标，图钉类图标一般设成"宽度一半、高度全高"，也就是尖端位置。

点击标记弹信息窗口是最高频的交互：

bindMarkerEvents() { this.markerLayer.on('click', (evt) => { const geometry = evt.geometry this.infoWindow.setPosition(geometry.position) this.infoWindow.setContent(` <div style="padding:8px 4px;min-width:160px;"> <div style="font-weight:600;margin-bottom:4px;">${geometry.properties.title}</div> <div style="color:#666;font-size:12px;">${geometry.properties.address}</div> </div> `) this.infoWindow.open() this.markerLayer.updateGeometries([ { id: geometry.id, styleId: 'active', position: geometry.position, properties: geometry.properties } ]) }) this.map.on('click', () => { this.infoWindow.close() }) }

map.on('click')用来关窗口，这是必须的，不然后台系统里信息窗口会一直挂着。注意updateGeometries是按 id 局部更新的接口，比setGeometries全量重置更省事，尤其是点位多的时候。

内容里直接拼 HTML 是可以的，但要警惕 XSS：所有来自后端的文本字段，拼进content之前必须转义。我见过因为门店名里带了个尖括号导致弹窗样式整个错乱的案例。

5.2 定位点总是偏几百米，问题出在坐标系

这是我认为最容易被忽略、但后果最严重的一个技术点。

世界上主流的坐标系有三套：

腾讯地图用的是GCJ-02。而浏览器通过navigator.geolocation拿到的是WGS-84。这两者之间差着几十米到几百米不等，直接拿过来用，定位点就会偏到隔壁街区去。

所以，只要你的数据来源是 GPS 原始坐标，就必须转换：

import coordtransform from 'coordtransform' // WGS-84 转 GCJ-02，用于把 GPS 定位结果落到腾讯地图上 function toTMapCoord(lngWgs, latWgs) { const [lng, lat] = coordtransform.wgs84togcj02(lngWgs, latWgs) return { lng, lat } }

坐标转换的数学原理是两套坐标系之间的偏移量拟合，纯前端库就能算，不需要请求服务端，性能上没有负担。腾讯位置服务的 WebService 也提供了坐标转换接口，如果你的坐标量大且允许走服务端，也可以用那个。

实践中还有两个具体建议。一是在数据层就把坐标系标准化，数据库里存统一的 GCJ-02，入库存之前转换好，别让前端到处做转换。二是在界面上留一个坐标系标识字段，不然半年后接手的人看到一批点偏了，根本不知道是数据问题还是代码问题。

反过来，如果用户在地图上点击选点，拿到的坐标本身就是 GCJ-02，可以直接存库、直接用于后续的地图渲染，不需要再转。区分清楚"数据从哪来"是这套逻辑的关键。

5.3 上千个点位时的聚合与可视化取舍

点位一多，直接堆MultiMarker就会出现两个问题：绘制卡顿、视觉上糊成一片看不出规律。

分档处理的经验是这样的：

几十个点，直接用MultiMarker，没有任何问题。

几百个点，可以开点聚合。腾讯地图 GL 提供了MarkerCluster，会根据缩放级别把相邻点合并成一个圆形的数量气泡，点击可下钻。这对门店分布这类场景非常实用。

上千个到几万个点，标记聚合也不够用了，要考虑改用热力图或者自定义可视化图层。热力图适合看密度分布，不适合看精确位置；如果是需要看精确位置的，用点图层直接渲染，反而比 DOM 形式的标记性能好得多。

// 点聚合的简化写法 this.cluster = new TMap.MarkerCluster({ map: this.map, minimumClusterSize: 2, geometries: points.map((p, i) => ({ id: String(i), styleId: 'default', position: new TMap.LatLng(p.lat, p.lng), properties: p })) })

还有一个隐藏的性能杀手：不要用DOMOverlay画几百个自定义 HTML 标记。DOM 覆盖物每个都会在页面上创建真实节点，几百个就是几百个 DOM，滚动和缩放都会卡。真要自定义内容，优先考虑Label或者用MarkerStyle直接指定图片，实在不行再考虑 canvas 自绘。

提示：点位数据从接口拿回来之后，如果要做聚合，记得先按视口范围过滤一遍再塞给地图，别把全国几万个点全量推给前端。这个优化在数据量大的项目里经常能带来数量级的性能提升。

6. 上线前的几道硬坎

本地跑通了，不代表上线没问题。地图这类第三方库有几个坑是只在生产环境、只在长时间运行、只在真实用户操作下才暴露出来的。

6.1 实例销毁与内存泄漏

单页应用最大的特点就是组件会反复创建和销毁。如果地图实例没被正确回收，你每次进出这个页面，就多留一份完整的地图对象在内存里——里面有 canvas、有事件监听、有定时器、有网络请求。进出十几次，页面就开始卡了。

销毁这一步必须做全：

beforeDestroy() { // 1. 解绑自己挂的 window 监听 window.removeEventListener('resize', this._onResize) // 2. 清掉定时器 clearTimeout(this.searchTimer) // 3. 关掉信息窗口，避免残留 DOM if (this.infoWindow) { this.infoWindow.close() this.infoWindow = null } // 4. 销毁覆盖物图层 if (this.markerLayer) { this.markerLayer.setMap(null) this.markerLayer = null } // 5. 销毁地图实例 if (this.map) { this.map.destroy() this.map = null } }

顺序上有个讲究：先摘图层，再销毁地图。直接 destroy 地图实例，有时候图层对象内部还持有对地图的引用，虽然大多数情况下引擎会处理，但显式置空更保险。另外要注意，事件用on注册的，理论上销毁实例时会被清理，但如果你用addEventListener往window或document上加过监听，那些必须你自己解绑。

排查泄漏有一个笨但有效的办法：打开浏览器开发者工具的内存面板，进出页面五六次，手动触发一次垃圾回收，然后看快照里TMap相关的对象数量是不是在递增。递增就说明有问题。

6.2 打包体积与按需加载

腾讯地图 GL 的脚本本体不小，如果你的项目是多页面的，把地图放在index.html里全局加载，等于所有用户都要下载一遍。更好的做法是路由级懒加载配动态脚本注入。

// router/index.js const MapPage = () => import('@/views/MapPage.vue')

配合前面写的loadTMap，脚本只会在真正进入地图页时才注入。更进一步，如果地图只在一个弹窗里用，也可以把注入时机推后到弹窗打开时，能再省一点首屏。

还有一点值得提：地图容器和父级样式里不要滥用transform和filter。这两类属性会创建新的层叠上下文，有时会干扰地图 canvas 的合成，表现为地图出现横向或纵向的细微偏移、拖拽时有拖影。我遇到过因为祖先元素上挂了个filter: blur(0)做动画，结果地图整体错位了一两个像素——这种问题排查起来非常费劲，所以布局上尽量保持地图容器的祖先链干净。

6.3 线上报错速查表与排查顺序

最后整理一份我实际用过的排查清单，出问题时按顺序过一遍，绝大多数情况能在五分钟内定位。

排错的原则是从外往里查：先确认网络请求有没有成功，再确认容器尺寸对不对，然后确认初始化时机，最后才怀疑业务代码。倒着查的人，往往会在自己的代码里翻半天，最后发现是 key 没配对。

我自己踩得最深的一次，是线上某个客户环境里地图始终不显示，本地、测试环境全都正常。查了两天，最后发现是客户的浏览器装了个插件，会在页面上注入一层样式覆盖，把地图容器的overflow改了。这种问题没有任何技术方案能提前规避，只能靠"从外往里查"的顺序，一步步把范围缩小。所以我后来养成一个习惯：任何和地图相关的线上问题，第一个动作都是打开控制台看网络请求和容器尺寸，而不是去看代码。

这套 vue 加 elementUI 加腾讯地图的组合，说到底难点不在 API 本身，API 文档写得很清楚。难的是让一个命令式的、有状态的、生命周期自管的地图对象，平稳地活在声明式的、响应式的、组件会反复生灭的前端框架里。把初始化时机、响应式隔离、销毁回收这三件事想明白，剩下的都是查文档的活。