【Cesium 开发实战教程】第一篇：Vue3+Cesium 环境搭建与首个地球场景实现

一、专栏导语​

大家好，我是专注于三维 GIS 开发的工程师。本专栏「Cesium 开发实战教程」旨在从实战角度出发，带大家从零掌握 Cesium.js 核心能力 —— 从环境搭建到高级功能（如空间分析、模型加载、动态数据可视化），每篇文章都会配套可运行代码和关键知识点解析，适合前端工程师、GIS 相关从业者入门学习。​

本文作为开篇，将重点解决新手最易踩坑的「环境配置」问题，最终实现一个能正常渲染地球的基础 Cesium 应用。​

二、技术栈准备​

在开始前，请确保本地已安装以下工具：​

• Node.js（v14+，推荐 v16 LTS）：用于包管理和项目运行​

• 代码编辑器：VS Code（推荐安装 Volar 插件支持 Vue3）​

• 浏览器：Chrome/Firefox（Cesium 对现代浏览器兼容性更好）​

核心依赖版本说明：​

• Vue：3.3.x（Composition API + Script Setup 语法）​

• Vite：4.x（构建工具，比 Webpack 更快）​

• Cesium：1.110+（本文使用 1.114 版本）​

三、 step-by-step 环境搭建​

1. 创建 Vue3+Vite 项目​

打开终端，执行以下命令创建项目（项目名可自定义，此处用cesium-demo）：

# 创建Vite项目
npm create vite@latest cesium-demo -- --template vue

# 进入项目目录
cd cesium-demo

# 安装基础依赖
npm install

此时可先运行npm run dev测试基础 Vue 项目是否正常（访问终端输出的本地地址，能看到 Vue 默认页面即成功）。

2. 安装 Cesium 依赖​

Cesium 官方提供了 npm 包，直接安装即可：

# 安装Cesium核心包
npm install cesium@1.114 --save

关键注意点：Cesium 需要加载静态资源（如地形数据、Shader 文件等），Vite 环境下需手动配置资源路径。​

3. Vite 配置 Cesium 资源​

在项目根目录创建vite.config.js（若已存在则修改），添加 Cesium 资源解析配置：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import path from 'path'

export default defineConfig({
  plugins: [vue()],
  resolve: {
    // 配置Cesium别名，方便代码中引入
    alias: {
      '@': path.resolve(__dirname, 'src'),
      'cesium': path.resolve(__dirname, 'node_modules/cesium/Source')
    }
  },
  server: {
    // 解决开发环境跨域问题（后续加载在线地形/影像会用到）
    proxy: {
      '/api': {
        target: 'https://api.cesium.com',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, '')
      }
    }
  },
  define: {
    // 告诉Cesium使用WebGL2（性能更好）
    CESIUM_HTML5_PATH: JSON.stringify('cesium/Widgets/widgets.css'),
    USE_WEBGL2: true
  },
  css: {
    preprocessorOptions: {
      // 全局引入Cesium样式（可选，也可在组件内单独引入）
      css: {
        additionalData: `@import "cesium/Widgets/widgets.css";`
      }
    }
  }
})

四、实现第一个 Cesium 地球场景​

1. 创建 Cesium 容器组件​

在src/components目录下新建CesiumViewer.vue组件，使用 Script Setup 语法编写：

<template>
  <!-- Cesium地球容器：必须设置宽高，否则无法渲染 -->
  <div class="cesium-container" ref="cesiumContainer"></div>
</template>

<script setup>
import { ref, onMounted } from 'vue'
// 引入Cesium核心模块
import { Viewer, Cartesian3, Color } from 'cesium'
// 引入Cesium样式（若Vite全局配置已引入，可省略）
import 'cesium/Widgets/widgets.css'

// 容器DOM引用
const cesiumContainer = ref(null)
// 存储Cesium Viewer实例（方便后续操作）
let viewer = null

