Cesium 从入门到精通一Vue3 Vite TS Cesium 环境搭建显示你的第一个 3D 地球本系列从零开始手把手带你用Vue3 Vite TypeScript Cesium Element Plus做一个可落地的三维 GIS 应用后端部分会逐步引入GeoServer / PostGIS / Spring Boot。每一期只做一件事写完就能跑附完整源码。本期是第 1 期把工程搭起来在浏览器里转出一个带影像底图的 3D 地球。一、最终效果浏览器打开http://localhost:5173/就能看到一个转到中国上空的 3D 地球底图是 ArcGIS 在线卫星影像可以用鼠标拖拽旋转、滚轮缩放。二、技术栈与版本技术版本说明Node.jsv22.x建议 ≥ 18Vue^3.5组合式 APIVite^8构建工具TypeScript~6.0Cesium1.146.0npm latest2026-10 验证三维地球引擎Element Plus^2.14UI 组件库本期先装上后面用三、实现步骤1. 创建 Vite Vue3 TS 工程打开终端选一个你喜欢的目录执行npm create vitelatest cesium-tutorial -- --template vue-ts进入工程并安装基础依赖cd cesium-tutorial npm install再装上 Cesium 和 Element Plusnpm install cesium element-plus2. 拷贝 Cesium 静态资源关键一步Cesium 运行时需要加载 WorkersWeb Worker、Assets字体、贴图、Widgets控件样式等静态文件。我们需要把它们从node_modules复制到public/cesium/下# PowerShell 命令在项目根目录执行 $src node_modules\cesium\Build\Cesium $dst public\cesium New-Item -ItemType Directory -Force -Path $dst Copy-Item $src\Assets,$src\Widgets,$src\Workers,$src\ThirdParty $dst -Recurse -Force复制完后目录结构应该是这样public/ └── cesium/ ├── Assets/ ├── ThirdParty/ ├── Widgets/ └── Workers/为什么要这一步因为 Vite 只会把public/下的文件原样拷贝到产物里。Cesium 在运行时会通过CESIUM_BASE_URL这个全局变量去找这些文件找不到就会黑屏、报404。3. 配置 vite.config.ts告诉 Cesium 去哪里找静态资源// vite.config.ts import { defineConfig } from vite import vue from vitejs/plugin-vue export default defineConfig({ plugins: [vue()], define: { // 关键Cesium 会根据这个全局变量去 /cesium/ 找 Workers / Assets CESIUM_BASE_URL: JSON.stringify(/cesium), }, base: ./, server: { port: 5173, open: true, }, })4. 改造入口文件// src/main.ts import { createApp } from vue import ElementPlus from element-plus import element-plus/dist/index.css // 引入 Cesium 官方控件样式 import cesium/Build/Cesium/Widgets/widgets.css import App from ./App.vue import ./style.css createApp(App).use(ElementPlus).mount(#app)清空脚手架自带的src/style.css改成全局样式/* src/style.css */ * { margin: 0; padding: 0; box-sizing: border-box; } html, body, #app { width: 100%; height: 100%; overflow: hidden; } /* 教学演示先隐藏左下角版权生产环境请保留以遵守 Apache 2.0 许可 */ .cesium-viewer-bottom { display: none !important; }5. 写地图组件src/components/CesiumViewer.vue这是整个系列最核心的一个组件后面所有功能都会在它上面扩展template div classviewer-wrapper !-- Cesium 挂载容器必须有明确宽高 -- div refcontainerRef classcesium-container/div !-- 左上角信息面板后面会换成 Element Plus 组件 -- div classtitle-panel h3Cesium 从入门到精通 · 第 1 期/h3 p我的第一个 3D 地球Vue3 Vite TS Cesium/p /div /div /template script setup langts import { onMounted, ref } from vue import * as Cesium from cesium const containerRef refHTMLElement | null(null) onMounted(() { if (!containerRef.value) return // 1. 创建 ViewerCesium 的核心入口一个页面通常只 new 一个 const viewer new Cesium.Viewer(containerRef.value, { // 2. 底图用 ArcGIS 在线影像无需 ion token 即可看到效果 baseLayer: new Cesium.ImageryLayer( new Cesium.UrlTemplateImageryProvider({ url: https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}, }), ), // 3. 关掉一堆默认控件画面干净一点 animation: false, // 左下角动画控件 timeline: false, // 底部时间轴 baseLayerPicker: false, // 右上角底图切换 geocoder: false, // 搜索框 homeButton: false, // 主页按钮 sceneModePicker: false, // 2D/3D 切换 navigationHelpButton: false,// 帮助按钮 fullscreenButton: false, // 全屏按钮 }) // 4. 相机飞到中国上空 viewer.camera.flyTo({ destination: Cesium.Cartesian3.fromDegrees(105.0, 35.0, 15000000), duration: 0, // 0 直接跳过去不做飞行动画 }) }) /script style scoped .viewer-wrapper { position: relative; width: 100%; height: 100vh; } .cesium-container { width: 100%; height: 100%; } .title-panel { position: absolute; top: 16px; left: 16px; z-index: 10; padding: 12px 16px; background: rgba(0, 0, 0, 0.55); border-radius: 6px; color: #fff; pointer-events: none; } .title-panel h3 { margin: 0 0 4px; font-size: 16px; } .title-panel p { margin: 0; font-size: 13px; opacity: 0.85; } /style6. 改一下App.vuetemplate CesiumViewer / /template script setup langts import CesiumViewer from ./components/CesiumViewer.vue /script顺手把脚手架自带的src/components/HelloWorld.vue删掉。四、运行npm run dev浏览器会自动打开http://localhost:5173/看到一个 3D 地球就成功了。可以鼠标左键拖拽旋转地球滚轮缩放右键拖拽倾斜视角五、几个新手必踩的坑页面一片黑没有地球99% 是CESIUM_BASE_URL没配对或者public/cesium/目录下没有 Workers/Assets。按 F12 看 Network找 404 的文件。报错CesiumViewer is not defined检查src/main.ts里有没有import cesium/Build/Cesium/Widgets/widgets.css。报 ion token 错误本教程用 ArcGIS 影像不需要 token。如果你改成默认底图baseLayer不传Cesium 会去请求 ion这时就需要去 https://ion.cesium.com 申请一个 token配置Cesium.Ion.defaultAccessToken xxx。容器高度为 0地球出不来Cesium 挂载的 div 必须有明确宽高。本教程里.cesium-container是width:100%; height:100%外层.viewer-wrapper是height:100vh再外层#app也是height:100%缺一不可。npm run dev报Cannot find native bindingVite 8 / rolldown这是 npm 的可选依赖optionalDependencies没装全导致的常见两种情况① npm 镜像源过滤了原生二进制最常见如果你配置了国内镜像registry.npmmirror.com部分镜像对.node原生文件同步不完整导致rolldown/binding-win32-x64-msvc装不上。解决用官方源补装缺失的绑定包npm install --save-dev rolldown/binding-win32-x64-msvc --registryhttps://registry.npmjs.org/或把全局源切回官方npm config set registry https://registry.npmjs.org/。② 老 npm 的可选依赖 bug见 https://github.com/npm/cli/issues/4828先npm i -g npmlatest升级 npm删除node_modules和package-lock.json后重新npm install。仍不行就换 pnpm。六、源码结构cesium-tutorial/ ├── public/cesium/ # Cesium 静态资源 ├── src/ │ ├── components/CesiumViewer.vue # 地图组件 │ ├── App.vue │ ├── main.ts │ └── style.css ├── vite.config.ts └── package.json七、下一期预告第 2 期Cesium 核心对象与相机控制—— 讲清楚Viewer / Scene / Camera / Ellipsoid四者关系实现几个按钮让相机飞北京、飞上海、回到全球视角并理解Cartesian3和经纬度的区别。