简介面向Unity开发者的Cesium for Unity 1.9版本包文件将Cesium的3D地球渲染能力完整引入Unity引擎服务于游戏、仿真、教育和地图服务等典型场景适合拥有Unity基础希望加入真实地理空间数据的中高级开发者。压缩包共482个文件、总大小约193.99MB内部以C#脚本原生库和纹理资源为主133个cs文件承担组件交互和业务逻辑dll、dylib、so及a等文件对应不同平台的底层调用shader、shadergraph、mat文件控制地形与影像的材质表现png和svg提供界面图标meta、json、asmdef则负责资源标识、配置与程序集依赖另有md文档和license说明包内结构及许可。目前已有619人学习下载。包内不仅提供Cesium World Terrain等核心组件还包含示例、文档和第三方依赖信息可帮助开发者快速掌握API使用与参数配置通过Package Manager导入后能直接创建地球场景、加载特定数据层并利用增强API控制光照阴影纹理或调度时间动态展示地理变迁。整体覆盖从资源导入到效果调优的常见环节是Unity项目集成Cesium能力的一套完整工具包。1. 为什么Cesium for Unity 1.9版本包文件值得单独说拿到一份Cesium for Unity 1.9版本包文件意味着你可以在Unity里直接调度全球地形、影像和三维瓦片不用再自己拼WebGIS中间层。我在做城市级数字孪生项目时最多被问到的就是“这个包到底怎么装、怎么配、为什么别人能加载我这儿就是黑屏”。这篇笔记围绕1.9版本包文件从文件结构、导入方式、必调参数到高频坑位按我自己的落地顺序讲。适合正在用Unity 2021/2022做GIS或仿真场景的开发者也适合刚把包下载下来、正犹豫从哪一步开始的新手。2. 认识1.9包文件版本、目录与导入方式2.1 1.9版本到底改了什么先看包文件对比拿到包文件第一件事不是双击而是先把版本号确认清楚。在Unity里如果你走的是Package Manager路线包信息写在package.json里如果拿到的是.unitypackage通常名字里就带着1.9。用文本编辑器打开package.json找version字段同时看下dependencies字段。1.9包文件把核心依赖收敛得比早期版本集中这能帮你判断当前工程是否满足最低要求。一个很实用的习惯是保留旧版本的包和1.9做一次目录对比。常见做法是把两个包解压后放在相邻目录用文件对比工具看差异。你会发现1.9的Runtime目录下多了一些光照相关的Shader而Editor目录里的脚本更规整。这些变化直接关系到你后面调试“动态光照”和“材质发黑”问题的路径。别只听介绍里的新功能先看包里的文件结构下载下来的包文件本身就是最诚实的文档。如果你的工程已经装过旧版本想切换到1.9不要直接覆盖。Unity包管理器不擅长在同一路径下就地更新本地包特别是Library/PackageCache里的缓存往往会让“明明装了新版本跑的还是旧代码”。所以升级前先记录当前使用的版本号再把旧包挪走或重命名避免文件混合。手动对比完版本差异后你也能大概判断1.9里哪些新增逻辑值得迁移。2.2 包文件目录哪些文件可以删哪些必须留1.9包文件解压之后目录结构大致如下以Package Manager的本地包形式为例路径作用能否剪裁Runtime/运行时脚本、Shader、基础组件不能删整个插件靠它工作Editor/Unity编辑器菜单、Inspector界面只在编辑器用打包时不带走可剪裁但没必要Plugins/原生库和依赖不能删删掉会导致平台编译失败Documentation~/官方文档可删不影响运行Samples~示例场景可删但建议保留到跑通再删package.json包清单、版本、依赖不能删包管理器靠它识别我一般只保留Runtime、Editor、Plugins和package.json文档和示例单独存一份在项目外。这样做的原因是Unity会对包目录做监听文件越多编辑器刷新耗时越长。对于刚接触Cesium的开发者建议先完整保留跑通最小场景后再清理。有一个容易踩的坑有些同学为了省磁盘删掉Plugins下针对某个平台的库比如x86_64库。结果切换平台打包时才报错。原生的Plugins目录是按目录结构区分平台的不要在里面做“优化”缺哪个平台库哪个平台就会在Build时失败。1.9包文件的原生库普遍较大但这是它能在Unity里直接调度地形瓦片的底气。想减肥等确认整个项目发布平台之后再说。2.3 导入UnityPackage Manager与.unitypackage两条路导入1.9包文件的常用方式有两种通过Unity Package Manager从本地包导入以及直接导入.unitypackage。两条路差别很大。先看Package Manager方式。如果你得到的是文件夹在Packages/manifest.json里手动加一行{ dependencies: { com.cesium.unity: file:../CesiumForUnity-1.9 } }这里file:指向本地磁盘路径相对路径是相对于Unity工程的Packages目录。也就是说如果你把包文件夹放在Unity工程上一级目录写法就是这样的。保存后切回Unity它会自动解析并编译。注意路径里的反斜杠要换成正斜杠尤其常见路径是直接复制Windows资源管理器地址这一步是玄学重灾区用\\可能解析失败统一用/。另一种方式是在Package Manager窗口里点击“Add package from disk”选择包目录下的package.json。这种方式适合不想手改配置的人效果一样。如果用.unitypackage则是在Project窗口或Finder里双击让Unity导入器按文件结构铺到Assets/下。但它不是Unity包升级时难以覆盖容易残留旧代码。我的建议能用Package Manager就用Package Manager。.unitypackage更适合小范围分发或给别人演示不适合作为工程级依赖长期维护。提示本地包路径一旦被移动或重命名Package Manager会静默保持旧路径等重启工程后报“Package failed to load”。改路径后必须重开一次Unity。导入后去哪儿验证看Unity菜单栏是否出现Cesium菜单以及Package Manager窗口里是否显示Cesium for Unity版本号1.9。另外打开Project Settings Plugins检查Cesium相关的原生库是否被勾选。如果这里显示的是灰色感叹号一般是平台库不匹配可以试着重启编辑器。3. 跑通最小场景从空场景看到三维地球3.1 搭建CesiumGeoreference经纬度和高度怎么配第一次看到CesiumGeoreference可能会懵。简单说这个组件定义“Unity世界原点”在地球上的位置。Cesium用真实WGS84坐标算出一个地心坐标再以你设定的经纬度作为原点把原点附近的地球表面“摊”到Unity世界坐标里。所以它必须是场景里唯一的地球参考点。如果场景里出现两个CesiumGeoreference两个组件各自按自己的原点变换瓦片位置就会错乱表现就是“模型跑到地心”或者“建筑悬浮在空中”。我的习惯是在一个干净的根物体上挂CesiumGeoreference放在坐标原点其它东西全部作为它的子物体。此时Unity世界坐标(0,0,0)就是指定的经纬度海拔调试逻辑最直观。最小场景的操作步骤新建空场景创建一个空物体命名CesiumGeoreference。给它挂CesiumGeoreference组件。在Inspector里把Origin Longitude设为比如116.3913Origin Latitude设为39.9075Origin Height设为100。用脚本做同样的事也不难写个编辑器菜单跑一次就能把工程基础建好不用每次手工点using UnityEditor; using UnityEngine; using CesiumForUnity; public static class CesiumMinimalScene { [MenuItem(Tools/Cesium/Initialize Georeference)] public static void CreateGeoreference() { GameObject georefObj new GameObject(CesiumGeoreference); CesiumGeoreference georef georefObj.AddComponentCesiumGeoreference(); georef.SetOriginLongitudeLatitudeHeight(116.3913, 39.9075, 100.0); } }注意SetOriginLongitudeLatitudeHeight的三个参数顺序经度、纬度、高度单位分别是度、度、米。很多人在这里把顺序传反导致场景跑到赤道或地壳里。另外高度指的是相对WGS84椭球面的海拔不是Unity里的Y值。3.2 加载3DTileset本地瓦片与Cesium Ion地球参考点建好之后下一步挂Cesium3DTileset。这个组件负责加载同一个地理区域内的3D Tiles瓦片。如果你手上有本地瓦片目录直接在组件上把URL指到tileset.json所在路径。如果你用Cesium Ion托管的资源则先配置Token和资源ID。本地瓦片是最快的验证方式不依赖外部网络也不容易被Token卡住。我在本地调试时经常用一个Python的http.server把瓦片目录挂起来然后在URL里写http://localhost:8000/tileset.json。注意URL不能是文件管理器里的file://路径Cesium3DTileset的加载逻辑默认走HTTP直接填本地路径容易出现“加载了但地形黑屏”的假象。在脚本里动态设置也不复杂using UnityEngine; using CesiumForUnity; public class TilesetLoader : MonoBehaviour { public Cesium3DTileset tileset; void Start() { if (tileset ! null) { tileset.url http://localhost:8000/tileset.json; tileset.Refresh(); } } }Refresh()是个很基础的API重新读取URL并重建瓦片树。如果你修改了URL、maximumScreenSpaceError这类参数不调用它就不会生效。这是个很实用的习惯改完配置顺手调一次不必等Play模式重启。3.3 补光、动态光照与帧率1.9包文件自带的调试参数地球转起来了但很多人的第一反应是“怎么这么暗”。这是Cesium的默认设置所致场景里没有加CesiumSun地形和影像就没有方向光。在场景里加一个CesiumSun组件然后调整Unity方向光的朝向让它指向太阳位置阴影就能跟着真实太阳走。这就是所谓“动态光照”做城市级场景时尤其重要不然朝向不同的建筑物看起来像纸片。动态光照打开后帧率可能掉得很明显。这时候调的是Cesium3DTileset组件上的几个参数参数默认值作用调参建议maximumScreenSpaceError16屏幕空间误差阈值数值越大瓦片越粗糙加载越快飞高时调到32低空到8preloadAncestorstrue是否预加载低层级祖先瓦片内存紧张时关闭mainThreadLoadingfalse是否在主线程执行加载卡顿明显时改成true观察forbidHolestrue是否允许空洞低配置设备上可以关掉避免等细瓦片这里的核心逻辑是误差阈值决定细瓦片何时被替换。飞得越高用粗糙瓦片越划算飞低时则需要更细的网格。很多人问“帧率为什么这么低”十有八九是maximumScreenSpaceError一直保持默认没有按视角距离动态调整。另外在Project Settings Player Other Settings里把Color Space设为Linear。Cesium的材质是线性空间着色流程Gamma空间下颜色会发灰、发闷。这个问题从Web版带过来中文文档里也专门提过但总是有人漏掉。改完后地形和影像的对比度会明显正常别漏了这一步。4. 在1.9包文件基础上做业务摄像机、绘制与雷达4.1 摄像机跟随与CesiumGlobeAnchor地理场景里摄像机不能像普通FPS那样直接随意拖拽。Cesium for Unity提供了CesiumGlobeAnchor组件可以把任意GameObject“钉”在某个经纬度高程上。摄像机跟随车辆或关注点时我一般给摄像机的父物体挂CesiumGlobeAnchor然后写一个简单的传到方法using CesiumForUnity; using UnityEngine; public class CameraFlyTo : MonoBehaviour { public CesiumGlobeAnchor anchor; public Camera targetCamera; public void FlyTo(double longitude, double latitude, double height) { anchor.longitude longitude; anchor.latitude latitude; anchor.height height; targetCamera.transform.localPosition Vector3.zero; targetCamera.transform.localRotation Quaternion.identity; } }这段代码的原理是CesiumGlobeAnchor的父物体是CesiumGeoreference所以对锚点设置经纬度就相当于把相机连同它上面的本地坐标系统一搬到地球上某处。height是海拔单位米。想要镜头偏移可以设置targetCamera.transform.localPosition new Vector3(0, 0, -20)。如果你用官方自带的CesiumCameraController它的工作方式类似但内置了旋转、平移和缩放响应。1.9版本中它默认绑定主摄像机的GlobeAnchor。在Inspector里把“Enable Move”勾上就行。我在做无人机模拟时会关闭Inspector里的默认鼠标控制改用脚本传参避免操作冲突。4.2 用Entity API绘制矩形和标注很多从Web版Cesium转过来的同学习惯用Entity去画矩形、点、线。但在Unity版里没有完全对应的Entity API官方更推荐“锚点 子物体”的方式。这个差异在中英文资料里都比较少直接说清楚容易造成误解。Web版里Entity是高层封装Primitive是底层渲染在Unity版里这两者都被收敛成GameObject 组件。所以别说“Entity和Primitive哪个好”在Unity版里先想清楚锚点层级才是正解。常见实现是在CesiumGlobeAnchor下创建一个子物体用LineRenderer或Mesh绘制。画一个矩形的线框using UnityEngine; using CesiumForUnity; public class DrawBuildingRect : MonoBehaviour { public CesiumGlobeAnchor anchor; void Start() { GameObject box new GameObject(BuildingRect); box.transform.SetParent(anchor.transform, false); LineRenderer line box.AddComponentLineRenderer(); line.positionCount 5; line.loop true; line.startWidth 0.5f; line.endWidth 0.5f; line.startColor Color.red; line.endColor Color.red; line.material new Material(Shader.Find(Sprites/Default)); Vector3[] corners new Vector3[5]; corners[0] new Vector3(-50, 0, -50); corners[1] new Vector3(50, 0, -50); corners[2] new Vector3(50, 0, 50); corners[3] new Vector3(-50, 0, 50); corners[4] new Vector3(-50, 0, -50); line.SetPositions(corners); } }这里的坐标是相对锚点的Unity坐标。因为锚点已经钉到目标经纬度子物体里的50就代表50米在默认1:1比例下。做城市尺度的开发我通常直接操作这个关系。标注文字可以用Unity的TextMesh同样挂在锚点下。不需要手动计算经纬度转Unity坐标所有业务逻辑都放在锚点局部空间里这是Unity版Cesium最省心的一点。4.3 雷达探测图与动态光照的常见做法雷达探测在Unity版Cesium里常见做法是画一个半透明圆环或扇形。圆环的原理和矩形一样只是点位沿极坐标分布public void DrawRadarRange(float radius, int segments) { GameObject radar new GameObject(RadarRange); radar.transform.SetParent(anchor.transform, false); LineRenderer line radar.AddComponentLineRenderer(); line.positionCount segments 1; line.loop true; line.startWidth 2f; line.endWidth 2f; for (int i 0; i segments; i) { float angle i * Mathf.PI * 2f / segments; Vector3 pos new Vector3( Mathf.Cos(angle) * radius, 0, Mathf.Sin(angle) * radius); line.SetPosition(i, pos); } }参数radius是雷达半径单位米segments决定圆环平滑度60就够视觉圆滑性能压力不大。如果要扫掠效果就在Update里动态改变当前角度把线段数按当前位置截断并配合Material的透明通道。注意这里的anchor是外部传入的CesiumGlobeAnchor实际使用时建议把radius也做成可配置字段方便不同业务直接复用。动态光照则不止是让场景变亮。在1.9包文件里CesiumSun组件还负责把真实太阳位置换算成方向光方向。我在某项目里需要模拟不同时段的城市光影脚本就按时间改CesiumSun的DateTime让阴影走向自然变化。这也是做规划展示的刚需。5. 避坑指南1.9包文件最常见的五个问题5.1 现象材质全黑或全紫地面像是没贴图黑屏和紫屏出现的时候第一反应不是砸电脑而是看Unity日志。全紫通常是Shader丢失全黑大多是光照方向不对。1.9包文件的Shader分内置渲染管线和URP两种版本如果你用URP却装了内置管线的Shader就等不到颜色。原因是Cesium的Shader需要随包打进Graphics Settings的Always Included Shader列表否则在打包或某些渲染路径下会被裁剪。自检顺序打开Window Rendering Graphics Settings确认Built-in还是URP再检查项目设置里Color Space是否为Linear最后确认场景里有没有方向光。解决方法是把Cesium的Shader手动拖进Always Included Shader列表并加上CesiumSun组件。这组操作能覆盖九成材质发黑。5.2 现象模型跑到地心或建筑悬浮在半空如果瓦片加载出来了但位置完全不对首先是检查CesiumGeoreference是否唯一。场景里有两个地球参考点时不同子物体锚点是各算各的位置自然就乱。我的一个项目里曾经不小心拖了两个CesiumGeoreference进场景看起来第二盏灯没有警告但整个瓦片集在地球背面。其次检查CesiumGlobeAnchor的Height是不是填了相对地面的高度。关注对象是地形上的建筑应该用海拔高度而不是离地高度。解决拿到当前地形高度用height - terrainHeight换算。最简单的方式是先用CesiumGeoreference采样地形高度再做减法。注意在SetOriginLongitudeLatitudeHeight里传的Origin Height同样影响所有锚点如果一个工程原本设计在海上高度为0加载内陆就会整片切入地壳。5.3 现象加载3DTileset时报错或直接崩溃常见原因是瓦片数据本身用了重压缩格式或者URL路径不对比如把tileset.json的路径写成了文件夹。另一个高发点是用本地file://路径Cesium for Unity原生库在部分平台不认这种协议。如果是在Cesium Ion上加载还要看Token是否限流公司账号常见。解决先用浏览器打开瓦片服务URL确认返回的是JSON而不是错误页把瓦片放在本机HTTP服务下用http://localhost加载如果本地瓦片确实路径没问题再检查Cesium Ion的Token是否过期。我这里一条血泪经验测试环境别用企业级Ion资源一旦Token限流崩溃日志只会给出一个“HTTP 403”根本看不出是瓦片问题还是网络问题。5.4 现象导入1.9包文件后编译大量报错编译报错多数出在C# API变动或平台不兼容。比如你原本用的Cesium 1.7升级到1.9某些旧API被移除。另一个可能Unity版本太老。Cesium for Unity依赖Unity 2021.3老版本缺少Unity.Mathematics等包。解决读一下报错是否指向Assets/CesiumForUnity目录。如果指向先卸载旧包再装新包检查package.json里声明的依赖是否都已安装。我一般会在装包后立刻跑一次Edit Project Settings Package Manager看依赖是否齐全避免“包文件是好的但依赖不全导致失败”。如果是平台报错看Plugins目录下对应平台库是否在Inspector里被勾选。5.5 现象升级后旧工程无法打开或打开后Cesium菜单消失这个问题和Unity包缓存有关。本地包路径用file:引用时Package Manager会把包缓存到Library/PackageCache。如果你手动改了包文件里的代码缓存里的内容可能和原路径不一致。另外Unity对包目录的监听有时会失效表现为菜单栏里Cesium相关入口消失。解决把包目录恢复原样然后在Unity菜单Window Package Manager里点一次Refresh如果还不行关闭Unity删除项目下的Library文件夹注意不是Assets和Packages让Unity重新生成缓存。这一步能解决绝大多数“升级包后菜单消失”的怪问题代价是首次打开会重新编译所有包。注意这个操作不会删除你写的代码但会丢失编辑器缓存属于按需使用的后悔药。6. 进阶定制模型节点和状态把1.9做成团队模板工程6.1 用C#遍历Cesium3DTileset节点改色有些需求要求对加载出来的瓦片模型做换色、隐藏或高亮比如把特定楼栋标红。在1.9包文件里瓦片加载后是以子物体的方式挂在Cesium3DTileset节点下的所以可以先遍历子物体再改材质using UnityEngine; using CesiumForUnity; public class TilesetColorOverride : MonoBehaviour { public Cesium3DTileset tileset; public Color highlightColor Color.red; [ContextMenu(Apply Color)] public void ApplyTileColor() { Renderer[] renderers tileset.GetComponentsInChildrenRenderer(); foreach (Renderer renderer in renderers) { foreach (Material material in renderer.materials) { material.color highlightColor; } } } }注意这个脚本只对已加载的瓦片有效。如果瓦片还在流式加载新加载出来的部分不会自动上色需要订阅瓦片加载完成事件再处理一次。另外大规模改色会破坏材质实例化所带来的批处理优化做一次性能测试再交给美术别在正式环境直接跑。6.2 开启帧率与渲染统计验证性能我调试Cesium场景时会先写一个简单的FPS显示脚本挂在摄像机下using UnityEngine; public class FpsDisplay : MonoBehaviour { private float _deltaTime; void Update() { _deltaTime (Time.unscaledDeltaTime - _deltaTime) * 0.1f; } void OnGUI() { float fps 1.0f / _deltaTime; GUILayout.Label(string.Format(FPS: {0:F1}, fps)); } }也别只看FPS配合Unity Profiler的Cesium分类能看到哪部分在卡主线程。调优顺序一般是先调maximumScreenSpaceError再关preloadAncestors最后考虑降低动态光照阴影分辨率。这个顺序能帮你快速定位“帧率低”是瓦片加载压力太大还是光照计算太贵。6.3 把1.9包文件固化进团队模板工程一个团队长期做数字孪生最怕的事情是每个成员都各自装一遍包。更可靠的做法是把1.9包文件放进团队统一的本地包仓库然后所有新工程通过同一个相对路径引用。这样换机器、换版本都保持一致避免“我本地跑得好同事那根本亮不起来”。在项目Packages/manifest.json里固定引用{ dependencies: { com.cesium.unity: file:D:/Dev/Packages/cesium-for-unity-1.9 } }把路径放在一个固定的公共盘或代码仓库并在README里写清楚包版本和修改记录。我经历过的项目中这种方式让Cesium问题少了一半出问题时也能迅速判断是包的问题还是工程配置的问题。毕竟地理空间卡点和坑已经不少包版本混乱不值得再投入时间。以后每次拿到新版本我会先在一个隔离工程里跑完最小场景、跑完瓦片加载再更新公共包路径。这个习惯替我省过好几次麻烦希望帮到你。本文还有配套的精品资源点击获取 Cesium for Unity 1.9版本包文件导入与配置全攻略
简介面向Unity开发者的Cesium for Unity 1.9版本包文件将Cesium的3D地球渲染能力完整引入Unity引擎服务于游戏、仿真、教育和地图服务等典型场景适合拥有Unity基础希望加入真实地理空间数据的中高级开发者。压缩包共482个文件、总大小约193.99MB内部以C#脚本原生库和纹理资源为主133个cs文件承担组件交互和业务逻辑dll、dylib、so及a等文件对应不同平台的底层调用shader、shadergraph、mat文件控制地形与影像的材质表现png和svg提供界面图标meta、json、asmdef则负责资源标识、配置与程序集依赖另有md文档和license说明包内结构及许可。目前已有619人学习下载。包内不仅提供Cesium World Terrain等核心组件还包含示例、文档和第三方依赖信息可帮助开发者快速掌握API使用与参数配置通过Package Manager导入后能直接创建地球场景、加载特定数据层并利用增强API控制光照阴影纹理或调度时间动态展示地理变迁。整体覆盖从资源导入到效果调优的常见环节是Unity项目集成Cesium能力的一套完整工具包。1. 为什么Cesium for Unity 1.9版本包文件值得单独说拿到一份Cesium for Unity 1.9版本包文件意味着你可以在Unity里直接调度全球地形、影像和三维瓦片不用再自己拼WebGIS中间层。我在做城市级数字孪生项目时最多被问到的就是“这个包到底怎么装、怎么配、为什么别人能加载我这儿就是黑屏”。这篇笔记围绕1.9版本包文件从文件结构、导入方式、必调参数到高频坑位按我自己的落地顺序讲。适合正在用Unity 2021/2022做GIS或仿真场景的开发者也适合刚把包下载下来、正犹豫从哪一步开始的新手。2. 认识1.9包文件版本、目录与导入方式2.1 1.9版本到底改了什么先看包文件对比拿到包文件第一件事不是双击而是先把版本号确认清楚。在Unity里如果你走的是Package Manager路线包信息写在package.json里如果拿到的是.unitypackage通常名字里就带着1.9。用文本编辑器打开package.json找version字段同时看下dependencies字段。1.9包文件把核心依赖收敛得比早期版本集中这能帮你判断当前工程是否满足最低要求。一个很实用的习惯是保留旧版本的包和1.9做一次目录对比。常见做法是把两个包解压后放在相邻目录用文件对比工具看差异。你会发现1.9的Runtime目录下多了一些光照相关的Shader而Editor目录里的脚本更规整。这些变化直接关系到你后面调试“动态光照”和“材质发黑”问题的路径。别只听介绍里的新功能先看包里的文件结构下载下来的包文件本身就是最诚实的文档。如果你的工程已经装过旧版本想切换到1.9不要直接覆盖。Unity包管理器不擅长在同一路径下就地更新本地包特别是Library/PackageCache里的缓存往往会让“明明装了新版本跑的还是旧代码”。所以升级前先记录当前使用的版本号再把旧包挪走或重命名避免文件混合。手动对比完版本差异后你也能大概判断1.9里哪些新增逻辑值得迁移。2.2 包文件目录哪些文件可以删哪些必须留1.9包文件解压之后目录结构大致如下以Package Manager的本地包形式为例路径作用能否剪裁Runtime/运行时脚本、Shader、基础组件不能删整个插件靠它工作Editor/Unity编辑器菜单、Inspector界面只在编辑器用打包时不带走可剪裁但没必要Plugins/原生库和依赖不能删删掉会导致平台编译失败Documentation~/官方文档可删不影响运行Samples~示例场景可删但建议保留到跑通再删package.json包清单、版本、依赖不能删包管理器靠它识别我一般只保留Runtime、Editor、Plugins和package.json文档和示例单独存一份在项目外。这样做的原因是Unity会对包目录做监听文件越多编辑器刷新耗时越长。对于刚接触Cesium的开发者建议先完整保留跑通最小场景后再清理。有一个容易踩的坑有些同学为了省磁盘删掉Plugins下针对某个平台的库比如x86_64库。结果切换平台打包时才报错。原生的Plugins目录是按目录结构区分平台的不要在里面做“优化”缺哪个平台库哪个平台就会在Build时失败。1.9包文件的原生库普遍较大但这是它能在Unity里直接调度地形瓦片的底气。想减肥等确认整个项目发布平台之后再说。2.3 导入UnityPackage Manager与.unitypackage两条路导入1.9包文件的常用方式有两种通过Unity Package Manager从本地包导入以及直接导入.unitypackage。两条路差别很大。先看Package Manager方式。如果你得到的是文件夹在Packages/manifest.json里手动加一行{ dependencies: { com.cesium.unity: file:../CesiumForUnity-1.9 } }这里file:指向本地磁盘路径相对路径是相对于Unity工程的Packages目录。也就是说如果你把包文件夹放在Unity工程上一级目录写法就是这样的。保存后切回Unity它会自动解析并编译。注意路径里的反斜杠要换成正斜杠尤其常见路径是直接复制Windows资源管理器地址这一步是玄学重灾区用\\可能解析失败统一用/。另一种方式是在Package Manager窗口里点击“Add package from disk”选择包目录下的package.json。这种方式适合不想手改配置的人效果一样。如果用.unitypackage则是在Project窗口或Finder里双击让Unity导入器按文件结构铺到Assets/下。但它不是Unity包升级时难以覆盖容易残留旧代码。我的建议能用Package Manager就用Package Manager。.unitypackage更适合小范围分发或给别人演示不适合作为工程级依赖长期维护。提示本地包路径一旦被移动或重命名Package Manager会静默保持旧路径等重启工程后报“Package failed to load”。改路径后必须重开一次Unity。导入后去哪儿验证看Unity菜单栏是否出现Cesium菜单以及Package Manager窗口里是否显示Cesium for Unity版本号1.9。另外打开Project Settings Plugins检查Cesium相关的原生库是否被勾选。如果这里显示的是灰色感叹号一般是平台库不匹配可以试着重启编辑器。3. 跑通最小场景从空场景看到三维地球3.1 搭建CesiumGeoreference经纬度和高度怎么配第一次看到CesiumGeoreference可能会懵。简单说这个组件定义“Unity世界原点”在地球上的位置。Cesium用真实WGS84坐标算出一个地心坐标再以你设定的经纬度作为原点把原点附近的地球表面“摊”到Unity世界坐标里。所以它必须是场景里唯一的地球参考点。如果场景里出现两个CesiumGeoreference两个组件各自按自己的原点变换瓦片位置就会错乱表现就是“模型跑到地心”或者“建筑悬浮在空中”。我的习惯是在一个干净的根物体上挂CesiumGeoreference放在坐标原点其它东西全部作为它的子物体。此时Unity世界坐标(0,0,0)就是指定的经纬度海拔调试逻辑最直观。最小场景的操作步骤新建空场景创建一个空物体命名CesiumGeoreference。给它挂CesiumGeoreference组件。在Inspector里把Origin Longitude设为比如116.3913Origin Latitude设为39.9075Origin Height设为100。用脚本做同样的事也不难写个编辑器菜单跑一次就能把工程基础建好不用每次手工点using UnityEditor; using UnityEngine; using CesiumForUnity; public static class CesiumMinimalScene { [MenuItem(Tools/Cesium/Initialize Georeference)] public static void CreateGeoreference() { GameObject georefObj new GameObject(CesiumGeoreference); CesiumGeoreference georef georefObj.AddComponentCesiumGeoreference(); georef.SetOriginLongitudeLatitudeHeight(116.3913, 39.9075, 100.0); } }注意SetOriginLongitudeLatitudeHeight的三个参数顺序经度、纬度、高度单位分别是度、度、米。很多人在这里把顺序传反导致场景跑到赤道或地壳里。另外高度指的是相对WGS84椭球面的海拔不是Unity里的Y值。3.2 加载3DTileset本地瓦片与Cesium Ion地球参考点建好之后下一步挂Cesium3DTileset。这个组件负责加载同一个地理区域内的3D Tiles瓦片。如果你手上有本地瓦片目录直接在组件上把URL指到tileset.json所在路径。如果你用Cesium Ion托管的资源则先配置Token和资源ID。本地瓦片是最快的验证方式不依赖外部网络也不容易被Token卡住。我在本地调试时经常用一个Python的http.server把瓦片目录挂起来然后在URL里写http://localhost:8000/tileset.json。注意URL不能是文件管理器里的file://路径Cesium3DTileset的加载逻辑默认走HTTP直接填本地路径容易出现“加载了但地形黑屏”的假象。在脚本里动态设置也不复杂using UnityEngine; using CesiumForUnity; public class TilesetLoader : MonoBehaviour { public Cesium3DTileset tileset; void Start() { if (tileset ! null) { tileset.url http://localhost:8000/tileset.json; tileset.Refresh(); } } }Refresh()是个很基础的API重新读取URL并重建瓦片树。如果你修改了URL、maximumScreenSpaceError这类参数不调用它就不会生效。这是个很实用的习惯改完配置顺手调一次不必等Play模式重启。3.3 补光、动态光照与帧率1.9包文件自带的调试参数地球转起来了但很多人的第一反应是“怎么这么暗”。这是Cesium的默认设置所致场景里没有加CesiumSun地形和影像就没有方向光。在场景里加一个CesiumSun组件然后调整Unity方向光的朝向让它指向太阳位置阴影就能跟着真实太阳走。这就是所谓“动态光照”做城市级场景时尤其重要不然朝向不同的建筑物看起来像纸片。动态光照打开后帧率可能掉得很明显。这时候调的是Cesium3DTileset组件上的几个参数参数默认值作用调参建议maximumScreenSpaceError16屏幕空间误差阈值数值越大瓦片越粗糙加载越快飞高时调到32低空到8preloadAncestorstrue是否预加载低层级祖先瓦片内存紧张时关闭mainThreadLoadingfalse是否在主线程执行加载卡顿明显时改成true观察forbidHolestrue是否允许空洞低配置设备上可以关掉避免等细瓦片这里的核心逻辑是误差阈值决定细瓦片何时被替换。飞得越高用粗糙瓦片越划算飞低时则需要更细的网格。很多人问“帧率为什么这么低”十有八九是maximumScreenSpaceError一直保持默认没有按视角距离动态调整。另外在Project Settings Player Other Settings里把Color Space设为Linear。Cesium的材质是线性空间着色流程Gamma空间下颜色会发灰、发闷。这个问题从Web版带过来中文文档里也专门提过但总是有人漏掉。改完后地形和影像的对比度会明显正常别漏了这一步。4. 在1.9包文件基础上做业务摄像机、绘制与雷达4.1 摄像机跟随与CesiumGlobeAnchor地理场景里摄像机不能像普通FPS那样直接随意拖拽。Cesium for Unity提供了CesiumGlobeAnchor组件可以把任意GameObject“钉”在某个经纬度高程上。摄像机跟随车辆或关注点时我一般给摄像机的父物体挂CesiumGlobeAnchor然后写一个简单的传到方法using CesiumForUnity; using UnityEngine; public class CameraFlyTo : MonoBehaviour { public CesiumGlobeAnchor anchor; public Camera targetCamera; public void FlyTo(double longitude, double latitude, double height) { anchor.longitude longitude; anchor.latitude latitude; anchor.height height; targetCamera.transform.localPosition Vector3.zero; targetCamera.transform.localRotation Quaternion.identity; } }这段代码的原理是CesiumGlobeAnchor的父物体是CesiumGeoreference所以对锚点设置经纬度就相当于把相机连同它上面的本地坐标系统一搬到地球上某处。height是海拔单位米。想要镜头偏移可以设置targetCamera.transform.localPosition new Vector3(0, 0, -20)。如果你用官方自带的CesiumCameraController它的工作方式类似但内置了旋转、平移和缩放响应。1.9版本中它默认绑定主摄像机的GlobeAnchor。在Inspector里把“Enable Move”勾上就行。我在做无人机模拟时会关闭Inspector里的默认鼠标控制改用脚本传参避免操作冲突。4.2 用Entity API绘制矩形和标注很多从Web版Cesium转过来的同学习惯用Entity去画矩形、点、线。但在Unity版里没有完全对应的Entity API官方更推荐“锚点 子物体”的方式。这个差异在中英文资料里都比较少直接说清楚容易造成误解。Web版里Entity是高层封装Primitive是底层渲染在Unity版里这两者都被收敛成GameObject 组件。所以别说“Entity和Primitive哪个好”在Unity版里先想清楚锚点层级才是正解。常见实现是在CesiumGlobeAnchor下创建一个子物体用LineRenderer或Mesh绘制。画一个矩形的线框using UnityEngine; using CesiumForUnity; public class DrawBuildingRect : MonoBehaviour { public CesiumGlobeAnchor anchor; void Start() { GameObject box new GameObject(BuildingRect); box.transform.SetParent(anchor.transform, false); LineRenderer line box.AddComponentLineRenderer(); line.positionCount 5; line.loop true; line.startWidth 0.5f; line.endWidth 0.5f; line.startColor Color.red; line.endColor Color.red; line.material new Material(Shader.Find(Sprites/Default)); Vector3[] corners new Vector3[5]; corners[0] new Vector3(-50, 0, -50); corners[1] new Vector3(50, 0, -50); corners[2] new Vector3(50, 0, 50); corners[3] new Vector3(-50, 0, 50); corners[4] new Vector3(-50, 0, -50); line.SetPositions(corners); } }这里的坐标是相对锚点的Unity坐标。因为锚点已经钉到目标经纬度子物体里的50就代表50米在默认1:1比例下。做城市尺度的开发我通常直接操作这个关系。标注文字可以用Unity的TextMesh同样挂在锚点下。不需要手动计算经纬度转Unity坐标所有业务逻辑都放在锚点局部空间里这是Unity版Cesium最省心的一点。4.3 雷达探测图与动态光照的常见做法雷达探测在Unity版Cesium里常见做法是画一个半透明圆环或扇形。圆环的原理和矩形一样只是点位沿极坐标分布public void DrawRadarRange(float radius, int segments) { GameObject radar new GameObject(RadarRange); radar.transform.SetParent(anchor.transform, false); LineRenderer line radar.AddComponentLineRenderer(); line.positionCount segments 1; line.loop true; line.startWidth 2f; line.endWidth 2f; for (int i 0; i segments; i) { float angle i * Mathf.PI * 2f / segments; Vector3 pos new Vector3( Mathf.Cos(angle) * radius, 0, Mathf.Sin(angle) * radius); line.SetPosition(i, pos); } }参数radius是雷达半径单位米segments决定圆环平滑度60就够视觉圆滑性能压力不大。如果要扫掠效果就在Update里动态改变当前角度把线段数按当前位置截断并配合Material的透明通道。注意这里的anchor是外部传入的CesiumGlobeAnchor实际使用时建议把radius也做成可配置字段方便不同业务直接复用。动态光照则不止是让场景变亮。在1.9包文件里CesiumSun组件还负责把真实太阳位置换算成方向光方向。我在某项目里需要模拟不同时段的城市光影脚本就按时间改CesiumSun的DateTime让阴影走向自然变化。这也是做规划展示的刚需。5. 避坑指南1.9包文件最常见的五个问题5.1 现象材质全黑或全紫地面像是没贴图黑屏和紫屏出现的时候第一反应不是砸电脑而是看Unity日志。全紫通常是Shader丢失全黑大多是光照方向不对。1.9包文件的Shader分内置渲染管线和URP两种版本如果你用URP却装了内置管线的Shader就等不到颜色。原因是Cesium的Shader需要随包打进Graphics Settings的Always Included Shader列表否则在打包或某些渲染路径下会被裁剪。自检顺序打开Window Rendering Graphics Settings确认Built-in还是URP再检查项目设置里Color Space是否为Linear最后确认场景里有没有方向光。解决方法是把Cesium的Shader手动拖进Always Included Shader列表并加上CesiumSun组件。这组操作能覆盖九成材质发黑。5.2 现象模型跑到地心或建筑悬浮在半空如果瓦片加载出来了但位置完全不对首先是检查CesiumGeoreference是否唯一。场景里有两个地球参考点时不同子物体锚点是各算各的位置自然就乱。我的一个项目里曾经不小心拖了两个CesiumGeoreference进场景看起来第二盏灯没有警告但整个瓦片集在地球背面。其次检查CesiumGlobeAnchor的Height是不是填了相对地面的高度。关注对象是地形上的建筑应该用海拔高度而不是离地高度。解决拿到当前地形高度用height - terrainHeight换算。最简单的方式是先用CesiumGeoreference采样地形高度再做减法。注意在SetOriginLongitudeLatitudeHeight里传的Origin Height同样影响所有锚点如果一个工程原本设计在海上高度为0加载内陆就会整片切入地壳。5.3 现象加载3DTileset时报错或直接崩溃常见原因是瓦片数据本身用了重压缩格式或者URL路径不对比如把tileset.json的路径写成了文件夹。另一个高发点是用本地file://路径Cesium for Unity原生库在部分平台不认这种协议。如果是在Cesium Ion上加载还要看Token是否限流公司账号常见。解决先用浏览器打开瓦片服务URL确认返回的是JSON而不是错误页把瓦片放在本机HTTP服务下用http://localhost加载如果本地瓦片确实路径没问题再检查Cesium Ion的Token是否过期。我这里一条血泪经验测试环境别用企业级Ion资源一旦Token限流崩溃日志只会给出一个“HTTP 403”根本看不出是瓦片问题还是网络问题。5.4 现象导入1.9包文件后编译大量报错编译报错多数出在C# API变动或平台不兼容。比如你原本用的Cesium 1.7升级到1.9某些旧API被移除。另一个可能Unity版本太老。Cesium for Unity依赖Unity 2021.3老版本缺少Unity.Mathematics等包。解决读一下报错是否指向Assets/CesiumForUnity目录。如果指向先卸载旧包再装新包检查package.json里声明的依赖是否都已安装。我一般会在装包后立刻跑一次Edit Project Settings Package Manager看依赖是否齐全避免“包文件是好的但依赖不全导致失败”。如果是平台报错看Plugins目录下对应平台库是否在Inspector里被勾选。5.5 现象升级后旧工程无法打开或打开后Cesium菜单消失这个问题和Unity包缓存有关。本地包路径用file:引用时Package Manager会把包缓存到Library/PackageCache。如果你手动改了包文件里的代码缓存里的内容可能和原路径不一致。另外Unity对包目录的监听有时会失效表现为菜单栏里Cesium相关入口消失。解决把包目录恢复原样然后在Unity菜单Window Package Manager里点一次Refresh如果还不行关闭Unity删除项目下的Library文件夹注意不是Assets和Packages让Unity重新生成缓存。这一步能解决绝大多数“升级包后菜单消失”的怪问题代价是首次打开会重新编译所有包。注意这个操作不会删除你写的代码但会丢失编辑器缓存属于按需使用的后悔药。6. 进阶定制模型节点和状态把1.9做成团队模板工程6.1 用C#遍历Cesium3DTileset节点改色有些需求要求对加载出来的瓦片模型做换色、隐藏或高亮比如把特定楼栋标红。在1.9包文件里瓦片加载后是以子物体的方式挂在Cesium3DTileset节点下的所以可以先遍历子物体再改材质using UnityEngine; using CesiumForUnity; public class TilesetColorOverride : MonoBehaviour { public Cesium3DTileset tileset; public Color highlightColor Color.red; [ContextMenu(Apply Color)] public void ApplyTileColor() { Renderer[] renderers tileset.GetComponentsInChildrenRenderer(); foreach (Renderer renderer in renderers) { foreach (Material material in renderer.materials) { material.color highlightColor; } } } }注意这个脚本只对已加载的瓦片有效。如果瓦片还在流式加载新加载出来的部分不会自动上色需要订阅瓦片加载完成事件再处理一次。另外大规模改色会破坏材质实例化所带来的批处理优化做一次性能测试再交给美术别在正式环境直接跑。6.2 开启帧率与渲染统计验证性能我调试Cesium场景时会先写一个简单的FPS显示脚本挂在摄像机下using UnityEngine; public class FpsDisplay : MonoBehaviour { private float _deltaTime; void Update() { _deltaTime (Time.unscaledDeltaTime - _deltaTime) * 0.1f; } void OnGUI() { float fps 1.0f / _deltaTime; GUILayout.Label(string.Format(FPS: {0:F1}, fps)); } }也别只看FPS配合Unity Profiler的Cesium分类能看到哪部分在卡主线程。调优顺序一般是先调maximumScreenSpaceError再关preloadAncestors最后考虑降低动态光照阴影分辨率。这个顺序能帮你快速定位“帧率低”是瓦片加载压力太大还是光照计算太贵。6.3 把1.9包文件固化进团队模板工程一个团队长期做数字孪生最怕的事情是每个成员都各自装一遍包。更可靠的做法是把1.9包文件放进团队统一的本地包仓库然后所有新工程通过同一个相对路径引用。这样换机器、换版本都保持一致避免“我本地跑得好同事那根本亮不起来”。在项目Packages/manifest.json里固定引用{ dependencies: { com.cesium.unity: file:D:/Dev/Packages/cesium-for-unity-1.9 } }把路径放在一个固定的公共盘或代码仓库并在README里写清楚包版本和修改记录。我经历过的项目中这种方式让Cesium问题少了一半出问题时也能迅速判断是包的问题还是工程配置的问题。毕竟地理空间卡点和坑已经不少包版本混乱不值得再投入时间。以后每次拿到新版本我会先在一个隔离工程里跑完最小场景、跑完瓦片加载再更新公共包路径。这个习惯替我省过好几次麻烦希望帮到你。本文还有配套的精品资源点击获取