Vue3 + 高德地图实战：如何用GLTFLoader在3D地图上加载自定义建筑模型（附完整代码）
最近在做一个智慧园区的项目，客户要求在三维地图上精准展示几栋新建的办公楼模型。一开始我尝试用传统的2D标注点，效果平平无奇，直到我把一个带玻璃幕墙和楼顶花园的glTF模型加载到地图上，那种沉浸式的空间感一下子就出来了。这让我意识到，三维模型加载不再是锦上添花，而是很多B端项目提升用户体验的刚需。
高德地图的JS API提供了原生的AMap.GltfLoader插件，配合Vue3的组合式API，能让我们以更现代、更模块化的方式集成三维可视化能力。但说实话，从模型格式转换、资源托管，到地图坐标校准、性能调优，每一步都有不少坑。这篇文章，我就结合自己踩过的坑，把从零开始在高德3D地图上加载自定义建筑模型的完整流程和核心技巧梳理出来，希望能帮你省下不少折腾的时间。
1. 环境准备与项目初始化
在开始写代码之前，我们需要先把开发环境搭建好。一个清晰的项目结构能让你后续的开发事半功倍，尤其是在处理三维模型这种资源密集型应用时。
1.1 创建Vue3项目并集成高德地图
我习惯用Vite来创建Vue3项目，它的启动速度和热更新体验要好得多。打开终端，执行以下命令：
npm create vue@latest vue3-amap-3d
cd vue3-amap-3d
npm install
项目创建好后，我们需要安装高德地图的JavaScript API。这里有个关键点：高德地图的3D功能需要特定的版本支持。根据我的经验，v1.4.15及以上版本对AMap.GltfLoader和AMap.Object3DLayer的支持最稳定。我们通过CDN方式引入，这样能确保API的完整性和版本一致性。
在你的index.html文件的<head>部分添加高德地图的JS SDK引用：
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Vue3 高德3D地图</title>
<!-- 引入高德地图JS API，注意key需要替换为你自己的 -->
<script src="/https://webapi.amap.com/maps?v=1.4.15&key=你的高德应用Key&plugin=Map3D"></script>
</head>
<body>
<div id="app"></div>
<script type="module" src="/src/main.js"></script>
</body>
</html>
注意：
plugin=Map3D这个参数至关重要，它告诉高德SDK加载3D地图和相关的三维图层能力。没有它，Object3DLayer和GltfLoader是无法使用的。
1.2 模型格式转换：从OBJ到GLTF/GLB
大部分设计师给过来的建筑模型都是.obj格式，但高德地图的GltfLoader原生支持的是.gltf或.glb格式。glTF（GL Transmission Format）是Khronos Group制定的开放标准，专为高效传输和加载3D场景而设计，可以理解为“3D界的JPEG”。
转换工具我推荐使用obj2gltf，这是Cesium团队维护的一个命令行工具，转换质量和兼容性都很好。首先确保你的系统安装了Node.js，然后全局安装这个工具：
npm install -g obj2gltf
假设你有一个名为building.obj的模型文件，以及对应的材质文件building.mtl和一堆纹理贴图（.jpg或.png）。你需要把它们放在同一个目录下，然后在这个目录打开终端，执行转换命令：
obj2gltf -i building.obj -o building.glb --compressTextures
这里有几个参数需要解释一下：
-i: 指定输入的OBJ文件。-o: 指定输出的glTF文件。使用.glb扩展名会生成一个二进制格式的glTF文件，它将模型、材质、纹理甚至动画都打包进一个文件，管理起来更方便。--compressTextures: 这个参数会尝试压缩纹理图片，能显著减小最终文件体积。对于网络加载来说，体积就是性能。
转换完成后，我强烈建议你用在线预览工具检查一下模型。glTF Viewer（https://gltf-viewer.donmccurdy.com/）是个不错的选择，拖拽生成的.glb文件进去，看看模型是否完整、纹理有没有丢失、方向是否正确。这一步能提前发现很多问题，避免把有问题的模型上传到服务器。
1.3 模型资源托管与路径管理
转换好的模型文件需要放在一个可以通过URL访问的位置。对于生产环境，自然是上传到CDN或对象存储（如阿里云OSS、腾讯云COS）。在开发阶段，我们可以利用Vite的静态资源服务。
在Vue3 + Vite项目中，你可以把模型文件放在public/models/目录下。这样，在开发服务器和生产构建后，都可以通过相对路径/models/building.glb来访问。但要注意，如果模型文件很大（比如超过10MB），可能会影响本地开发服务器的启动速度。
一个更专业的做法是，在开发阶段使用一个本地静态文件服务器来专门托管模型资源，比如用http-server：
# 在模型文件所在目录运行
npx http-server -p 8081 --cors
然后在代码中通过http://localhost:8081/building.glb来加载。这样既不影响Vite开发服务器，也模拟了生产环境从远程加载的场景。
2. 核心代码实现：Vue3组合式API封装
环境准备好后，我们来编写核心的地图与模型加载逻辑。Vue3的组合式API让我们能把相关的功能逻辑抽离成可复用的函数，代码结构会清晰很多。
2.1 创建可复用的3D地图Hook
我习惯把高德地图的初始化、图层管理和模型加载逻辑封装成一个自定义的Composition API函数，我称之为useAmap3D。在src/composables/目录下创建useAmap3D.js文件：
import { ref, onMounted, onUnmounted } from 'vue'
export function useAmap3D(containerId, options = {}) {
const mapInstance = ref(null)
const object3DLayer = ref(null)
const gltfLoader = ref(null)
const loadedModels = ref(new Map()) // 用于存储已加载的模型实例
// 默认的3D地图配置
const defaultOptions = {
viewMode: '3D',
zoom: 17,
pitch: 45, // 俯仰角，让视角有点倾斜，3D感更强
rotation: 0,
center: [116.397428, 39.90923], // 默认北京天安门
showBuildingBlock: true, // 显示默认的3D楼块
mapStyle: 'amap://styles/light', // 使用浅色主题，模型更突出
showIndoorMap: false,
...options
}
// 初始化地图
const initMap = () => {
return new Promise((resolve, reject) => {
// 确保高德地图JS API已加载
if (!window.AMap) {
reject(new Error('高德地图JS API未加载，请检查script标签'))
return
}
try {
mapInstance.value = new AMap.Map(containerId, defaultOptions)
// 创建3D对象图层
object3DLayer.value = new AMap.Object3DLayer()
mapInstance.value.add(object3DLayer.value)
// 异步加载GltfLoader插件
mapInstance.value.plugin(["AMap.GltfLoader"], () => {
gltfLoader.value = new AMap.GltfLoader()
console.log('3D地图及GLTF加载器初始化完成')
resolve(mapInstance.value)
})
} catch (error) {
reject(error)
}
})
}
// 加载单个GLTF/GLB模型
const loadModel = (modelUrl, position, modelOptions = {}) => {
return new Promise((resolve, reject) => {
if (!gltfLoader.value) {
reject(new Error('GLTF加载器未初始化'))
return
}
const defaultModelOpts = {
scale: 1,
height: 0,
scene: 0,
...modelOptions
}
gltfLoader.value.load(modelUrl, (gltfObject) => {
if (!gltfObject) {
reject(new Error('模型加载失败，返回对象为空'))
return
}
// 设置模型位置和属性
gltfObject.setOption({
position: new AMap.LngLat(position[0], position[1]),
...defaultModelOpts
})
// 添加到3D图层
object3DLayer.value.add(gltfObject)
// 存储模型引用，便于后续操作
const modelId = `model_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`
loadedModels.value.set(modelId, {
instance: gltfObject,
url: modelUrl,
position,
options: defaultModelOpts
})
resolve({ id: modelId, instance: gltfObject })
}, (error) => {
reject(new Error(`加载模型失败: ${error.message}`))
})
})
}
// 更新模型位置
const updateModelPosition = (modelId, newLngLat) => {
const modelData = loadedModels.value.get(modelId)
if (modelData && modelData.instance) {
modelData.instance.setOption({
position: new AMap.LngLat(newLngLat[0], newLngLat[1])
})
modelData.position = newLngLat
return true
}
return false
}
// 移除模型
const removeModel = (modelId) => {
const modelData = loadedModels.value.get(modelId)
if (modelData && modelData.instance) {
object3DLayer.value.remove(modelData.instance)
loadedModels.value.delete(modelId)
return true
}
return false
}
// 清理资源
const destroy = () => {
if (mapInstance.value) {
// 移除所有模型
loadedModels.value.forEach((model) => {
object3DLayer.value.remove(model.instance)
})
loadedModels.value.clear()
// 移除图层并销毁地图
mapInstance.value.remove(object3DLayer.value)
mapInstance.value.destroy()
mapInstance.value = null
}
}
// 生命周期钩子中自动初始化和清理
onMounted(() => {
initMap().catch(console.error)
})
onUnmounted(() => {
destroy()
})
return {
mapInstance,
object3DLayer,
loadedModels,
initMap,
loadModel,
updateModelPosition,
removeModel,
destroy
}
}
这个Hook封装了地图初始化、模型加载、更新和销毁的全生命周期管理。使用Promise包装异步操作，让调用方可以用async/await更优雅地处理加载状态。
2.2 构建模型加载组件
有了Hook，我们就可以创建一个专门用于显示3D地图和模型的Vue组件。在src/components/目录下创建AmapModelViewer.vue：
<template>
<div class="model-viewer-container">
<!-- 地图容器 -->
<div ref="mapContainer" class="map-container"></div>
<!-- 控制面板 -->
<div v-if="showControls" class="control-panel">
<div class="control-group">
<h4>模型控制</h4>
<div class="model-list">
<div
v-for="model in modelList"
:key="model.id"
扫一扫
1585
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
