Vue 3 + Mapbox GL JS：自定义三维地图模板的封装实践

如果你手头的项目需要上一张三维地图，你大概能体会那种感觉：说简单也简单，说麻烦是真麻烦。我在给某园区项目管理平台做可视化大屏时，需求是“楼宇数据要能立体展示、地形起伏要看得出来、鼠标点上去要有详情”，而且留给我折腾地图的时间只有两天。最后沉淀下来的方案就是这篇文章的标题：vue通过npm安装js实现mapbox自定义3D模板。简单说，就是用 Vue 3 做基础框架，通过 npm 安装 mapbox-gl 这个 JavaScript 库，把地图初始化、3D 地形、建筑挤出、控件交互全部封装成一个可复用的 Vue 组件，换数据、换坐标就能直接用。

文章适合两类人：一类是想在 Vue 项目里快速跑起三维地图的开发者，另一类是已经能显示地图但想搞清楚 3D 效果原理的人。我会把踩过的坑、参数为什么这么调、组件怎么封装才不泄漏内存都写清楚，照着做基本半天内能出一个能用的 3D 地图模板。

1. 项目背景与整体思路拆解

1.1 为什么要把3D地图做成模板

做可视化项目的朋友应该有体会：客户报需求的时候很少只说“给我一张地图”，通常是既要显示区域轮廓，又要点开楼宇看到属性信息，还要能拉高视角看地形和建筑的层次关系。这种需求如果每次从零开始搭，光调样式、配图层、试坐标就能耗掉大半天，更别提 3D 地形、建筑挤出这些特性光是参数就能让人调到头秃。

我这次遇到的情况是，项目里要展示园区十几栋楼宇的空间位置和楼层数据，后续还要接入实时设备状态。如果我把地图逻辑散落在页面组件里，数据一变或者换一个项目，整个页面都要动，复用率极低。所以我决定把地图相关的部分全部抽离，做成一个模板组件：初始化逻辑、3D 场景、交互事件都在组件内部处理，对外只暴露配置项和事件回调。这样当前项目能用，下个项目改个坐标和数据源也能直接用，省下来的时间非常可观。

1.2 技术选型：为什么是Vue加Mapbox GL JS

三维地图的技术方案不少，但适合 Vue 项目快速迭代的组合其实不多。我简单对比过几个常见选项：

• Cesium：功能很强，适合全球级、大场景、时间轴动画这类需求，但对普通业务项目来说偏重，学习成本也高，团队如果没有专门的地理信息背景，上手会吃力。
• Three.js：3D 渲染能力没得说，但地图数据对接、矢量瓦片、坐标系这些东西都要自己处理，从零搭一套能用的体系周期太长。
• Leaflet：生态成熟，2D 场景很顺手，但 3D 支持比较弱，做建筑挤出和地形起伏基本要靠插件，效果和稳定性都打折扣。
• Mapbox GL JS：基于 WebGL 渲染，原生支持矢量瓦片、3D 地形（raster-dem）、建筑挤出（fill-extrusion），API 设计得也比较清楚，文档和示例丰富，配合 Vue 的组件化模式很顺手。

Vue 这边的理由也很直观：组件生命周期和地图的生命周期天然契合。组件挂载完成时创建地图实例，组件卸载时销毁地图实例，响应式数据还可以直接驱动视角切换和图层显隐。用 npm 安装 mapbox-gl，依赖版本由 package.json 管理，团队成员拉下代码执行一次 npm install 就能跑，不必手动下载 JS 文件或者担心版本冲突。

1.3 模板设计的三个核心思路

动手写代码之前，我先定了三个原则，后面所有实现都围绕它们展开：

一是配置化。中心坐标、缩放级别、倾斜角度、地图样式、数据源地址这些全部作为组件参数传入，不在组件内部写死。这样同一个模板放到不同项目里，只需要改参数，不需要改组件代码。

二是事件化。地图内部的点击、加载完成、视角变化等事件，通过 Vue 的 emit 机制抛给使用方。上层业务只需要监听事件，不需要接触地图实例的细节，组件之间的耦合度降到最低。

