Vue集成Cesium 3D地图开发实战指南

jiyulishang

1. Cesium 地图初始化与 Vue 集成实战

作为一个长期从事地理信息系统开发的工程师，我经常需要在 Web 项目中集成 3D 地图功能。Cesium 作为目前最强大的开源 3D 地球可视化库，虽然功能强大但入门门槛较高。今天我将分享在 Vue 项目中集成 Cesium 的完整方案，特别针对无 Token 的本地开发环境进行了优化。

这个方案的核心优势在于：

完全摆脱对 Cesium Ion Token 的依赖
使用高德地图作为默认底图（国内访问稳定）
精简所有非必要 UI 控件
提供可直接复用的 Vue 组件模板
包含完整的相机控制工具集

2. 环境准备与基础配置

2.1 项目初始化与依赖安装

首先创建一个标准的 Vue 3 项目（这里以 Vite 为例）：

bash复制npm create vite@latest cesium-demo --template vue
cd cesium-demo

然后安装 Cesium 核心库：

bash复制npm install cesium

注意：Cesium 的 npm 包体积较大（约 50MB），安装可能需要较长时间。如果遇到网络问题，可以考虑使用国内镜像源。

2.2 资源文件配置

Cesium 需要一些静态资源文件才能正常运行，我们需要将这些文件复制到项目的 public 目录：

找到 node_modules/cesium/Build/Cesium 目录
将整个 Cesium 文件夹复制到项目的 public 目录下

目录结构应该如下所示：

code复制public/
  └── Cesium/
      ├── Assets/
      ├── ThirdParty/
      ├── Widgets/
      ├── Cesium.js
      └── ...

2.3 HTML 文件引入

在 public/index.html 的 <head> 部分添加以下代码：

html复制<link href="/Cesium/Widgets/widgets.css" rel="stylesheet">
<script src="/Cesium/Cesium.js"></script>

关键点：必须在 Vue 挂载的 DOM 元素之前加载 Cesium.js，否则会报初始化错误。

3. Vue 组件实现

3.1 基础地图组件

创建一个 MapView.vue 组件，包含以下核心功能：

vue复制<template>
  <div class="map-page">
    <div ref="mapContainerRef" class="map-container"></div>
  </div>
</template>

<script>
export default {
  name: 'MapView',
  data() {
    return {
      viewer: null
    }
  },
  mounted() {
    this.initMap()
  },
  methods: {
    initMap() {
      const Cesium = window.Cesium
      if (!Cesium) {
        console.error('Cesium 未正确加载')
        return
      }

      // 配置高德地图瓦片服务（无需 Token）
      const imageryProvider = new Cesium.UrlTemplateImageryProvider({
        url: "https://webst0{s}.is.autonavi.com/appmaptile?style=6&x={x}&y={y}&z={z}",
        subdomains: ["1", "2", "3", "4"],
        minimumLevel: 3,
        maximumLevel: 18,
      })

      // 初始化 Viewer
      this.viewer = new Cesium.Viewer(this.$refs.mapContainerRef, {
        animation: false,
        timeline: false,
        baseLayerPicker: false,
        geocoder: false,
        homeButton: false,
        sceneModePicker: false,
        navigationHelpButton: false,
        fullscreenButton: false,
        infoBox: false,
        selectionIndicator: false,
        vrButton: false,
        projectionPicker: false,
        shouldAnimate: false,
        terrainProvider: new Cesium.EllipsoidTerrainProvider(),
        imageryProvider: false
      })

      // 手动添加高德地图图层
      this.viewer.imageryLayers.removeAll()
      this.viewer.imageryLayers.addImageryProvider(imageryProvider)

      // 移除版权信息（开发环境）
      this.viewer._cesiumWidget._creditContainer.style.display = "none"
    }
  },
  beforeUnmount() {
    if (this.viewer) {
      this.viewer.destroy()
      this.viewer = null
    }
  }
}
</script>

<style scoped>
.map-page {
  position: relative;
  width: 100vw;
  height: 100vh;
}

.map-container {
  width: 100%;
  height: 100%;
}
</style>

3.2 关键配置解析

高德地图瓦片配置：
- subdomains: 使用多个子域名分摊请求，避免并发限制
- minimumLevel: 设置最小缩放级别（3级对应全国视图）
- maximumLevel: 设置最大缩放级别（18级对应街道细节）
Viewer 初始化选项：
- 禁用所有 UI 控件以获得干净视图
- terrainProvider: 使用默认椭球地形（无需网络请求）
- imageryProvider: false: 阻止 Cesium 自动加载默认底图
性能优化：
- 组件销毁时调用 viewer.destroy() 释放资源
- 移除版权信息减少 DOM 节点（仅限开发环境）

4. 地图控制工具集

4.1 核心工具函数

创建 map.js 工具文件，实现以下功能：

javascript复制// 定位到指定坐标
export const locate = (viewer, options = {}) => {
  const {
    lon,
    lat,
    height = 2000000,
    heading = 0,
    pitch = -90,
    duration = 1.2,
    flyTo = true
  } = options
  
  const destination = Cesium.Cartesian3.fromDegrees(lon, lat, height)
  const orientation = {
    heading: Cesium.Math.toRadians(heading),
    pitch: Cesium.Math.toRadians(pitch)
  }

  if (flyTo) {
    viewer.camera.flyTo({ destination, orientation, duration })
  } else {
    viewer.camera.setView({ destination, orientation })
  }
}

