★ FEATURED ARTICLE 简介基于Vite、Vue3、TypeScript与Cesium.js的集成项目模板面向需要快速构建三维地球场景的Web前端开发者解决Cesium与Vue生态整合耗时的问题。模板封装了Vue3组合式API、TypeScript类型系统与Cesium原生实例的对接逻辑并内置一个可运行的地球场景示例包含视角控制、图层加载等基础交互方便开发者快速理解三维组件的挂载与卸载流程。资源包共16个文件涵盖Vue组件、TypeScript定义、JSON配置、样式与SVG图标等压缩后仅21KB结构紧凑且依赖清晰其中JSON与TypeScript文件负责配置与类型声明Vue组件和样式文件构建界面SVG补充图标资源Markdown与YAML则提供说明文档和构建选项。已有2686人学习下载适合具备一定Vue基础、希望深入Cesium的开发者参考。模板还预置了axios、element-plus、vuex等常用依赖并提供基于pnpm的锁定文件可保证环境一致性同时通过文档与构建配置帮助读者跳过繁琐的环境配置专注业务逻辑与三维可视化开发也可作为团队项目的初始脚手架。1. 从零搭一个三维 GIS 工程坑比想象中多接手三维 GIS 项目时最耗时的往往不是 Cesium API 本身而是工程化配置Vite 打包 Cesium 的资源路径、TypeScript 类型声明、按需加载的组件封装、viewer 的生命周期管理。这套 Vite Vue3 TypeScript Cesium.js 集成模板就是把这些“地基”一次性打好让开发者的重心直接落在业务图层、粒子特效和场景交互上而不是反复折腾构建配置。适合两类人一是打算用 Cesium 做城市级数字孪生、地块可视化的前端工程师二是想从二维地图转向三维场景、但对 WebGL 和 Cesium 底层不熟的 Vue 开发者。它解决的痛点是“开箱即用”——clone 下来、装依赖、跑 dev浏览器里就能看到一个可拖拽、可缩放、可拾取的三维地球。2. 技术选型拆解为什么偏偏是这四件套2.1 ViteCesium 这种“巨无霸”依赖靠它做开发时提速Vite 在开发模式下基于原生 ESModule按需编译Cesium 的包体积在 4MB 量级如果用 Webpack冷启动可能要等 20 秒以上改一行代码热更新也要晃几秒。Vite 把 Cesium 作为依赖预构建配合optimizeDeps配置能大幅缩短二次启动时间。生产构建走 Rollup配合vite-plugin-cesium可以自动处理 Cesium 的静态资源拷贝和CESIUM_BASE_URL注入。模板里对 Vite 的配置重点在三个地方base路径、build.target和server代理。我一般会把base设为相对路径./这样部署到子目录或对象存储后不用改代码build.target设为es2015兼顾老浏览器server.proxy用来转发地图服务请求解决跨域。2.2 Vue3 TypeScript组合式 API 才是三维场景的正确姿势Vue3 的setup语法和 Cesium 的声明式对象模型很搭——ref管理 viewer 实例onMounted初始化onUnmounted销毁。如果用 Options APICesium 的viewer、entities、viewer.camera这种强关联对象散落在data、methods、watch里代码会很快失控。TypeScript 声明文件让 Cesium 的 API 有了完整的“说明书”编辑器提示能直接给出参数类型和重载签名。模板里一般会内置一个组合式函数目录src/composables/把 viewer 创建、相机飞行、实体管理抽成独立模块。类型声明上Cesium 官方提供的是cesium/index.d.ts如果模板里没有需要在tsconfig.json的types数组中显式引用。2.3 目录结构每个文件夹的用途先说清楚├── public/ │ └── cesium/ # Cesium 静态资源Workers、Assets、Widgets ├── src/ │ ├── components/ │ │ └── CesiumViewer.vue # 封装好的三维地图组件 │ ├── composables/ │ │ ├── useCesium.ts # 创建 viewer 的组合式函数 │ │ ├── useCamera.ts # 相机控制封装 │ │ └── useEntities.ts # 实体增删改查封装 │ ├── config/ │ │ └── cesium.config.ts # 全局配置token、默认视角、terrain │ ├── views/ │ │ └── HomeView.vue # 地图页面入口 │ ├── types/ │ │ └── cesium.d.ts # 补充的类型声明 │ ├── utils/ │ │ └── offline.ts # 离线数据加载工具 │ ├── App.vue │ └── main.ts ├── vite.config.ts ├── tsconfig.json └── package.jsonpublic/cesium是模板里比较关键的一步——Cesium 在运行时需要通过CESIUM_BASE_URL去加载 Web Worker 和纹理资源。有人把 Cesium 直接import进来后遇到黑屏原因就是静态资源没被正确拷贝。模板把静态资源放在public下并配置了CESIUM_BASE_URL/cesium从根源上规避了这个问题。3. 核心模块实战一个三维地球从初始化到交互的完整链路3.1 viewer 初始化别用默认的按业务来配模板里useCesium.ts的初始化逻辑通常是这样写的// src/composables/useCesium.ts import * as Cesium from cesium import { ref, shallowRef } from vue // 使用 shallowRef 避免 Vue 深度代理 Cesium 实例带来的性能损耗 const viewer shallowRefCesium.Viewer | null(null) export function useCesium(container: HTMLElement) { viewer.value new Cesium.Viewer(container, { animation: false, // 关闭动画控件 timeline: false, // 关闭时间轴 baseLayerPicker: false, // 关闭底图选择器 geocoder: false, // 关闭搜索框 sceneModePicker: false, // 关闭场景模式切换 navigationHelpButton: false, fullscreenButton: false, infoBox: false, // 关闭默认弹窗 selectionIndicator: false, terrain: Cesium.Terrain.fromWorldTerrain() // 开启地形 }) return viewer }这段代码里有几个关键参数值得展开说baseLayerPicker: false会隐藏左上角的图层选择按钮很多业务系统里必须关闭infoBox: false和selectionIndicator: false则是为了后续自定义弹窗避免 Cesium 默认的 HTML 弹窗遮挡业务 UI。最容易被忽略的是shallowRef而不是ref——Cesium 的Viewer内部维护了大量原生对象和事件监听如果让 Vue 对其实施深度响应式代理拖动相机时会产生海量的依赖收集帧率会明显下降。地形配置用的是Cesium.Terrain.fromWorldTerrain()这是 Cesium 1.104 之后的写法老版本用的是Cesium.createWorldTerrainAsync()。如果你用的是旧模板这里需要手动升级否则 TypeScript 编译阶段就会报错。3.2 相机视角从“定位到地球”到“飞到目标点”初始化后如果视角停在太空里用户会以为地图没加载出来。模板里的useCamera.ts提供了两个核心方法——flyTo和setView// src/composables/useCamera.ts import * as Cesium from cesium import { viewer } from ./useCesium // 飞行到指定坐标duration 控制飞行时长 export function flyTo(lng: number, lat: number, height: number, duration 3) { viewer.value?.camera.flyTo({ destination: Cesium.Cartesian3.fromDegrees(lng, lat, height), orientation: { heading: Cesium.Math.toRadians(0), pitch: Cesium.Math.toRadians(-45), roll: 0 }, duration }) } // 瞬移不带动画适合地图初始化 export function setView(lng: number, lat: number, height: number) { viewer.value?.camera.setView({ destination: Cesium.Cartesian3.fromDegrees(lng, lat, height) }) }fromDegrees将经纬度转换为笛卡尔坐标可直接作为flyTo的destination。orientation中的heading是相机朝向正北为 0pitch是俯仰角-45 表示从斜上方观察。需要说明的是flyTo是异步的如果紧接着调用getPosition去读取相机坐标读到的可能是飞行前的值。模板里一般会配合camera.moveEnd事件来做飞行后的回调处理。3.3 实体管理业务图层像操作数组一样简单Cesium 的entities集合虽然好用但项目一大就会出现“实体满天飞”的局面——内存泄漏、重复 ID 冲突、批量删除无门。模板的useEntities.ts将实体的增删改查包了一层// src/composables/useEntities.ts import * as Cesium from cesium import { viewer } from ./useCesium export function addEntity(opt: { id: string lng: number lat: number height?: number billboard?: string label?: string }) { return viewer.value?.entities.add({ id: opt.id, position: Cesium.Cartesian3.fromDegrees(opt.lng, opt.lat, opt.height ?? 0), billboard: opt.billboard ? { image: opt.billboard, scale: 0.5 } : undefined, label: opt.label ? { text: opt.label, pixelOffset: new Cesium.Cartesian2(0, -30), font: 14px sans-serif } : undefined }) } export function removeEntity(id: string) { viewer.value?.entities.removeById(id) } export function clearAll() { viewer.value?.entities.removeAll() }这里有个模板层面的设计细节viewer.entities本身是EntityCollection它有add、removeById和removeAll三个原生方法。封装的意义不在包一层而在于统一了实体创建时的默认样式——比如billboard的默认缩放、label的默认偏移。实际业务里你从后端拉到的设备点位可能要区分在线/离线、正常/告警模板的扩展点在addEntity里加一个color参数即可。3.4 事件交互点击拾取和鼠标悬浮一个都别漏三维场景的事件交互和二维不同点击对象时要通过scene.pick做射线检测并且需要判断拾取到的是不是 entity// src/utils/pick.ts import * as Cesium from cesium import { viewer } from ../composables/useCesium export function initPickHandler() { const handler new Cesium.ScreenSpaceEventHandler(viewer.value!.scene.canvas) handler.setInputAction((movement) { const picked viewer.value!.scene.pick(movement.position) if (Cesium.defined(picked) picked.id) { // 这里拿到了 entity 的 id可以回传后端做数据联动 console.log(picked entity id:, picked.id.id) } }, Cesium.ScreenSpaceEventType.LEFT_CLICK) return handler }scene.pick接受屏幕坐标会从 Canvas 中做像素级拾取。picked.id在拾取到 entity 时是 entity 对象拾取到 3D Tiles 时可能是 primitive 或 Cesium3DTileFeature。这块是 Cesium 官网文档写得最模糊的地方模板里加上这一层封装后业务侧接入就不用关心拾取底层差异了。4. 从模板到业务项目运行、构建和避坑指南4.1 克隆后第一步依赖安装和 ION Token 处理无论模板里是否内置了ion.defaultAccessToken我都建议你尽早注册一个自己的 Cesium ION Token——因为 Cesium 的在线影像底图、地形服务都走 ION匿名 token 有并发限制。模板的cesium.config.ts一般预留了配置入口// src/config/cesium.config.ts import * as Cesium from cesium Cesium.Ion.defaultAccessToken import.meta.env.VITE_CESIUM_ION_TOKEN export const DEFAULT_VIEWER_OPTIONS { // 省略其他 viewer 配置 }这里用的import.meta.env.VITE_CESIUM_ION_TOKEN是 Vite 的环境变量机制。在项目根目录创建.env.local文件写入VITE_CESIUM_ION_TOKEN你的tokenVite 会自动加载而且只有VITE_前缀的变量才会暴露给前端代码服务端密钥不会误入打包产物。跑起来之后如果发现底图是灰色的或者地形拉不起来第一步去 Network 面板看api.cesium.com的请求是否返回 401 或 429。401 是 token 错了429 是并发超限——这两个状态是翻车率最高的两个点十有八九和业务代码无关。4.2 打包部署静态资源路径和 gzip 的坑生产构建时如果base没配置好cesium/Workers下的 Worker 脚本会 404场景黑屏但控制台没有任何报错。模板把base: ./写在vite.config.ts里部署到 Nginx 子目录和对象存储时都能适配。另外一个容易忽视的性能点是build.rollupOptions的output.manualChunks。Cesium 的体积太大如果和三方库打在一个 chunk 里首屏加载会非常慢。模板一般会把 Cesium 单独拆出来// vite.config.ts export default defineConfig({ base: ./, build: { rollupOptions: { output: { manualChunks: { cesium: [cesium] } } } } })拆包之后cesium.js会被独立加载并利用浏览器缓存业务代码更新时不会让用户重新下载那个 4MB 的大文件。部署到生产后建议在 Nginx 开启 gzipCesium 的 JS 压缩率通常能在 70% 以上首屏传输体积能压到 1MB 出头。4.3 常见踩坑记录坑一投产后地图黑屏但有光照和天空盒现象是 Cesium 场景里能看到星空背景但地球是黑的底图不渲染。原因多半是baseLayer配置缺失——新版本 Cesium 默认使用 Ion 的在线影像网络环境受限或 token 失效时底图就会静默失败。解决方式有两种一是配置离线底图二是给Viewer传imageryProvider替换默认影像。我一般习惯在cesium.config.ts里显式指定一个 OpenStreetMap 或 ArcGIS 在线服务作为兜底。坑二拖拽地图时页面卡顿帧率低于 20原因是viewer被 Vue 的reactive或ref做了深度代理。Cesium 每帧都在更新相机位置而viewer.camera的属性变化会触发 Vue 的响应式依赖追踪导致脏检查耗掉大量主线程时间。解决方式是在useCesium.ts里用shallowRef或者直接用markRaw标记 viewer告诉 Vue 不要代理它。坑三Cesium.Ion.defaultAccessToken赋值时机太晚有时候初始化 viewer 就会抛CesiumIon相关错误原因是 token 赋值发生在new Viewer()之后Cesium 在创建默认底图时已经带着匿名 token 去请求了。解决方式是把 token 赋值放到main.ts中在new Viewer之前执行模板里更稳妥的做法是单独建一个initCesium.ts在app.mount之前引入。坑四打包后地图层级很浅放大了才能看到细节原因是terrainProvider没有生效Cesium 用的是默认椭球体地形没有高程数据渲染的视觉效果。检查方式有两个一是查看viewer.terrainProvider是否为EllipsoidTerrainProvider二是看 Network 面板是否有地形瓦片请求。模板如果引入了地形服务确认 token 有地形权限没权限的话terrainProvider会静默回退。坑五vue-tsc 类型检查报 Cesium 模块找不到声明现象是编译时提示Could not find a declaration file for module cesium。新版 Cesium 自带类型声明旧的写法里要装types/cesium已经停止维护。解决方式是升级到 Cesium 1.100并在tsconfig.json的compilerOptions.types里确认没有显式排除cesium。5. 二次开发扩展思路把这个模板改造成你的业务基座模板的价值上限取决于你怎么扩展它。我建议从三个方向入手分别对应不同业务阶段。第一把CesiumViewer.vue从“单页面嵌入”改成“多页面复用”。模板里useCesium是单例模式如果项目里有多个路由都需要地图组件最好按路由实例化多个Viewer然后在onUnmounted里调用viewer.destroy()。常见做法是给useCesium增加一个key参数用 Map 缓存多个 viewer避免切换路由时出现“上一页的实体残留”问题。第二封装自己的图层加载器。Cesium 对 GeoJSON、KML、3D Tiles 有不同的数据源类型模板一般只覆盖了 entity你可以参考useEntities的写法新增一个useDataSource.ts统一管理Cesium.GeoJsonDataSource.load()和Cesium.Cesium3DTileset的加载、样式过滤和销毁。3D Tiles 的style是 Cesium 里最强大的功能——按高度着色、按属性设置透明度、做条件渲染都可以建议尽早研究它的语法。第三接入真实业务数据流。模板里addEntity的入参是硬编码的你可以在此基础上加一个fetchDeviceList的逻辑用轮询或 WebSocket 推送设备状态动态更新 billboard 的颜色和 label。Cesium 实体更新不需要重建找到实体后直接改entity.billboard.color渲染线程下一帧就会自动处理。验证扩展效果时我建议给自己定三个硬指标一是看切换路由时浏览器内存是否持续增长——上升就说明 viewer 或事件处理器没有被正确销毁二是看数据量增长到 10 万条 entity 时场景帧率是否能保持 30 以上——不行就要考虑改用Primitive或CustomDataSource批量渲染三是看生产包首屏传输体积是否控制在 2MB 以内——超了就回头检查manualChunks和静态资源有没有混进业务解构。从那次把模板里的单例 viewer 改成多实例之后我每次接手新项目都强制自己先花几个小时把模板的composables目录通读一遍再动手写业务组件。理解了它的抽象层次和封装思路后换到任何 Vue3 Cesium 的项目都能快速上手。希望这篇拆解能帮你在三维 GIS 的路上少走几个弯路。本文还有配套的精品资源点击获取
阅读完成 · 觉得有帮助？