三是生命周期托管。组件挂载时初始化地图，卸载时彻底销毁地图实例并解绑事件，避免内存泄漏和重复初始化。这三点听起来简单，但实际踩坑的时候会发现，每一点都有很多细节要处理。

2. 环境准备与基础工程搭建

2.1 创建Vue项目并安装mapbox依赖

我这次用的是 Vite 方式创建 Vue 3 项目，命令很直接：

npm create vite@latest my-3d-map -- --template vue cd my-3d-map npm install npm install mapbox-gl

安装完成之后，建议执行一下npm list mapbox-gl确认版本号。我项目里当时装的是 v3 系列，和 Vue 3 配合没什么问题。如果你用的是 Vue 2，也不是不能用，只是组件写法要改成 Options API 或者用 Vue 2 的响应式方式，整体思路是一样的。

这里有一个容易被忽略的点：Mapbox GL JS 的版本迭代比较快，v2 之后有部分 API 做了调整，比如样式 URL 的写法、部分图层属性的默认值。安装时尽量使用最新的稳定版本，不要图方便去复制网上旧文章的固定版本号，否则容易遇到 API 对不上的问题。npm 安装时默认会加^前缀，如果想锁死版本，可以去掉前缀再安装，保证团队环境一致。

2.2 配置access token与环境变量

使用 Mapbox 需要申请一个 access token，这个 token 相当于调用地图服务的钥匙，必须妥善管理。我的习惯是不把 token 直接写死在代码里，而是放到环境变量文件中，让不同环境使用不同配置。

项目根目录创建.env.development和.env.production，内容类似：

VITE_MAPBOX_TOKEN=你的开发环境token

在组件里通过import.meta.env.VITE_MAPBOX_TOKEN读取。Vite 项目用import.meta.env，Vue CLI 项目则用process.env.VUE_APP_MAPBOX_TOKEN，两者环境变量前缀有差异，别搞混。

.token 放在环境变量里还有一个好处：代码提交到代码仓库时可以把真实 token 忽略掉，只保留.env.example作为模板，新同事拿到项目后自己填入 token，避免密钥泄露。我用这种方案以后，再没出现过 token 被不小心提交到远端仓库的情况。

2.3 项目目录结构与基础组件骨架

为了让模板清晰可维护，目录我这样安排：

src/ components/ MapTemplate.vue views/ HomeView.vue styles/ map.css

MapTemplate.vue负责封装所有地图逻辑，HomeView.vue负责业务数据和布局。组件的基础骨架先搭出来，内部先不做完整 3D 逻辑，只做一个能正常初始化的地图容器：

<template> <div ref="mapContainer" class="map-container"></div> </template> <script setup> import { ref, onMounted } from 'vue'; import mapboxgl from 'mapbox-gl'; const mapContainer = ref(null); onMounted(() => { mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_TOKEN; const map = new mapboxgl.Map({ container: mapContainer.value, style: 'mapbox://styles/mapbox/dark-v11', center: [105, 35], zoom: 10 }); }); </script> <style scoped> .map-container { width: 100%; height: 100%; } </style>

这时候页面里能出现一张 2D 地图，就说明环境配置成功了。注意容器必须要有明确的高度，否则地图会渲染成一片空白，这个问题我在后面常见问题章节还会展开说。

3. 自定义3D模板核心功能实现

3.1 地图初始化与3D视角配置

二维地图只能看到俯视平面，要做 3D 效果，关键在视角参数。Mapbox GL JS 的Map构造参数里有几个和 3D 直接相关的选项：pitch是俯仰角，取值范围 0 到 60 左右，角度越大，地图倾斜越明显，建筑侧面和地形起伏才看得出来；bearing是方位角，控制地图绕中心点旋转，配合 pitch 使用才能从不同角度欣赏立体效果。

我实际配置的视角参数是这样：

