做数字孪生项目的朋友应该都遇到过这个场景领导丢过来一套超图SuperMapiServer发布的三维服务地址让你在Unity里把场景拉起来还要能叠加业务数据、能查询、能联动。很多人第一反应是让建模同事导一份FBX到Unity里手工摆放结果模型一更新Unity里全部重新对齐坐标一偏就是半天最后项目延期。其实Unity接入超图在线服务这件事远没有想象中那么玄乎。核心就三件事弄清楚iServer上发布了什么类型的服务、用对Unity端对应的加载组件或接口、调通鉴权和坐标系。这篇文章我按实际项目踩坑的顺序把Unity接入超图在线服务的完整流程拆开讲一遍从服务类型识别、SDK配置到三类典型在线服务的落地代码再到线上项目的性能优化全部写给正在做UnityGIS集成的开发者。1. 在线服务接入前先搞懂超图服务的类型和工作流1.1 超图桌面端与iServer之间的服务发布链路接入在线服务之前最容易被忽略的是理解超图这套体系里“数据从哪来、发布成什么、Unity怎么消费”。SuperMap的数据生产通常在SuperMap iDesktop桌面端完成把倾斜摄影、BIM模型、点云、地形栅格等数据整理成工作空间再配好坐标系和缓存。然后通过iServer发布服务工作空间对外提供HTTP/HTTPS接口。Unity端拿到的是一个URL而不是一堆散落的模型文件。这条链路决定了在线服务的价值数据更新在服务端直接完成Unity客户端只要重启场景或刷新图层就能看到最新数据。我接手过不少项目前期用FBX导出方式做原型数据一更新就崩溃切到在线服务后甲方在iDesktop里修模型客户端重新加载S3M图层就同步了效率完全不在一个量级。所以这篇文章所有的方案都会围绕“服务端发布-客户端消费”这条主线展开。1.2 在线服务的三种典型形态三维服务、二维地图服务与数据服务在Unity里接超图在线服务要先搞清iServer上到底有哪几种服务可以接。服务类型REST路径特征Unity里的典型用途加载方式三维服务S3M/Scene/iserver/services/3D-xxx/rest/realspace数字孪生主场景、倾斜摄影、BIM模型SuperMap Unity SDK的SceneControl与LayerFace组件二维地图服务Map/iserver/services/map-xxx/rest/maps/xxx底图叠加、业务图层叠加、栅格瓦片UnityWebRequest按瓦片拉图或用SDK的MapControlREST数据服务/iserver/services/data-xxx/rest/data要素查询、属性过滤、空间分析联动UnityWebRequest发POST请求解析JSON三维服务是数字孪生主场景一般用SDK组件加载二维地图服务适合做整体地理底图比如全国路网、行政区划数据服务则是在已加载的三维场景上做业务交互比如点击建筑查产权信息、按字段过滤设备点。搞清楚这三类服务后面接什么都顺。1.3 为什么推荐在线加载而不是直接导入模型很多人有个疑问既然Unity里也能放模型为什么非要接在线服务我从交付角度说几个实际对比。直接导入模型的工作流是“数据生产-导出FBX/OBJ-Unity手工摆放-锁定相对坐标”听着简单但真实项目里模型动不动就是几个GB的倾斜摄影Unity直接导入轻则卡成PPT重则内存爆掉。在线服务走的是S3M格式的流式加载客户端按需请求当前视锥范围内的瓦片数据加载速度和显存占用比全部导入低一个量级。还有一个被忽视的点坐标基准。超图数据通常是CGCS2000或者Web Mercator投影坐标系直接导入Unity的模型常常跑到十万八千里外而通过SDK加载在线服务SDK已经帮你处理好了投影坐标到Unity世界坐标的换算。省掉的不只是写转换代码的时间还有排查模型跑飞的通宵。2. 环境准备Unity版本、SDK配置与网络探测2.1 环境与版本选型Unity版本、SuperMap SDK与配套资源以我常用的SuperMap Unity SDK适用于Unity 2019.4 LTS或2020.3 LTS为例这两个版本是我在多个项目里验证过最稳定的组合。新版本Unity2021.3也能跑但有时遇到渲染管线兼容性的小问题建议生产环境先锁LTS版本没必要追新。SDK从超图官网申请试用版或联系商务获取正式版。解压后你会发现里面有几个关键目录Plugins原生插件包含SuperMap内核的C库、ScriptsC#封装层、Scenes官方示例场景。导入Unity时建议只导入SDK的Unity Package不要手动拷贝DLL文件否则容易漏依赖。C#脚本层面SDK的核心命名空间包括using SuperMap.Data; // 数据模型、坐标系、数据集相关 using SuperMap.UI; // SceneControl、MapControl等UI控件 using SuperMap.Realspace; // 三维场景、图层、S3M相关2.2 导入SDK并跑通第一个Demo场景导入完成后先别急着写代码把官方提供的示例场景跑通一次这一步能帮你快速验证环境和许可。在Unity中打开SDK自带的Demo场景通常是SuperMap_Start或Realspace_Test场景场景里已经放置了一个SceneControl游戏对象。在SceneControl的Inspector面板中找到Is Server选项勾选后填入你拿到的三维服务地址。点击运行如果场景里出现了地形或模型说明SDK基础链路没问题。如果提示“Invalid License”或“许可无效”检查Unity的Plugins目录下是否有SuperMap.License相关文件可能需要在系统里先运行一次SDK目录下的许可工具SuperMapLicenseManager进行激活。我建议不要在原始Demo场景上直接改而是复制一份场景改名比如Scene_OnlineDemo保留原始文件作为对照。后续加图层、改路径都在复制场景里做出问题了随时回滚。注意SDK的许可分为试用许可和正式许可试用许可会有水印或时长限制。商用项目务必提前确认许可模式否则压测阶段突然弹许可过期提示现场会非常尴尬。2.3 动手之前先做四项网络与配置检查接入在线服务最大的坑往往出现在第一步服务地址根本访问不到。我整理了一个接入前三分钟自查清单每一条我都踩过实地检查服务URL是否在浏览器里能打开。比如三维服务的根地址是http://服务器IP:8090/iserver/services/3D-XXX/rest/realspace在浏览器打开能看到XML格式的服务描述才说明服务正常。检查端口是否开通。iServer默认端口是8090Unity开发机到服务器之间如果隔了防火墙先用telnet 服务器IP 8090测试端口连通性本地通了再谈SDK加载。检查许可。在浏览器里打开iServer首页看服务列表是否能展开如果某些服务灰色显示大概率是服务端许可中该模块未授权比如三维服务需要“三维”许可模块。检查坐标系。拿到服务地址后通过REST API的/rest/realspace描述信息确认坐标系编码。Unity里加载三维服务时SceneControl里的坐标系设置要和服务端一致否则出现整片场景偏移。3. 核心实操Unity加载超图三类在线服务的完整步骤3.1 加载三维缓存服务S3M作为数字孪生主场景多数数字孪生项目的核心场景就是三维服务里面的数据包括倾斜摄影、BIM、点云等。用SDK加载的流程分三步放置控件、填服务地址、设置坐标。下面是核心代码using SuperMap.Data; using SuperMap.UI; using SuperMap.Realspace; using UnityEngine; public class OnlineSceneLoader : MonoBehaviour { public SceneControl sceneControl; void Start() { // 1. 清空当前场景避免残留图层干扰 sceneControl.Scene.Clear(); // 2. 创建三维图层并指定远程服务地址 Layer3D layer sceneControl.Scene.Layers.Add( OnlineScene, // 图层名称可自定义 Layer3DType.S3M, // 图层类型加载超图三维切片服务 http://服务器IP:8090/iserver/services/3D-XXX/rest/realspace ); // 3. 调整观察相机到目标区域 sceneControl.Scene.FlyingOperator.FlyTo( new Point3D(12684732.12, 2559358.56, 120), // 目标点注意这里的坐标是投影坐标不是经纬度 500.0, // 距离地面高度 45.0, // 俯仰角45度比较自然 0.0 // 方向角 ); } }这段代码里有两个容易被新手忽略的细节。第一个是Layer3DType.S3M这个枚举值指明当前加载的是超图的服务端缓存格式而不是本地S3M数据文件两者虽然类型枚举相同但数据来源路径的解析逻辑完全不一样。第二个是FlyTo里使用的坐标。如果服务端坐标系是Web MercatorEPSG:3857这里的坐标就应该填Web Mercator坐标大概是12800000、2560000这个量级而不是经纬度。很多人在这一步用经纬度去飞结果镜头飞到非洲去了。3.2 加载REST地图服务作为坐标底图在实际项目中三维场景常常需要叠加一张二维底图作为地理位置的参照比如路网、行政区划、河流水系。超图iServer发布的REST地图服务可以在Unity中通过两种方式加载一是用SDK的MapControl组件二是通过UnityWebRequest拉取服务端瓦片再作为贴图贴到Unity的平面上。我用过比较稳定的是第二种方式原因在于它不依赖SDK里二维地图的许可模块而且可以随时替换瓦片URL模板灵活度更高。超图REST地图服务支持标准的XYZ路径模板请求地址通常长这样http://服务器IP:8090/iserver/services/map-XXX/rest/maps/底图名称/tilex/{x}/tiley/{y}/tilez/{z}这里{x}、{y}、{z}对应瓦片行列号和缩放级别。在Unity里写一个瓦片加载器核心逻辑是加载中心点对应的瓦片然后持续填充周边瓦片using System.Collections; using UnityEngine; using UnityEngine.Networking; public class TileMapLoader : MonoBehaviour { public string tileUrlTemplate http://服务器IP:8090/iserver/services/map-XXX/rest/maps/底图名称/tilex/{x}/tiley/{y}/tilez/{z}; public int zoomLevel 10; public GameObject tilePlanePrefab; // 一个平面细分网格用于显示瓦片贴图 IEnumerator LoadTile(int x, int y, int z) { string url tileUrlTemplate .Replace({x}, x.ToString()) .Replace({y}, y.ToString()) .Replace({z}, z.ToString()); using (UnityWebRequest request UnityWebRequestTexture.GetTexture(url)) { yield return request.SendWebRequest(); if (request.result UnityWebRequest.Result.Success) { Texture2D tex DownloadHandlerTexture.GetContent(request); GameObject plane Instantiate(tilePlanePrefab, transform); plane.GetComponentRenderer().material.mainTexture tex; // 根据瓦片行列号计算平面位置换算方式取决于投影规则 } else { Debug.LogError(瓦片加载失败: request.error); } } } }这里有几个关键点一是瓦片地址里的底图名称必须是iServer上发布的服务名不是工作空间名二是{z}缩放级别建议从服务端的默认比例尺范围里选超出范围会返回404三是瓦片请求并发数要控制如果一次性请求几十张瓦片iServer默认的并发限制会让你直接收到503。提示如果你在浏览器里能看到瓦片在Unity里就是加载不出来优先检查两个东西请求头里的Referer是否被服务端限制以及请求的URL里是否有特殊字符需要转义。3.3 通过REST API查询服务做业务联动在线服务不只是把模型拉出来看真正的项目都会要求点击查询、条件筛选、统计联动。超图iServer的REST数据服务提供了一套完整的查询接口Unity侧只需要用UnityWebRequest发送POST请求接收JSON返回结果即可。一个典型的属性查询请求如下POST http://服务器IP:8090/iserver/services/data-XXX/rest/data/datasources/数据源名称/datasets/数据集名称/featureResults请求体RequestBody是一个JSON字符串示例{ getFeatureMode: SQL, attributeFilter: SMID 0, maxFeatures: 100, returnContent: true, fieldNames: [SMID, 名称, 楼层数] }Unity侧的核心代码using UnityEngine; using UnityEngine.Networking; using System.Text; using System.Collections; public class FeatureQueryHelper : MonoBehaviour { public string queryUrl http://服务器IP:8090/iserver/services/data-XXX/rest/data/datasources/数据源名称/datasets/数据集名称/featureResults; public IEnumerator QueryBySql(string filter) { string json JsonUtility.ToJson(new QueryRequest { getFeatureMode SQL, attributeFilter filter, maxFeatures 100, returnContent true }); using (UnityWebRequest request new UnityWebRequest(queryUrl, POST)) { byte[] bodyRaw Encoding.UTF8.GetBytes(json); request.uploadHandler new UploadHandlerRaw(bodyRaw); request.downloadHandler new DownloadHandlerBuffer(); request.SetRequestHeader(Content-Type, application/json); yield return request.SendWebRequest(); if (request.result UnityWebRequest.Result.Success) { // 返回的是JSON数组需要自己解析feature集合 Debug.Log(request.downloadHandler.text); // 在这里把返回的字段映射到UI列表或者场景实体上 } } } }有一点需要特别提醒attributeFilter里的字段名不能随意写必须和数据集里的字段名完全一致包括大小写另外如果数据集字段是中文名JSON序列化时要注意编码格式建议统一用UTF-8否则中文条件大概率查不出结果。3.4 把三块内容串起来一个典型场景的完整逻辑我把在一个项目里验证过的场景启动逻辑整理出来供你参考。这个场景的需求是先加载三维建筑体再叠加道路底图点击建筑时从数据服务查询该建筑的基本信息并显示在UI上。场景启动顺序先初始化SceneControl加载三维S3M图层飞行到目标建筑区域。等待三维场景首帧渲染完成再在当前Camera下挂载瓦片底图加载器加载周边若干级的底图瓦片贴在透明平面上实现底图叠底。在SceneControl上挂一个射线点击监听检测点击到的模型对象取其唯一标识字段比如建筑ID。通过REST数据服务的SQL查询接口把该建筑ID作为过滤条件传入返回建筑属性列表。把属性绑定到Unity的UI面板完成业务联动。整个逻辑里最容易出问题的是第一步和第二步的衔接如果底图加载器在三维场景还没初始化完就开始拉瓦片瓦片平面的坐标基准可能错乱。我建议加一个延时或者等待SceneControl初始化回调的机制确保三维场景先就绪再叠底图。4. 常见问题与排查心得实录4.1 黑屏、白球、位置偏移这些现象分别指向什么加载三维服务时最常见的几个现象对应的原因通常是固定的整理成一张表给各位对照现象大概率原因处理方式运行后一片黑服务地址填错、端口不通、许可模块缺失先在浏览器里打开服务地址验证看Unity控制台有无报403/404/503检查iServer许可中三维模块是否启用场景连上一个白球视角飞到了坐标远离数据的位置检查FlyTo坐标是否是投影坐标不能直接填经纬度核对服务端坐标系与Unity里设置的坐标系是否一致模型加载出来了但位置平移了几公里坐标系或偏移参数不一致在iServer服务描述里确认坐标系编码Unity端同步设置为同一坐标系部分服务还有坐标偏移修正参数加载到一半卡住最后闪退数据范围太大、显存不足调整相机的远裁剪面关闭不必要的图层开启动态调度削隐瓦片底图有黑块部分级别瓦片未缓存检查服务端是否缓存了对应缩放级别或者请求超出服务范围的瓦片坐标4.2 Token失效与权限不足的排查超图iServer从10i版本开始默认开启了Token鉴权。如果你的服务地址里没有带token参数浏览器里能打开但Unity代码里返回401或者“Access Forbidden”这就是典型的Token问题。排查和解决方式在iServer服务管理中给对应的服务生成一个长期有效的TokenURL地址后面拼接?tokenxxxx。注意Token的有效期和IP白名单设置生产环境建议配置“该Token仅允许指定IP使用”这样即使Token泄露影响面也可控。如果你用SDK加载三维服务可以在SDK的初始化参数里设置Token字段而不是硬拼URL。SDK内部会对服务请求自动附加Token。某些老项目使用的iServer版本不支持URL传Token那就需要在请求头里附加Authorization字段值为Bearer token。4.3 版本不匹配与服务格式兼容性SuperMap的版本迭代比较快同一个S3M格式在不同大版本里做了很多扩展。如果你发现Unity端SDK加载不了某个特定的三维服务而桌面端iDesktop却能正常打开很可能就是SDK版本低于服务端发布缓存版本。遇到这种情况最快的处理方式是查看服务端缓存数据的地图配置里S3M的版本号然后对照SDK的支持说明。如果确实版本落后建议升级Unity SDK而不是降级服务器端的数据缓存因为重新生成缓存通常要花大量时间。4.4 常见问题速查表问题可以尝试的解决顺序三维服务加载黑屏浏览器直接访问服务地址 - 检查端口telnet - 检查iServer许可 - 换一个已确认可用的示例场景对比点击模型没反应确认射线是否打中模型 - 确认模型所在的层是否支持点击 - 确认点击到的对象是否能取到标识字段查询接口返回空数据在REST API在线测试页面直接调一次 - 检查SQL条件字段名是否包含中文且编码正确 - 查iServer日志地图瓦片错位检查瓦片坐标计算方式 - 检查平面预制体的纹理平铺参数 - 确认请求级别是否超出服务范围Unity场景卡顿掉帧关闭服务端动态调度参数 - 调整视锥体距离 - 减少并发请求数5. 在线服务的性能优化与生产环境经验5.1 加载调度不要一股脑全加载接完在线服务能跑通之后就得考虑性能了。在线服务的好处是按需加载但如果你在Unity里把所有图层一股脑设置成“始终可见”SDK还是会根据视锥去请求大量的瓦片数据。我的经验是把距离相机很远的图层优先级降低优先加载视野中心附近的S3M块。对不参与交互且占比很大的图层比如整片地表倾斜摄影可以设置visible属性为false只在需要特写时动态打开。如果有BIM模型建议在服务端发布时就按专业或楼层拆分数据集Unity侧按需加载不要一次性拉全楼。5.2 网络请求与缓存控制并发善用本地缓存iServer对并发请求数有上限默认看配置一般几十到一百不等。Unity端同时发太多瓦片请求会直接把服务拖垮。我在项目里做了一个简单的请求队列最多同时并发6个请求其他排队。不要小看这个设计它能避免很多诡异的偶发断连。另外对于重复访问的场景SDK本身有本地缓存机制但默认缓存路径和大小需要你自己设置。缓存建议放在项目的持久化目录不要放在StreamingAssets里。缓存大小根据磁盘容量设置我通常设5GB左右足够覆盖城市级三维数据的大部分重复浏览场景。5.3 我踩过的一个印象最深的坑最后分享一个印象很深的经验。有一个项目现场环境特殊服务器和Unity开发机不在同一网段中间经过了多层NAT。开发时一切正常部署到现场后三维场景死活加载不出来。排查到最后发现是NAT设备对HTTP长时间连接的监听过期导致SDK和服务端的TCP长连接被中间设备掐断。解决方案是把SDK的超时时间调小一点并且在场景加载失败时自动重新连接一次同时让现场网络同事调整NAT设备的连接保活时间。这个问题的隐蔽之处在于它不是必然发生而是偶发出现一旦发生就全部表现为加载失败。后来我在所有项目合同里都会跟客户确认一句三维服务所在网段的中间设备不能主动断开HTTP长连接。这句话帮我少加了很多次班。在线接服务的这套流程验证一次之后后续项目基本就是复用流程从拿到服务地址到场景跑起来控制在半天以内是可以做到的。希望这篇实操文档能让你少走一些弯路把更多时间留给业务功能本身。