// 场景模式切换
export const switchSceneMode = (viewer, mode, duration = 0.8) => {
  const normalizedMode = String(mode || "").toUpperCase()
  
  if (normalizedMode === "2D") {
    viewer.scene.morphTo2D(duration)
  } else if (normalizedMode === "3D") {
    viewer.scene.morphTo3D(duration)
  } else {
    viewer.scene.morphToColumbusView(duration)
  }
}

// 获取相机状态
export const getCameraState = (viewer) => {
  const cartographic = viewer.camera.positionCartographic
  return {
    height: cartographic.height,
    heading: Cesium.Math.toDegrees(viewer.camera.heading),
    pitch: Cesium.Math.toDegrees(viewer.camera.pitch),
    lon: Cesium.Math.toDegrees(cartographic.longitude),
    lat: Cesium.Math.toDegrees(cartographic.latitude)
  }
}

4.2 Vue 工具组件

创建 MapTools.vue 组件提供 UI 控制界面：

vue复制<template>
  <div class="map-tools">
    <el-card shadow="always">
      <el-button-group>
        <el-button @click="onLocate">定位到北京</el-button>
        <el-button @click="onZoomIn">放大</el-button>
        <el-button @click="onZoomOut">缩小</el-button>
      </el-button-group>
      
      <el-button-group style="margin-left: 10px">
        <el-button @click="on2D">2D</el-button>
        <el-button @click="on3D">3D</el-button>
      </el-button-group>
      
      <el-descriptions :column="1" border>
        <el-descriptions-item label="经度">{{ cameraState?.lon.toFixed(6) }}</el-descriptions-item>
        <el-descriptions-item label="纬度">{{ cameraState?.lat.toFixed(6) }}</el-descriptions-item>
        <el-descriptions-item label="高度">{{ cameraState?.height.toFixed(2) }}米</el-descriptions-item>
      </el-descriptions>
    </el-card>
  </div>
</template>

<script>
import { locate, getCameraState, switchSceneMode } from './map'

export default {
  props: ['viewer'],
  data() {
    return {
      cameraState: null
    }
  },
  methods: {
    onLocate() {
      locate(this.viewer, { lon: 116.4074, lat: 39.9042 })
      this.refreshCameraState()
    },
    refreshCameraState() {
      this.cameraState = getCameraState(this.viewer)
    }
    // 其他方法...
  }
}
</script>

<style scoped>
.map-tools {
  position: absolute;
  top: 20px;
  left: 20px;
  z-index: 999;
}
</style>

5. 高级功能实现

5.1 点集区域飞行

在 map.js 中添加区域飞行功能：

javascript复制export const flyToPointsRegion = (viewer, points, options = {}) => {
  const cartesians = points.map(p => 
    Cesium.Cartesian3.fromDegrees(p.lon, p.lat, p.height || 0)
  )
  
  const boundingSphere = Cesium.BoundingSphere.fromPoints(cartesians)
  const range = boundingSphere.radius * (options.rangePaddingRatio || 1.2)
  
  viewer.camera.flyToBoundingSphere(boundingSphere, {
    duration: options.duration || 1.2,
    offset: new Cesium.HeadingPitchRange(
      Cesium.Math.toRadians(options.heading || 0),
      Cesium.Math.toRadians(options.pitch || -45),
      range
    )
  })
}

5.2 使用示例

javascript复制// 飞向北京五环区域
const beijingPoints = [
  { lon: 116.403963, lat: 39.915119 },
  { lon: 116.397026, lat: 39.908722 },
  { lon: 116.323171, lat: 39.983607 },
  { lon: 116.486409, lat: 39.921489 }
]

flyToPointsRegion(viewer, beijingPoints, {
  pitch: -30,
  duration: 2.5
})

6. 常见问题与解决方案

6.1 地图不显示问题排查

空白页面：
- 检查 Cesium 资源文件是否正确复制到 public 目录
- 确认控制台没有 404 错误（特别是 Cesium.js 和 widgets.css）
- 确保 Viewer 初始化时 DOM 元素已挂载
Token 相关错误：
- 如果看到 "This application is using Cesium's default ion access token" 警告
- 确认已设置 imageryProvider: false 避免自动加载 Bing 地图
跨域问题：
- 高德地图瓦片服务需要确保域名在允许列表
- 开发时可配置代理或使用浏览器扩展禁用 CORS

6.2 性能优化建议

按需加载：

javascript复制// 动态导入 Cesium 模块
const { Viewer } = await import('cesium')

地形数据优化：

javascript复制// 使用简单地形替代
viewer.terrainProvider = new Cesium.EllipsoidTerrainProvider()

内存管理：

javascript复制// 定期清理实体
viewer.entities.removeAll()

7. 项目结构与扩展建议

完整的项目结构建议：

code复制src/
  ├── components/
  │   ├── MapView.vue    # 主地图组件
  │   └── MapTools.vue   # 地图控制工具
  ├── utils/
  │   └── map.js         # 地图工具函数
  └── assets/
      └── styles/
          └── map.scss   # 地图相关样式