const map = new mapboxgl.Map({ container: mapContainer.value, style: 'mapbox://styles/mapbox/dark-v11', center: [105, 35], zoom: 13, pitch: 60, bearing: -30 });

样式方面，我常用dark-v11做深色底图，适合可视化大屏；如果是业务系统偏明亮风格，可以用light-v11或者streets-v12。样式 URL 也可以换成自定义样式，后续如果要统一品牌色，可以在地图平台上做样式定制，然后把样式 ID 传进来。

这里有个细节值得注意：pitch和bearing不仅可以在初始化时设置，也可以在运行中通过map.easeTo或者map.flyTo动态切换。我经常在模板里做一个“切换视角”的功能，让地图在 2D 俯视和 3D 倾斜之间平滑过渡，客户演示的时候效果非常直观。代码很简单：

map.flyTo({ center: [105, 35], zoom: 14, pitch: 60, bearing: 30, duration: 2000 });

3.2 三维地形与建筑挤出效果

视角倾斜只是让地图“看起来是斜的”，真正的立体感来自两个能力：地形起伏和建筑挤出。

地形起伏的做法是添加一个 raster-dem 数据源，然后调用setTerrain告诉地图引擎使用这个数据源来生成高程：

map.on('load', () => { map.addSource('dem-source', { type: 'raster-dem', url: 'mapbox://mapbox.terrain-rgb', tileSize: 256, maxzoom: 14 }); map.setTerrain({ source: 'dem-source', exaggeration: 1.2 }); });

这里的exaggeration参数是地形夸张系数，默认 1 表示真实比例，大于 1 会放大地形起伏。做山地、丘陵区域的可视化时，我一般设成 1.2 到 1.5，看起来既有立体感又不会失真；如果是平原城市，设 1 就够了。注意地形数据的maxzoom要配好，不然缩放级别超过数据精度后看不到效果。

建筑挤出用的是fill-extrusion图层。如果我们使用 Mapbox 自带的基础样式，里面通常已经包含建筑图层数据，可以直接在样式的建筑图层上叠加 3D 效果：

map.addLayer({ id: '3d-buildings', source: 'composite', 'source-layer': 'building', type: 'fill-extrusion', minzoom: 15, filter: ['==', 'extrude', 'true'], paint: { 'fill-extrusion-color': '#888888', 'fill-extrusion-height': ['coalesce', ['get', 'height'], 0], 'fill-extrusion-base': ['coalesce', ['get', 'min_height'], 0], 'fill-extrusion-opacity': 0.8 } });

这段代码里的height和min_height是建筑数据里的楼层高度字段，coalesce表示如果字段不存在则使用默认值 0。透明度我设成 0.8，这样建筑底部能透出一点底图，整体层次感更好。如果你的项目使用的是自定义数据而非 Mapbox 内置底图，则需要通过addSource添加 GeoJSON 数据源，再基于它创建 fill-extrusion 图层，思路是一样的，只是数据源类型要改成geojson。

3.3 自定义控件与交互设计

地图能用之后，交互控件是必须要做的。Mapbox GL JS 提供了一组标准控件，直接 addControl 就能用：

map.addControl(new mapboxgl.NavigationControl(), 'top-right'); map.addControl(new mapboxgl.ScaleControl(), 'bottom-left'); map.addControl(new mapboxgl.FullscreenControl(), 'top-right');

NavigationControl 是缩放和旋转按钮，ScaleControl 是比例尺，FullscreenControl 是全屏切换。这些控件在不同项目里几乎都有需求，直接封装进模板，上层不需要关心。

业务交互方面，最常见的是点击地图获取信息。在 3D 场景下，点击获取的经纬度是鼠标射线和地形或建筑的交点，需要用queryRenderedFeatures来查询当前点击位置有哪些图层数据：

