一、前言EarthSDK3 最大特点是引擎无关一套业务代码可以同时支持 Cesium 浏览器渲染、UE 虚幻视口渲染封装了大量底层逻辑不用深度啃 Cesium 原生复杂 API 就可以快速做三维数字孪生业务。网上有一篇入门教程附带完整 Gitee 示例工程。为了更好理解整套框架我没有直接下载成品项目而是新建空白 Vite‑Vue 项目一步步安装依赖、编写代码复现案例功能。在复现原有功能之外自己额外开发新的业务组件过程踩了很多示例仓库不会遇到的问题把真实经历记录下来。参考原文仓库https://gitee.com/future0105/earth.git二、环境搭建 真实踩坑记录2.1 依赖安装与 vite.config 配置踩坑新建 Vite 项目后安装 EarthSDK 全套依赖一开始漏掉vite‑plugin‑static‑copy插件配置。坑 1earthsdk3‑assets 静态资源 404现象页面运行起来三维地球正常显示但是所有 POI 图标、标绘素材全部不显示控制台报静态 js 文件 404。 原因earthsdk3‑assets 里面的图标、资源文件需要拷贝到输出目录不配置 vite‑plugin‑static‑copy打包后资源找不到。 解决配置 viteStaticCopy 插件把 node_modules 下 earthsdk3‑assets 复制到 js 目录同时 index.html 引入对应 js 文件。坑 2Vite 别名路径写错路由文件找不到组件新增图源切换练习页面路由配置/views/ImagerySwitch/Index.vue实际文件夹和文件名大小写、层级不对Vite 直接报错Failed to resolve import xxxDoes the file exist?。 一开始反复检查路由代码忽略磁盘上真实文件夹命名VSCode 提示看不出来路径错误。 解决核对磁盘真实目录要么修改路由 import 路径要么新建对应文件夹与 Index.vue 文件修改路由之后必须重启 vite 开发服务器热更新修复不了路由文件找不到的问题。2.2创建 Cesium 视口生命周期问题坑 3setup 顶层直接创建 viewer拿不到 DOM 元素一开始直接在script setup顶层执行objm.createCesiumViewer(earth.value)ref 获取不到真实 DOM创建视口直接失败。 原因setup 执行阶段 DOM 还未挂载ref 容器是 null。 解决必须放到onMounted生命周期里面获取 dom 再创建视口。三、Vue 模板开发遇到非常迷惑的真实 bug亲身遇到坑 4路由代码异常页面按钮直接消失控制台无明显红色报错场景首页页面需要增加按钮跳转到我自己写的影像图源切换练习页面。 在 script setup 顶层写useRouter()项目路由还没有完全调试到位内部抛出异常。 诡异现象控制台没有显眼报错但是模板里面一部分 DOM 直接丢失按钮看不见页面其他内容正常渲染。排查很久才定位。 原因Vite 静默吞掉部分 setup 内部异常不会整页崩溃只会把出错代码关联的模板片段直接丢弃。 解决不要在 script setup 顶层直接执行 useRouter完善 vue‑router 安装与路由配置调试阶段先注释路由跳转逻辑模板 DOM 立刻恢复显示。坑 5UE 视口切换点击 WebSocket 1006 报错点击切换 UE 视口按钮控制台 WebSocket 1006 断开报错。 原因本地没有启动 ESSS 信令服务和 EarthSDK.exe 程序没有部署 UE 后端环境。 学习阶段可以先忽略这个报错优先把 Cesium 相关功能吃透。四、复现原有示例仓库实现功能基于参考示例拆分多个页面路由复现已有功能Cesium/UE 视口切换影像图层显隐控制测量组件距离、面积、高度测量清除测量对象POI 标绘点、模型标绘天气雨雪云特效相机视角书签保存地图右键自定义菜单。五、✨自己新增开发的功能模块重点这部分是参考示例仓库原本没有我自己分析 SDK API 之后新增实现的练习功能。5.1 影像图源切换练习页面新建独立路由页面/imagerySwitch专门用来练习影像图层ESImageryLayer。 功能点el‑select 下拉选择不同在线瓦片图源ArcGis 卫星、高德卫星切换下拉选项动态替换底图图层 url开关控制影像图层显示隐藏独立页面不和首页业务代码耦合方便学习调试objm.createSceneObject创建图层对象。学习收获理解createCesiumViewer()仅仅创建画布地球影像属于场景对象画布本身是黑色空白球体图层需要手动创建添加。5.2 经纬度、高度输入相机飞到目标点位重点练习独立表单组件完全依靠 EarthSDK 内部 API 实现不需要调用任何第三方地图接口。 功能点表单输入框经度、纬度、高度完整表单校验逻辑判断输入不能为空判断输入必须为合法数字经度范围校验‑180 ~ 180纬度‑90 ~ 90高度合理范围校验校验不通过使用ElMessage弹出中文提示校验全部通过之后调用 SDK 接口执行相机飞行动画平滑飞到输入的经纬高点位。练习点相机飞行 API 使用、表单数据校验、Element Plus 消息提示组件使用。六、学习总结与框架理解EarthSDK3 引擎无关的设计同一套业务对象 API底层可以切换 Cesium 或者 UE 渲染减少两套引擎重复开发工作量。所有影像、测量、POI、天气都属于场景对象统一使用objm.createSceneObject()创建destroySceneObject()销毁对象管理模式统一。从零搭建项目会遇到很多直接运行成品仓库不会出现的配置坑对理解整套框架帮助更大。开发三维页面一定要重视销毁逻辑WebGL 很容易出现内存泄漏。Vue3Vite 开发注意控制台没有报错不等于代码没问题部分异常会被静默捕获表现为部分 DOM 消失。