// 组件挂载后初始化Cesium（确保DOM已渲染）
onMounted(() => {
  if (!cesiumContainer.value) return

  // 1. 初始化Viewer
  viewer = new Viewer(cesiumContainer.value, {
    // 配置项：关闭不需要的默认控件
    timeline: false, // 时间轴
    animation: false, // 动画控制
    baseLayerPicker: true, // 底图切换控件
    geocoder: true, // 地址搜索控件
    homeButton: true, // 主页按钮（回到默认视角）
    sceneModePicker: true, // 场景模式切换（3D/2D/ Columbus View）
    navigationHelpButton: true, // 帮助按钮
    fullscreenButton: true // 全屏按钮
  })

  // 2. 基础配置：设置相机初始位置（指向中国区域）
  viewer.camera.setView({
    destination: Cartesian3.fromDegrees(
      104.1954, // 经度
      35.8617,  // 纬度
      5000000   // 高度（米）
    ),
    orientation: {
      heading: 0, // 水平旋转角度（0为正北）
      pitch: -0.5, // 俯仰角度（负为向下看）
      roll: 0 // 翻滚角度
    }
  })

  // 3. 可选：添加一个测试实体（红色点）
  viewer.entities.add({
    position: Cartesian3.fromDegrees(116.404, 39.915), // 北京坐标
    point: {
      color: Color.RED, // 颜色
      pixelSize: 10, // 像素大小
      outlineColor: Color.WHITE, // 轮廓颜色
      outlineWidth: 2 // 轮廓宽度
    },
    name: "北京位置标记" // 鼠标悬浮时显示的名称
  })

  // 4. 隐藏Cesium默认版权信息（可选，商业项目需注意版权）
  viewer._cesiumWidget._creditContainer.style.display = 'none'
})

// 组件卸载时销毁Viewer（防止内存泄漏）
onUnmounted(() => {
  if (viewer) {
    viewer.destroy()
    viewer = null
  }
})
</script>

<style scoped>
.cesium-container {
  width: 100vw;
  height: 100vh;
  overflow: hidden;
}
</style>

2. 在主页面使用组件​

修改src/App.vue，替换默认内容为：

<template>
  <div id="app">
    <CesiumViewer />
  </div>
</template>

<script setup>
import CesiumViewer from './components/CesiumViewer.vue'
</script>

<style>
/* 清除默认样式 */
* {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}
</style>

3. 运行项目并验证​

终端执行npm run dev，打开浏览器访问本地地址（如http://127.0.0.1:5173/），若看到以下效果则成功：​

• 一个三维地球场景​

• 右侧有底图切换、搜索等控件​

• 鼠标悬浮在红色点上显示 “北京位置标记”​

• 可通过鼠标拖拽旋转地球、滚轮缩放​

五、常见问题解决（新手必看）​

1. 问题 1：Cesium 资源加载失败（404 错误）​

• 原因：Vite 未正确解析 Cesium 静态资源​

• 解决方案：​

1. 检查vite.config.js中cesium别名路径是否正确​
2. 若仍报错，可手动复制node_modules/cesium/Source/Assets、node_modules/cesium/Source/Widgets到public目录，并重写资源路径：

// 在初始化Viewer前添加
window.CESIUM_BASE_URL = '/Widgets/'

2. 问题 2：地球显示为黑色（无影像）​

• 原因：Cesium 默认底图需要联网，或跨域配置问题​

• 解决方案：​

1. 检查网络是否正常（默认加载 Bing 地图）​
2. 若跨域报错，确保vite.config.js中proxy配置正确​
3. 可替换为开源底图（如天地图），后续文章会详细讲解

3. 问题 3：容器无高度（地球不显示）​

• 原因：未给 Cesium 容器设置明确宽高​

• 解决方案：确保.cesium-container样式中包含width: 100vw; height: 100vh;（或固定像素值）

六、总结与下一篇预告​

本文完成了 3 件核心事：​

1. 搭建了 Vue3+Vite+Cesium 的基础开发环境​
2. 实现了首个可交互的三维地球场景（含相机控制、实体添加）​
3. 解决了新手常见的环境配置坑点​

下一篇预告：《Cesium 核心概念解析与相机控制实战》—— 会深入讲解 Viewer、Scene、Camera 等核心对象，以及如何实现自定义视角切换、飞行漫游等功能，同时带大家加载自定义底图（如天地图、高德地图）。​

如果本文对你有帮助，欢迎点赞 + 收藏，有问题可在评论区留言，我会及时回复！