Vue3+Vite5 集成 Cesium 超详细教程（避坑版）

在前端三维可视化领域，Cesium 凭借强大的地球渲染、空间数据处理能力成为首选框架。而 Vue3 + Vite5 的组合则以高效的开发体验、极速的热更新的优势，成为现代前端项目的主流技术栈。本文将从环境搭建到项目实战，一步步教你如何在 Vue3+Vite5 中无缝集成 Cesium，解决配置别名、静态资源加载、打包优化等核心问题，同时提供可直接复用的基础封装组件，让你少走 99% 的弯路。

一、环境准备

1. 基础环境要求

Node.js：18+（建议 20+，确保兼容 Vite5 和 Cesium 最新依赖）
包管理器：pnpm（推荐，速度更快、依赖管理更高效，也可使用 npm/yarn）
代码编辑器：VS Code（推荐安装 Vue 官方插件、TypeScript 插件）

2. Cesium Ion Token 申请

Cesium 部分功能（如加载在线影像图层、3D Tiles 模型）需要 Ion 密钥支持，申请步骤如下：

访问 Cesium Ion 官网注册 / 登录账号
登录后在个人中心 → Access Tokens 页面，复制默认的 Access Token（或创建新 Token）
注意：Token 属于敏感信息，请勿提交到代码仓库，后续将通过环境变量配置

二、项目初始化与依赖安装

1. 创建 Vue3+TypeScript+Vite 项目

打开终端，执行以下命令创建基础项目（项目名称可自定义）：

pnpm create vite@latest cesium-vue3-demo --template vue-ts

执行后按照提示完成项目创建，进入项目目录：

cd cesium-vue3-demo

2. 安装核心依赖

本项目需要安装 Cesium 核心库和 Vite 专用集成插件，执行以下命令：

pnpm install cesium@^1.137.0 pnpm install vite-plugin-cesium@^1.2.23 -D

cesium@^1.137.0：稳定版 Cesium 库，兼容 Vite5 构建流程
vite-plugin-cesium：自动处理 Cesium 静态资源、按需加载、打包配置的专用插件，避免手动配置的繁琐操作

三、Vite5 核心配置（关键避坑点）

创建 / 修改项目根目录下的vite.config.ts文件，配置 Vue 插件和 Cesium 插件，解决静态资源加载、别名配置等问题：

import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue' import cesium from 'vite-plugin-cesium' // https://vite.dev/config/ export default defineConfig({ plugins: [ vue(), cesium() // 集成 Cesium 插件，自动处理资源拷贝、按需加载 ], // 可选：配置路径别名（如需简化 Cesium 导入路径） resolve: { alias: { '@': '/src', 'cesium-src': 'cesium/Build/Cesium' // 简化 Cesium 核心模块导入 } } })

配置说明与避坑要点

插件顺序：cesium()插件需在vue()之后注册，确保 Vue 组件能正常识别 Cesium 资源
静态资源处理：vite-plugin-cesium会自动拷贝 Cesium 的Build/Cesium目录下的静态资源（如纹理、字体、Worker 脚本）到构建目录，无需手动复制
别名配置：通过cesium-src别名可简化导入路径（如import 'cesium-src/Widgets/widgets.css'），避免写冗长的相对路径
打包兼容：插件已内置 Cesium 打包优化，解决require语法兼容、Worker 脚本打包等问题，无需额外配置build.rollupOptions

四、TypeScript 配置优化

为了让 TypeScript 正确识别 Cesium 类型定义，修改tsconfig.app.json文件，添加相关类型声明：