map.on('click', (e) => { const features = map.queryRenderedFeatures(e.point, { layers: ['3d-buildings'] }); if (features.length > 0) { // 拿到建筑属性，交给上层去展示 emit('building-click', features[0].properties); } });

这里有个容易踩的坑：默认地图光标在 3D 建筑上不会变成小手，用户不知道能不能点。所以我还加了一行map.on('mousemove')去判断当前指针是否悬停在建筑图层上，是就切换 cursor 样式，不是就恢复默认。这个交互细节虽然小，但实际体验提升很明显。

3.4 封装为Vue组件的完整实现

把前面这些逻辑全部收拢到一个组件里，就是模板的最终形态。我用的组合式 API 写法，关键点是 props 接收配置、emit 抛出事件、onMounted初始化、onUnmounted销毁：

<template> <div ref="mapContainer" class="map-container"></div> </template> <script setup> import { ref, onMounted, onUnmounted } from 'vue'; import mapboxgl from 'mapbox-gl'; const props = defineProps({ accessToken: { type: String, required: true }, center: { type: Array, default: () => [105, 35] }, zoom: { type: Number, default: 12 }, pitch: { type: Number, default: 60 }, bearing: { type: Number, default: -30 }, style: { type: String, default: 'mapbox://styles/mapbox/dark-v11' } }); const emit = defineEmits(['map-ready', 'building-click']); const mapContainer = ref(null); let map = null; onMounted(() => { mapboxgl.accessToken = props.accessToken; map = new mapboxgl.Map({ container: mapContainer.value, style: props.style, center: props.center, zoom: props.zoom, pitch: props.pitch, bearing: props.bearing }); map.on('load', () => { initTerrain(); initBuildings(); initControls(); emit('map-ready', map); }); map.on('click', (e) => { const features = map.queryRenderedFeatures(e.point, { layers: ['3d-buildings'] }); if (features.length > 0) { emit('building-click', features[0].properties); } }); }); function initTerrain() { map.addSource('dem-source', { type: 'raster-dem', url: 'mapbox://mapbox.terrain-rgb', tileSize: 256, maxzoom: 14 }); map.setTerrain({ source: 'dem-source', exaggeration: 1.2 }); } function initBuildings() { map.addLayer({ id: '3d-buildings', source: 'composite', 'source-layer': 'building', type: 'fill-extrusion', minzoom: 15, filter: ['==', 'extrude', 'true'], paint: { 'fill-extrusion-color': '#888888', 'fill-extrusion-height': ['coalesce', ['get', 'height'], 0], 'fill-extrusion-base': ['coalesce', ['get', 'min_height'], 0], 'fill-extrusion-opacity': 0.8 } }); } function initControls() { map.addControl(new mapboxgl.NavigationControl(), 'top-right'); map.addControl(new mapboxgl.ScaleControl(), 'bottom-left'); map.addControl(new mapboxgl.FullscreenControl(), 'top-right'); } onUnmounted(() => { if (map) { map.remove(); map = null; } }); </script> <style scoped> .map-container { width: 100%; height: 100%; } </style>

使用方只需要这样调用：

<MapTemplate :access-token="token" :center="[105, 35]" :zoom="13" @map-ready="handleMapReady" @building-click="handleBuildingClick" />

组件化之后，业务代码和地图代码彻底分离。我在好几个项目里复用这个模板，每次只改坐标、样式和数据回调，地图逻辑基本不动。组件销毁时调用map.remove()会释放 WebGL 上下文和相关资源，这是避免内存泄漏的关键一步，千万别省。

4. 项目部署与性能优化实践

4.1 构建配置与包体控制

Mapbox GL JS 本身是一个比较大的库，如果项目只有一两个页面用到地图，把所有页面都一次性加载显然不划算。我的做法是使用 Vue 的异步组件，让地图组件在进入相关路由时才加载：

const MapTemplate = defineAsyncComponent(() => import('@/components/MapTemplate.vue') );

这样地图相关的 JS 会被单独拆成一个 chunk，首屏不加载，只有用户打开地图页面时才下载。实测在我的项目里，首屏包体直接少了 300 多 KB，效果很显著。

此外，Vite 打包默认会生成 sourcemap，这种文件在浏览器控制台调试时有用，但部署到生产环境既拖慢上传速度，又可能暴露源码结构，建议在生产构建时关闭。在vite.config.js里这样配置：

export default defineConfig({ build: { sourcemap: false, chunkSizeWarningLimit: 1500 } });

chunkSizeWarningLimit是调整 chunk 大小警告阈值的，mapbox 类库单独打包后容易超过默认 500KB 的警告线，适当调大可以避免构建日志里出现一堆干扰性的警告。这只是调整参考数值，不影响实际打包结果。

4.2 图层与数据性能优化

3D 地图对性能的要求比 2D 高一个档次，尤其是建筑挤出的 fill-extrusion 图层，每个建筑都是一个三维几何体，数据量大时帧率会明显下降。我踩过几次坑之后总结了几条实用经验：

一是控制数据精度。使用自定义 GeoJSON 时，尽量删除不需要的字段，尤其是大段的字符串属性，会拖慢序列化和渲染。建筑轮廓的顶点数量也要控制，过于精细的边界在常规缩放级别下根本看不出来，数据量却成倍增加。

二是合理设置图层可见级别。fill-extrusion 图层可以设置minzoom，比如我设置的 15，意思是最小显示级别是 15 级，比这更小的缩放级别下不渲染建筑，节省大量 GPU 开销。像地形数据也有maxzoom上限，级别超过数据精度后不再加载更细的瓦片。

三是及时清理不需要的资源。切换页面或者更新数据时，用map.removeLayer()和map.removeSource()把旧图层和旧数据源移除，否则地图引擎会一直保留这些渲染资源。我在模板里加了一个更新数据的方法，每次先移除旧的源再重新添加，实测内存占用稳定，不会随着操作次数增加而上涨。

四是大批量点数据建议开启聚合。Mapbox 支持对 GeoJSON 数据源设置cluster: true，当缩放级别较小、点数量很多时，地图会自动聚合为带数量的圆点，既清晰又流畅。

4.3 常见问题与排查技巧

做这个模板的过程中，我遇到的问题不少，整理成一张速查表供参考：

其中我想特别展开说一下 Worker 相关的问题。Mapbox GL JS 内部使用 Web Worker 处理大量计算，在部分构建配置下，浏览器无法自动定位到正确的 Worker 文件，会出现运行时报错，控制台提示一大串 Worker 相关的内容，地图直接初始化失败。我遇到时用的解决方法是：

import mapboxgl from 'mapbox-gl'; import mapboxglWorker from 'mapbox-gl/dist/mapbox-gl-worker'; mapboxgl.workerClass = mapboxglWorker;

这段配置要放在创建地图实例之前。不同版本解法略有差异，但思路都是告诉库应该加载哪个 Worker 文件。如果看到地图网络请求里出现了 404 的 worker 请求，基本就能确定是这个原因。

还有一个很容易被忽视的问题：初始化地图时如果容器尺寸在创建那一刻是 0，地图内部的计算就会出错，等容器变大后地图也可能不会自动重绘。解决办法是在容器尺寸发生变化后调用map.resize()。我在模板里用 ResizeObserver 监听容器大小变化，自动触发 resize，这样页面里切换侧边栏、弹窗全屏之类的操作都不会导致地图显示异常。

写在最后的一个小经验

这个模板做完之后，我最大的体会是：不要把希望寄托在“一次写对”，地图这类带渲染引擎的东西，问题往往是环境相关的。第一次跑起来看到空白页不要慌，按着控制台报错一件件查，先确认容器尺寸，再查 token，再看图层类型，比自己瞎试快得多。另外，一开始最好用一个固定的、数据量小的测试坐标，等所有功能都跑通了再换成真实业务数据，否则数据和地图代码混在一起出问题，排查起来非常痛苦。

后续如果要扩展，可以考虑把图层配置也做成 JSON 描述，通过配置数组动态生成图层，这样不需要改组件代码就能在上层自由组合多个数据源。我现在已经在往这个方向演进，模板的通用性又上了一个台阶。希望这篇文章能帮你少踩几个坑，做出自己的三维地图模板。