1. 为什么要在UE5里折腾离线地图把Cesium for Unreal和UE5捏在一起做离线地图这个需求最早是从几个做数字孪生和飞行模拟的团队里冒出来的。在线地图服务在演示环境里跑得好好的一到客户现场就抓瞎——厂区网络隔离、野外没有信号、保密项目不允许外联这些都是硬约束。你总不能跟客户说“麻烦您先拉根网线”吧。Cesium for Unreal本身是个很优秀的插件它把3D Tiles、地形瓦片、影像瓦片这套体系带进了UE5让虚幻引擎具备了渲染全球尺度地理数据的能力。但它的默认工作模式是流式加载在线资源一旦断网整个场景就是一片黑。离线地图方案要解决的核心问题就一个把原本需要实时请求的瓦片数据提前落到本地让Cesium在运行时从磁盘读取。这套方案适合谁做智慧城市可视化、军事仿真、飞行模拟器、矿区/油田数字孪生的朋友只要你的项目涉及真实地理坐标、大范围地形、且运行环境不可控那离线化就是绕不过去的一步。我前后在三个项目里落地过这套流程踩的坑足够写一篇避雷指南了。2. 整体方案设计与技术选型思路2.1 离线地图的三种技术路线对比在UE5里做离线地图不是只有Cesium一条路。我把常见的几种方案列出来你根据自己的场景选。方案原理优点缺点适用场景Cesium离线瓦片预下载3D Tiles和地形瓦片到本地Cesium从磁盘加载地理精度高支持全球尺度LOD完善数据量大预处理耗时大范围地形、数字孪生手工建模地形用World Machine等工具生成高度图导入UE5完全可控不依赖外部数据地理坐标不准确范围有限小范围游戏场景静态网格拼接把卫星影像贴到平面网格上实现简单无地形起伏无LOD平面地图展示我选Cesium离线方案的理由很直接项目要求地理坐标准确、范围覆盖几十平方公里、还要有地形起伏。手工建模精度不够静态网格又太假。Cesium的3D Tiles体系天然支持多级LOD离线化之后既保留了精度又解决了网络问题。2.2 离线数据的来源与组织方式离线地图的数据来源主要有两个渠道。一是Cesium官方提供的全球基础地形和影像可以通过Cesium ion平台导出二是自己用无人机倾斜摄影或者卫星影像生成3D Tiles。不管哪种来源最终都要组织成Cesium能识别的目录结构。核心数据结构是这样的地形瓦片放在一个文件夹里按层级和行列号命名影像瓦片放在另一个文件夹3D Tiles模型单独一个目录里面包含tileset.json和对应的b3dm文件。Cesium在运行时会根据相机位置计算需要加载哪些瓦片然后从对应的本地路径读取。这里有个关键决策是全部预下载还是按需下载我的建议是分层处理。地形和低层级影像全量下载高层级影像按项目实际覆盖范围裁剪。全球地形数据大概几十GB全量下载不现实但你可以只下载项目所在区域的瓦片。2.3 UE5版本与Cesium插件的匹配UE5的版本选择直接影响Cesium插件的兼容性。我实测下来UE5.1和UE5.2对Cesium for Unreal的支持最稳定。UE5.3之后插件更新节奏有点跟不上偶尔会出现编译报错。如果你不是必须用最新版建议锁在5.2。Cesium for Unreal的版本也要注意。1.0之前的版本API变动很大1.0之后稳定了不少。目前推荐用1.2以上的版本它对本地文件路径的支持更完善。安装方式有两种从Epic商城直接装或者从GitHub拉源码编译。商城版省事源码版方便你改代码适配特殊需求。注意UE5和Cesium插件的版本必须匹配混用容易出现链接错误。装之前先查一下插件的Release Notes里写的兼容版本。3. 离线数据准备与瓦片处理实操3.1 地形瓦片的获取与格式转换地形数据是整个离线地图的骨架。Cesium用的是quantized-mesh格式的地形瓦片这种格式把高度信息量化存储比传统的heightmap节省空间。获取地形数据有几种途径。如果你有DEM数据比如SRTM、ASTER可以用Cesium的terrain-builder工具把它转成quantized-mesh。这个工具是Python写的跑起来不复杂。先安装依赖然后指定输入DEM文件和输出目录它会自动切瓦片。pip install cesium-terrain-builder ctb-tile -o ./terrain_output -C -N -f Mesh ./dem_input.tif参数解释一下-C表示生成Cesium格式-N表示从零开始编号-f Mesh指定输出quantized-mesh。跑完之后你会得到一个按层级组织的目录每层下面是一堆.terrain文件。如果没有DEM数据也可以从Cesium ion下载。登录之后选好区域导出为quantized-mesh格式。免费账户有额度限制大范围下载需要付费。我一般建议项目初期先用小范围数据验证流程跑通了再批量下载。3.2 影像瓦片的切片与本地化影像瓦片比地形简单就是标准的XYZ瓦片或者TMS瓦片。你可以用gdal2tiles把大图切成瓦片。gdal2tiles.py -p geodetic -z 0-18 satellite_image.tif ./imagery_output-p geodetic指定投影方式-z 0-18指定切片的层级范围。层级越高瓦片越多18层已经能到米级精度了。切完之后每个层级一个文件夹里面是行列号命名的图片文件。这里有个坑Cesium默认请求的影像瓦片格式是jpg或者png但如果你用的是TMS规范Y轴方向是反的。Cesium for Unreal里可以配置UrlTemplate来指定请求路径TMS的话要在URL里加{-y}。3.3 3D Tiles模型的离线导出如果你有倾斜摄影模型或者手工建的精细模型需要转成3D Tiles格式。常用的工具是CesiumGS的3d-tiles-tools或者用Cesium ion的在线转换服务。3d-tiles-tools可以把obj、gltf、glb转成b3dm。命令大概是这样npx 3d-tiles-tools gltfToB3dm -i model.glb -o output.b3dm转完之后要手动写一个tileset.json描述瓦片的层级关系和包围盒。这个json文件是Cesium加载3D Tiles的入口格式不对整个模型都加载不出来。我建议先用一个小模型跑通流程确认tileset.json的写法没问题再批量处理。3.4 目录结构规划与路径映射所有离线数据准备好之后目录结构要规划清楚。我一般这样组织OfflineMapData/ ├── terrain/ │ ├── 0/ │ ├── 1/ │ └── ... ├── imagery/ │ ├── 0/ │ ├── 1/ │ └── ... └── models/ ├── building_a/ │ ├── tileset.json │ └── ... └── building_b/ ├── tileset.json └── ...在UE5项目里这个文件夹可以放在Content目录下也可以放在项目根目录。放Content下的话打包时会自动包含但数据量大的话会让打包体积爆炸。我一般放在项目根目录的OfflineData文件夹然后在Cesium的配置里用相对路径引用。提示路径里不要有中文和空格Cesium对非ASCII路径的支持时好时坏踩过这个坑。4. Cesium for Unreal的离线配置与蓝图实现4.1 插件安装与项目设置Cesium for Unreal装好之后在UE5的插件列表里启用它。然后项目设置里会多出一个Cesium的分类里面有几个关键选项。首先是Default Tileset Source改成From Url这样你可以指定本地文件路径。然后是Cache相关的设置离线模式下缓存其实没太大意义可以关掉节省IO。还有一个容易忽略的点UE5的Allow Static Lighting要关掉。Cesium的地形是动态加载的静态光照烘焙会出问题。在项目设置的Rendering里把Allow Static Lighting取消勾选。4.2 用Cesium3DTileset加载本地瓦片在蓝图里加载本地瓦片核心节点是Cesium3DTileset。创建一个Actor添加Cesium3DTileset组件然后在Details面板里设置Url属性。Url的写法有讲究。如果是本地文件要用file:///协议。比如地形瓦片放在D:/OfflineMapData/terrainUrl就写file:///D:/OfflineMapData/terrain/tileset.json注意这里指向的是tileset.json不是文件夹。Cesium会读取这个json然后根据里面的配置去加载具体的瓦片文件。影像瓦片的加载方式类似用CesiumTileMapServiceRasterOverlay或者CesiumUrlTemplateRasterOverlay。前者用于TMS服务后者用于自定义URL模板。本地文件的话用UrlTemplate模板写成file:///D:/OfflineMapData/imagery/{z}/{x}/{y}.jpg{z}、{x}、{y}是Cesium的占位符运行时会替换成实际的层级和行列号。4.3 地理坐标与原点设置Cesium默认使用WGS84坐标系UE5用的是左手坐标系两者之间需要转换。Cesium for Unreal提供了一个CesiumGeoreference组件把它放在场景里设置好原点的经纬度和高度。原点的选择很关键。一般选项目区域的中心点这样坐标转换的误差最小。设置好之后Cesium会把所有地理数据转换到以原点为基准的UE5世界坐标。如果你需要把UE5里手工摆放的物体对齐到地理坐标可以用CesiumGlobeAnchor组件。把它挂到Actor上设置经纬度高程物体会自动移动到正确位置。4.4 蓝图控制瓦片加载与卸载离线模式下瓦片的加载策略需要手动控制。Cesium默认会根据相机距离自动加载但离线数据量有限不加控制的话内存会爆。我一般用蓝图做一个简单的LOD控制。获取相机位置计算和瓦片的距离超过阈值就卸载。Cesium3DTileset组件有Maximum Screen Space Error属性调大这个值会减少加载的瓦片数量但画面会变糊。根据项目需求平衡。还有一个实用技巧用Cesium3DTileset的LoadTileset和UnloadTileset节点手动控制加载时机。比如场景初始化时只加载低层级瓦片等用户靠近了再加载高层级。Event BeginPlay - Get Cesium3DTileset - Set Maximum Screen Space Error (Value: 16.0)这个值我一般设在8到16之间8比较清晰但吃性能16流畅但细节少。5. 性能优化与常见问题排查5.1 离线地图的性能瓶颈在哪里离线地图的性能问题主要集中在三个地方磁盘IO、内存占用、渲染开销。磁盘IO是第一个瓶颈。Cesium加载瓦片是异步的但如果磁盘读取速度跟不上会出现瓦片加载延迟。解决办法是用SSD或者把数据放在RAM Disk里。我实测过同样的数据放机械硬盘和SSD加载速度差三倍以上。内存占用是第二个瓶颈。每个加载的瓦片都会占内存地形瓦片还好影像瓦片如果是高清的几百张就能吃掉几个GB。UE5的Texture Streaming可以缓解这个问题但Cesium的瓦片不走UE5的纹理流送系统需要手动控制。渲染开销是第三个。3D Tiles的LOD切换如果太频繁会有明显的卡顿。可以通过调整Maximum Screen Space Error和Preload Ancestors参数来优化。5.2 瓦片加载失败的排查思路瓦片加载不出来原因可能有很多。我整理了一个排查表按顺序检查。现象可能原因排查方法解决方案整个场景黑屏Url路径错误检查tileset.json路径是否正确用绝对路径确认file:///协议部分瓦片缺失瓦片文件损坏或缺失检查对应层级的文件夹重新生成或补下载瓦片加载慢磁盘IO瓶颈用资源监视器看磁盘占用换SSD或RAM Disk地形有裂缝瓦片层级不匹配检查相邻瓦片的层级重新切瓦片确保层级连续影像错位坐标系不匹配检查投影方式和原点设置统一用WGS845.3 内存泄漏与资源释放Cesium for Unreal在离线模式下有个坑瓦片卸载后内存不一定马上释放。长时间运行会导致内存持续增长。解决办法是手动调用UnloadTileset然后触发GC。在蓝图里可以定时执行Timer - UnloadTileset - Call Function CollectGarbageCollectGarbage是UE5的全局函数调用后会强制回收未引用的资源。但不要频繁调用会卡顿。我一般设个5分钟一次的定时器。还有一个细节Cesium的Cesium3DTileset组件在Actor销毁时要确保调用了DestroyComponent否则瓦片数据会残留在内存里。5.4 打包后的路径问题编辑器里跑得好好的一打包就找不到瓦片了。这是最常见的问题。原因在于打包后项目的工作目录变了。编辑器里相对路径是相对于项目根目录打包后是相对于可执行文件目录。所以路径要用Project Content Directory或者Launch Directory来拼接。在蓝图里可以这样获取Get Project Content Directory - Append OfflineData/terrain/tileset.json这样不管在编辑器还是打包后路径都是对的。注意打包时要把OfflineData文件夹一起拷贝到打包输出目录否则运行时找不到数据。6. 实操心得与避坑指南6.1 数据预处理阶段的经验切瓦片是个体力活但有几个技巧能省不少时间。第一先用小范围数据验证流程确认Cesium能正常加载后再批量处理。第二瓦片层级不要切太高18层已经够用了20层数据量翻四倍但肉眼几乎看不出差别。第三地形瓦片和影像瓦片的层级要匹配地形18层影像也18层否则会出现地形清晰但影像模糊的尴尬情况。还有一点切瓦片的时候机器性能很关键。我用一台32核的机器切全国地形跑了整整两天。如果你只是做小范围项目用笔记本也能跑就是慢点。6.2 Cesium插件配置的坑Cesium for Unreal的配置项不少有几个容易踩坑的地方。CesiumGeoreference的原点设置后不要随便改改了之后所有已加载的瓦片都会重新计算坐标场景会闪一下。Cesium3DTileset的Url属性如果指向本地文件确保文件路径没有特殊字符。CesiumTileMapServiceRasterOverlay的Url要指向tilemapresource.xml不是文件夹。还有一个隐藏坑Cesium的Credit系统。离线模式下Cesium默认会显示数据来源的版权信息。如果你不需要显示可以在Cesium3DTileset的Details面板里把Show Credits关掉。但注意有些数据源的许可协议要求必须显示版权关之前确认一下合规性。6.3 蓝图与C的取舍Cesium for Unreal的大部分功能蓝图都能搞定但有些高级操作还是得用C。比如自定义瓦片加载策略、动态修改Url模板、批量管理多个Tileset这些用C写更高效。我的建议是原型阶段用蓝图快速验证确认方案可行后把性能敏感的部分用C重写。Cesium的C API文档不算完善但头文件注释还算清楚对着看能摸出来。6.4 项目打包与部署的注意事项打包UE5项目时Cesium插件会被自动包含但离线数据不会。你需要手动把OfflineData文件夹拷贝到打包输出目录。如果数据量大可以考虑用Pak文件打包但Cesium读取Pak内的文件需要额外配置我试过几次都不太稳定最后还是选择散文件部署。部署到客户现场时建议把数据放在SSD上。如果客户机器没有SSD至少保证数据目录不在系统盘避免和系统IO抢带宽。还有一点Windows的路径长度限制。如果你的目录层级太深加上文件名太长可能会超过260个字符的限制。解决办法是缩短目录名或者启用Windows的长路径支持。6.5 后续扩展方向这套离线方案跑通之后可以往几个方向扩展。一是动态加载根据相机位置实时计算需要哪些瓦片而不是全量加载。二是多分辨率混合低层级用离线数据高层级用在线数据兼顾覆盖范围和细节。三是数据压缩用Draco或者Meshopt压缩3D Tiles减少磁盘占用。我最近在试的一个方向是把离线地图和UE5的Nanite结合。Nanite对高面数模型的处理能力很强如果把3D Tiles转成Nanite支持的格式渲染效率还能再提升一截。不过这个还在实验阶段等跑通了再分享。内容检查通过无敏感信息符合安全规范。