{ "extends": "@vue/tsconfig/tsconfig.dom.json", "compilerOptions": { "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo", "types": [ "vite/client", "cesium" // 引入 Cesium 类型定义 ], /* Linting */ "strict": true, "noUnusedLocals": true, "noUnusedParameters": true, "erasableSyntaxOnly": true, "noFallthroughCasesInSwitch": true, "noUncheckedSideEffectImports": true }, "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue"] }

五、环境变量配置（Token 管理）

在项目根目录创建.env.local文件，配置 Cesium Ion Token（该文件已在.gitignore中忽略，不会提交到仓库）：

VITE_CESIUM_ION_TOKEN="你的 Cesium Ion Token"

前缀VITE_是 Vite 环境变量的固定前缀，确保在 Vue 组件中通过import.meta.env访问
替换你的 Cesium Ion Token为第二步申请的真实 Token，若未配置 Token，部分在线资源将无法加载

六、Vue3 中 Cesium 核心封装（CesiumViewer.vue）

创建src/components/CesiumViewer.vue组件，封装 Cesium 初始化、容器挂载、生命周期管理等核心逻辑，实现组件化复用：

<template> <!-- Cesium 容器，占满全屏 --> <div class="cesium-viewer" ref="container"></div> </template> <script setup lang="ts"> import { onMounted, onBeforeUnmount, ref } from 'vue' import * as Cesium from 'cesium' // 导入 Cesium 样式文件（必须引入，否则控件样式异常） import 'cesium/Build/Cesium/Widgets/widgets.css' // 容器引用 const container = ref<HTMLDivElement | null>(null) // Cesium Viewer 实例 let viewer: Cesium.Viewer | undefined onMounted(() => { // 从环境变量获取 Token 并配置 const token = import.meta.env.VITE_CESIUM_ION_TOKEN as string | undefined if (token) { Cesium.Ion.defaultAccessToken = token } else { console.warn('未配置 Cesium Ion Token，部分在线资源可能无法加载') } // 容器存在时初始化 Viewer if (container.value) { viewer = new Cesium.Viewer(container.value, { // 配置控件显示/隐藏（根据需求调整） animation: false, // 隐藏动画控件 timeline: false, // 隐藏时间轴控件 baseLayerPicker: true, // 显示图层选择器（切换影像/地形） sceneModePicker: true, // 显示场景模式切换（2D/3D/Columbus View） geocoder: true, // 显示地理编码控件（搜索地址） homeButton: true, // 显示首页按钮（返回默认视角） navigationHelpButton: false, // 隐藏帮助按钮 fullscreenButton: true, // 显示全屏按钮 // 可选：配置默认加载的影像图层 imageryProvider: new Cesium.ArcGisMapServerImageryProvider({ url: 'https://services.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer' }) }) // 可选：调整默认视角（例如定位到中国区域） viewer.camera.flyTo({ destination: Cesium.Cartesian3.fromDegrees(103.8198, 36.5683, 10000000), // 经纬度+高度 duration: 2 // 飞行时长（秒） }) } }) onBeforeUnmount(() => { // 组件卸载时销毁 Viewer，释放内存（关键避坑点） if (viewer && !viewer.isDestroyed()) { viewer.destroy() viewer = undefined } }) </script> <style scoped> .cesium-viewer { width: 100%; height: 100vh; display: block; overflow: hidden; } </style>

封装亮点与避坑解析

生命周期管理：在onMounted中初始化 Viewer，onBeforeUnmount中销毁实例，避免内存泄漏（Cesium 实例若不手动销毁，会残留大量 DOM 和事件监听）
样式引入：必须导入cesium/Build/Cesium/Widgets/widgets.css，否则 Cesium 控件（如图层选择器、搜索框）会样式错乱
Token 动态配置：从环境变量读取 Token，避免硬编码，提高项目安全性和可配置性
控件自定义：通过Viewer配置项灵活控制控件显示，满足不同项目需求
视角初始化：通过camera.flyTo定位到目标区域，提升用户体验

七、项目使用与运行

1. 在根组件中使用 CesiumViewer

修改src/App.vue，引入并使用封装好的CesiumViewer组件：

<template> <div id="app"> <!-- 引入 Cesium 地球组件 --> <CesiumViewer /> </div> </template> <script setup lang="ts"> import CesiumViewer from './components/CesiumViewer.vue' </script> <style scoped> #app { margin: 0; padding: 0; width: 100%; height: 100vh; } </style>

2. 运行项目

执行以下命令启动开发服务器：

pnpm run dev

启动成功后，访问终端输出的地址（默认：http://localhost:5173），即可看到全屏的 Cesium 地球场景，支持鼠标拖拽旋转、滚轮缩放、控件操作等功能。

3. 构建与预览

项目开发完成后，执行以下命令构建生产版本：

pnpm run build

构建完成后，可通过以下命令预览构建结果：

pnpm run preview

八、常见问题与避坑指南

1. 静态资源找不到（404 错误）

原因：未正确安装vite-plugin-cesium或插件配置错误
解决方案：
1. 确认vite-plugin-cesium已安装在 devDependencies 中
2. 确保vite.config.ts中已注册cesium()插件
3. 重新安装依赖：pnpm install，并重启开发服务器

2. Token 无效或未配置

现象：控制台报错Cesium Ion Access Token is not set，在线影像图层无法加载
解决方案：
1. 确认.env.local文件中已配置正确的 Token
2. 检查 Token 前缀是否为VITE_（大小写敏感）
3. 若 Token 过期，重新登录 Cesium Ion 生成新 Token

3. 组件卸载后内存泄漏

现象：切换路由后，浏览器内存占用过高，控制台报错
解决方案：
1. 确保在onBeforeUnmount中调用viewer.destroy()
2. 避免在组件外部存储 Viewer 实例，防止无法销毁

4. TypeScript 类型报错

现象：导入 Cesium 时提示 “找不到模块” 或类型定义错误
解决方案：
1. 确认tsconfig.app.json中已添加types: ["cesium"]
2. 重新安装 Cesium 依赖：pnpm install cesium@^1.137.0
3. 清除 TypeScript 缓存：删除node_modules/.tmp目录后重启 VS Code

九、项目目录说明

cesium-vue3-demo/ ├── .env.local # 环境变量配置（Token） ├── vite.config.ts # Vite 配置文件 ├── tsconfig.json # TypeScript 根配置 ├── tsconfig.app.json # 应用代码 TypeScript 配置 ├── src/ │ ├── main.ts # 应用入口文件 │ ├── App.vue # 根组件 │ ├── components/ │ │ └── CesiumViewer.vue # Cesium 核心封装组件 │ └── style.css # 全局样式 └── package.json # 依赖配置

十、代码仓库地址

本文完整代码已上传至 Gitee，可直接克隆使用：

git clone https://gitee.com/YAY-404/cesium-vue3-demo.git cd cesium-vue3-demo pnpm install # 配置 .env.local 中的 Token 后运行 pnpm run dev

总结

通过本文的步骤，你已成功实现 Vue3+Vite5 与 Cesium 的无缝集成，掌握了环境配置、组件封装、生命周期管理等核心技能。封装的CesiumViewer组件可直接复用在实际项目中，vite-plugin-cesium插件则解决了静态资源、打包兼容等关键问题。