前阵子接了一个三维地理信息展示的活儿要求在内网环境里用 Cesium 搭建一个以哈密区域为核心的三维场景。客户端那边一口咬定必须用 1.19.11 这个老版本说是之前的系统全部基于这个版本扩展的升级换新引擎会让一堆历史功能和控件全部报废。接过需求后我才发现这事儿比想象中麻烦老版本 Cesium 默认会请求在线影像服务离线环境里一开页面就是黑地球影像纵使加载上来了还得考虑跟 DEM 地形数据叠加后的匹配问题哈密这边的地形数据还得自己预处理、切片、发布、调试。整套流程走下来从选型、切图到最终跑通前后折腾了小半个月。这篇文章就把这次基于 Cesium 1.19.11 加载自定义影像和哈密地形数据的完整过程记录下来包括方案选型的来龙去脉、参数配置的逐一讲解、我在实际操作中踩过的大坑以及最后总结出来的问题排查清单。如果你也正被要求在老版本引擎上做本地影像和地形叠加这篇应该能帮你少走不少弯路。1. 项目理解与技术选型思路1.1 为什么锁定 Cesium 1.19.11Cesium 1.19.11 是一个很特殊的版本。它发布于 2017 年底到 2018 年初那段区间恰好处于 WebGL 技术开始大规模普及、三维地球应用从 PC 桌面端向浏览器端迁移的关键节点。这个版本的 API 设计已经非常稳定内置了成熟的地理坐标系、影像图层管理、地形加载和相机控制机制同时还没有被后来 Cesium ion 在线资产服务捆绑。这就意味着你完全可以在纯离线环境下依靠自定义的本地数据源完成整套三维可视化。当时的第一感受是新版 Cesium 虽然功能强、效果好但它的很多默认行为都依赖 ion 在线服务。一旦项目部署在大西北的机关单位内网里外网访问全部掐断新版的很多便利特性反而变成累赘。而 1.19.11 的加载逻辑非常朴素——它不关心数据从哪里来只要你能提供一个 HTTP 接口返回瓦片数据它就能渲染出来。这种特性让它特别适合内网离线三维场景。从工程角度来说老版本还意味着你手上的很多历史代码都能直接复用。我这次接手场景里前端框架、UI 组件、交互逻辑都已经封装好了基于 1.19.11 的接口。如果贸然升级到新版引擎所有基于底层 API 封装的代码都得重新适配人力成本和时间成本都不可接受。所以锁定 1.19.11 不是怀旧是现实约束下的理性选择。1.2 “影像 地形”双通道架构理解 Cesium 的三维场景渲染逻辑最关键的一点就是分清影像图层和地形数据的区别。影像图层相当于贴在三维地球表面的一张“壁纸”负责把卫星遥感影像、扫描地图或手绘底图铺到球面上构成视觉画面的主体内容。而地形数据则是一个描述地表起伏的数字高程模型Cesium 根据这个模型对地球表面进行顶点位移让山脉、山谷、戈壁滩的起伏真实地呈现出来。这两套数据在架构上是完全独立的两个通道。影像走ImageryProvider地形走TerrainProvider。它们分别生成各自的瓦片金字塔在渲染管线里再做贴合。如果只加载影像而没有地形画面是平的像摊开的一张地图纸如果只加载地形而没有影像则是一个灰蒙蒙、只有起伏没有纹理的模型。在哈密的场景里我们想要的效果是把遥感影像当作真实地表纹理叠加在 30 米分辨率 DEM 生成的地形起伏之上这样用户拖拽地图时能感受到天山余脉的走势和盆地平原的平坦。数据流的走向也很明确原始影像文件和 DEM 文件分别经过预处理转成 Cesium 能识别的瓦片目录然后放到本地静态服务器上Cesium 通过 URL 模板按层级加载。整个过程不依赖任何在线服务数据的掌控权和获取速度都在本地完成。1.3 自定义影像加载的几种路线对比自定义影像加载在 Cesium 1.19.11 中有好几种实现方式但各有各的使用边界不能随便选。我把常见的几条路线整理成了对比表。方案适用场景优点缺点UrlTemplateImageryProvider本地瓦片目录、标准 XYZ/TMS 切片性能好按需加载支持大规模数据需要自己切瓦片目录规范必须匹配SingleTileImageryProvider单张大幅遥感图、简单底图配置最简单一张图片就能显示图片过大时加载慢且全局只能一整张纹理WebMapServiceImageryProvider已有 GeoServer / MapServer 服务后端切图灵活支持动态裁剪每次请求开销高交互流畅度一般TileMapServiceImageryProvider标准 TMS 元数据服务有 tileset.xml 元数据配置简单不如 UrlTemplate 那么直接可控这次项目里我优先采用的是UrlTemplateImageryProvider。原因很简单哈密区域的范围清楚我们可以用工具把影像提前切成 0-18 级的金字塔瓦片后续运行过程中零计算开销直接按级别拉图。而且瓦片方案里的坐标原点、级别范围、投影方式都是自己定的能跟地形数据严格对齐。那单张图片的方案行不行也能用。如果你是拿一张 JPG 或者 PNG 当底图范围不大、分辨率要求不高确实省事。但哈密的项目里我们有 2 米分辨率的影像单张图片放大到几十个像素级别之后没法看必须走切瓦片路线。2. 自定义影像加载核心实现2.1 UrlTemplateImageryProvider 参数配置逐项拆解在 Cesium 1.19.11 里一个最基础的本地瓦片影像加载代码是下面这个样子。var tmsProvider new Cesium.UrlTemplateImageryProvider({ url : http://192.168.1.100:8080/hami_imagery/{z}/{x}/{y}.png, tilingScheme : new Cesium.GeographicTilingScheme({ numberOfLevelZeroTilesX : 2, numberOfLevelZeroTilesY : 1 }), minimumLevel : 0, maximumLevel : 18, rectangle : Cesium.Rectangle.fromDegrees(91.0, 41.0, 97.0, 45.0) }); viewer.imageryLayers.addImageryProvider(tmsProvider);这里每个参数都不是随便填的我来逐个说清楚背景。url是瓦片的 HTTP 地址模板{z}表示层级、{x}表示列号、{y}表示行号。Cesium 在渲染时会把这三个占位符替换成真实数字去请求对应的瓦片文件。坑点在于{y}的方向。不同切图工具的瓦片编号起点不同有的是从左上角 0 开始向下递增有的是从左下角 0 开始向上递增。如果这个方向反了你加载出来的影像不是上下颠倒就是南北错位。tilingScheme是瓦片切分方案。它本质上规定了第 0 级地球被切成几块、每块的经纬度跨度是多少、后续每一级如何细分。我用的是GeographicTilingScheme也就是按经纬度等间隔切分的方案0 级把全球切为 2 列 1 行每块覆盖 180 度经度和 180 度纬度。这个方案比较适合国内多用经纬度坐标系的数据。如果你用的是 Web 墨卡托投影的瓦片那tilingScheme应该选WebMercatorTilingScheme它的 0 级是 1 列 1 行从左上角开始编号。minimumLevel和maximumLevel是瓦片请求的层级范围。哈密的瓦片我只切到了 18 级所以maximumLevel设为 18超过这个级别 Cesium 就不会再去请求不存在的瓦片。没切数据却允许请求最直接的结果就是 F12 控制台里一片红——全是在请求不存在的第四级目录。rectangle指定了影像数据覆盖的地理范围。设置它最大的好处是缩小渲染区域。Cesium 只需要在这个区域内请求瓦片区域外面的范围直接留空避免为了一个局部数据跑满全球的请求量。2.2 坐标系与瓦片编号规则中的关键选择这部分是新手最容易抓狂的地方。很多人影像加载不出来不是代码写错了而是瓦片数据的坐标系和 Cesium 默认的纹理映射方式对不上。首先要搞清楚Cesium 内部对地球表面做纹理采样时是根据tilingScheme来决定每个瓦片覆盖的经纬度范围的。如果你的瓦片是用 EPSG:4326 经纬度切出来的那么你在加载时就必须告诉 Cesium“我的瓦片是经纬度切法”也就是new Cesium.GeographicTilingScheme()。如果你的瓦片是用 EPSG:3857 Web 墨卡托切出来的那就必须用WebMercatorTilingScheme。两边不一致画面表现就是瓦片整体错位或者根本显示不出来。第二个关键点是 0 级切分的数量。GeographicTilingScheme的 0 级切 2 列 1 行每块正好是 180 度 × 180 度。WebMercatorTilingScheme的 0 级切 1 列 1 行覆盖全球。这个参数必须跟实际切图工具生成的目录结构一致。比如你用某切图工具默认参数切 4326 瓦片它 0 级生成 2 个目录 0/0 和 0/1那就对应numberOfLevelZeroTilesX : 2。第三点是{y}方向问题。如果你手上的瓦片是按 TMS 规范切的第 0 级从底部开始往上编行号那么 Cesium 的UrlTemplateImageryProvider默认按顶部起始的规则取行号时你会看到影像上下颠倒。这种情况下你可以在 url 模板里改用{reverseY}占位符解决。不过要注意{reverseY}在很多后期版本里才稳定支持1.19.11 里我实测是可以用的。如果你的切图工具是严格的 TMS推荐编码时直接用{reverseY}这样代码的可读性也更好。url : http://192.168.1.100:8080/hami_imagery/{z}/{x}/{reverseY}.png2.3 影像加载完成后的正确验证方式影像 provider 配置好之后不要急着看效果先做几个基本验证。第一件事打开浏览器开发者工具的 Network 面板过滤 XHR 和 Img 请求拖动地球到哈密区域观察是否有瓦片请求发出去。如果你的 rectangle 设的没问题网络请求里应该能看到http://192.168.1.100:8080/hami_imagery/...这样的地址。第二件事点开其中一张瓦片 URL看看图片是不是一张正常的宫格图。经常出现的情况是瓦片能请求到但是内容是空白或纯色块那可能是切图时数据范围选错了或者图片格式 Cesium 不认。Cesium 对 PNG、JPG、WebP 都支持但如果是带透明通道的怪异格式在小版本上偶尔会踩坑。第三件事是验证瓦片的排列逻辑。你可以把相机拉到最大范围看全局的地球轮廓是否正常。如果影像出现了横向平移或者上下颠倒说明tilingScheme或者y方向的配置有问题回到 2.2 节检查。我还习惯在代码里输出 provider 的ready状态tmsProvider.readyPromise.then(function() { console.log(影像 provider 就绪瓦片范围: tmsProvider.rectangle); }).otherwise(function(err) { console.error(影像 provider 加载失败: err); });1.19.11 里UrlTemplateImageryProvider是支持readyPromise的如果初始化的元数据读取失败这个 Promise 会进入失败状态方便我们第一时间发现问题。3. 哈密地形加载完整流程3.1 地形数据来源与预处理要点哈密区域的地形数据我采用的是开源 DEM 数据源常见的选项是 SRTM 和 ALOS。SRTM 的 30 米分辨率在哈密这种地貌反差大的区域表现尚可但如果需要更精细的峡谷、冲积扇等地形细节ALOS 的 12.5 米分辨率更好。拿到数据后不能直接用必须经过几个关键步骤。首先是坐标范围裁剪。哈密区域的大致范围在东经 91 度到 97 度、北纬 41 度到 45 度之间但这只是一个粗略的四边形。你从公开数据源下载的 DEM 往往是若干条带状的图幅文件需要用工具按你要的范围裁剪拼接成一张完整的 TIF。我在实际项目中使用的处理方式是用 GDAL 命令行做裁剪和重投影gdal_translate -projwin 91 45 97 41 -a_srs EPSG:4326 granule1.tif hami_dem_1.tif gdal_translate -projwin 91 45 97 41 -a_srs EPSG:4326 granule2.tif hami_dem_2.tif gdal_merge.py -o hami_dem_merged.tif hami_dem_1.tif hami_dem_2.tif-projwin后面的四个数字顺序是xmin ymax xmax ymin注意别看错。-a_srs EPSG:4326是为了强制把数据定义为 WGS84 经纬度坐标很多原始 DEM 自带投影信息但为了避免切图工具读不到元数据这里做一次显式声明更稳妥。接下来要用gdalwarp把 DEM 的像元分辨率统一成你需要的级别。我这次地形瓦片最高做到 16 级30 米分辨率的原始数据刚好够用再往上切也没意义纯属浪费存储空间和处理时间。处理完成后再转成 16 位整型或 32 位浮点型的单波段 GeoTIFF确保高度值不丢失。3.2 生成 Cesium 可识别的地形瓦片Cesium 不能直接加载 GeoTIFF它需要的是经过编码的地形瓦片格式专业术语叫 quantized-mesh。这种格式的瓦片金字塔和影像金字塔类似也是{z}/{x}/{y}三级目录但文件扩展名是.terrain并且在根目录有一个layer.json元数据文件描述瓦片的层级范围、投影信息等。切地形瓦片我采用的是开源地形切图工具核心原理是读入 DEM 影像按照指定的金字塔结构生成高程瓦片。切图命令大致如下。ctb-tile --output ./hami_terrain --terrain --format quantized-mesh --zoom 0-16 hami_dem_merged.tif切图完成后输出的目录结构应该是hami_terrain/ |-- layer.json |-- 0 | |-- 0 | | -- 0.terrain |-- 1 | |-- 0 | | -- 0.terrain |-- ... -- 16 |-- 3586 | -- 2543.terrain为什么 Cesium 1.19.11 能直接认这套格式因为它在底层实现了 quantized-mesh 1.0 解析。原来的 1.0 版本把每个地形瓦片的顶点按照四叉树细分然后用 16 位整型存储相对高度这样可以极大压缩体积。我特意确认过1.19.11 和这个地形格式的兼容性没有问题前提是你切图时一定要选 1.0 格式不要切那个带法线纹理扩展的新版 1.1 格式老引擎解析起来容易出问题。有一个切图时的操作细节值得留意原始 DEM 数据范围之外的那些区域会生成高度值为 0 的平坦瓦片。如果你在 Cesium 里加载后发现哈密区域边缘出现了一个大坑看起来像地陷了一样多半是这个问题。解决的办法是在切图前把 DEM 再向外扩一圈让边界外的区域也填上合理的高程值这样过渡会比较自然。3.3 地形瓦片发布与 Cesium 接入地形瓦片生成以后需要放到一个 HTTP 静态文件服务上。我用的是 nginx配置片段如下。server { listen 8080; server_name 192.168.1.100; location /hami_terrain/ { alias /data/terrain/; default_type application/vnd.quantized-meshoctet-stream; add_header Access-Control-Allow-Origin *; } location /hami_imagery/ { alias /data/imagery/; default_type image/png; add_header Access-Control-Allow-Origin *; } }default_type是必须写的一行。.terrain文件不是常见扩展名nginx 默认不认识会把它当application/octet-stream返回旧版 Cesium 对地形请求的响应媒体类型有校验类型不对就直接挂掉。写application/vnd.quantized-meshoctet-stream是标准做法实测下来 1.19.11 能正常解析。跨域头Access-Control-Allow-Origin *也是为开发方便加的。如果你的前端页面跑到另一台机器上而瓦片服务留在内网服务器跨域请求是少不了的。生产环境当然要收紧这个配置但开发调试阶段全放开才不容易被卡脖子。Cesium 侧加载地形的代码就更简单了。var terrainProvider new Cesium.CesiumTerrainProvider({ url : http://192.168.1.100:8080/hami_terrain }); viewer.terrainProvider terrainProvider; terrainProvider.readyPromise.then(function() { console.log(地形就绪最大级别: terrainProvider.maximumLevel); });这里注意url要指向发布目录的根路径不是layer.json的完整路径Cesium 会自己拼接layer.json去请求。如果你在浏览器里直接访问http://192.168.1.100:8080/hami_terrain/layer.json能看到一个 JSON 文件说明服务发布成功。3.4 镜头定位与高程夸张调整地形加载完成不是终点还得验证它和影像是否精确贴合。手动放大地图找到哈密区域太费事我习惯用相机飞行直接定位。viewer.camera.flyTo({ destination : Cesium.Cartesian3.fromDegrees(93.5, 42.8, 120000.0), orientation : { heading : 0, pitch : -Cesium.Math.PI_OVER_TWO, roll : 0 }, duration : 3 });飞到目标位置后如果地形和影像都正确你应该能看到哈密盆地的地貌轮廓——北部山体有明显的起伏南部平原地带相对平坦影像纹理贴合在山体表面。这时候还要检查一个参数高程夸张系数。Cesium 默认的高程缩放是 1.0意思是真实高程值不做放大。哈密这种区域整体海拔较高但相对高差并不是特别极端如果想让起伏更明显可以调高夸张系数。viewer.scene.globe.terrainExaggeration 1.5;但夸张系数调太高会有副作用——整个场景会变得“卡通化”视觉上非常假。我建议在 1.0 到 2.0 之间微调找到一个视觉舒服的点。4. 实操效果与联调优化4.1 影像与地形叠加后的渲染验证当影像和地形两个通道都正常工作后画面上的三维感会立刻显现出来。这时候我会做一组系统性检查确保叠加效果没有潜在问题。第一是看纹理贴合的姿态。当地形有起伏时影像纹理应该自然地包裹在山包上而不是像桌布一样平平地铺在半空中。如果你看到影像表面是平的、与地形的起伏脱节多半是terrainProvider没有赋值成功或者depthTestAgainstTerrain的设置导致半透明纹理把地形盖住了。第二是看细节层级。把镜头拉低到楼宇尺度观察地面纹理是否还是清晰的。如果到 15 级以上影像变得模糊说明切图级别不够需要回去补切瓦片或者考虑换更高效的纹理压缩方式。在没做任何影像金字塔扩展的情况下我这次切到 18 级基本满足了 15000 到 110000 尺度下的浏览需求。第三是看整体色调和范围过渡。哈密区域周边的戈壁滩、绿洲和山体在影像上有不同的色彩如果影像裁剪范围小于 DEM 范围边缘会出现一块无色区域。我在 3.2 节里提到过 DEM 外扩的问题影像同样要预留出一定范围的过渡带避免边界太生硬。4.2 性能优化与内存控制内网环境下性能问题同样不可忽视。老版本 Cesium 在低配工控机上跑起来很容易掉帧尤其是地形加载后顶点数量暴增对 GPU 的压榨很明显。我做了几个关键优化。第一是限定影像最大请求级别。maximumLevel定到 18但实际用户很少拉那么深。可以把默认最高级别设到 16只有滚轮放大到足够近时才请求更深层瓦片。这个 Cesium 会自动控制。第二是设置合理的瓦片缓存大小。TileMapServiceImageryProvider和UrlTemplateImageryProvider都使用内存内的瓦片缓存。在 1.19.11 里你可以通过这个属性控制缓存上限。viewer.scene.globe.tileCacheSize 512;这个属性不是越大越好。缓存越大重新浏览之前看过的区域时加载越快但内存占用也越高。我用 512 这个值在 8GB 内存的工控机上跑得很稳再往上就会开始吃紧。第三是关闭不必要的附加渲染。scene.requestRenderMode为 true 时画面静止时不再重复渲染只等有交互或数据请求时才重绘这在低功耗设备上非常有效。但要注意开启这个模式后偶尔会出现拖拽时画面滞后需要配合手动触发渲染的机制。viewer.scene.requestRenderMode false;我实际测试下来在交互频繁的场景里反而会卡所以默认保持 false只有在大屏展示这种几乎只做观赏的场景才考虑开启。4.3 离线环境里那些“隐形炸弹”老版本 Cesium 最坑人的地方就是离线环境下的隐性网络依赖。外网断开后Cesium 运行时依然尝试向在线服务请求资源导致各种不可预知的表现。先说几个最典型的。如果你直接new Cesium.Viewer(id)没有传任何地图参数新版会在后台请求 Cesium ion 的默认影像和地形。1.19.11 也是同样的逻辑它在没有显式指定imageryProvider时默认请求在线 Bing 影像。内网环境下这个请求会一直超时重试导致页面卡顿和黑屏。解决方法是初始化后立刻清掉默认图层再挂上自己的影像。var viewer new Cesium.Viewer(cesiumContainer, { imageryProvider : false }); viewer.imageryLayers.removeAll(); viewer.imageryLayers.addImageryProvider(tmsProvider); viewer.terrainProvider terrainProvider;另外一个隐性问题Cesium 默认会读取 Cesium ion 的 asset 访问凭据。即使你在代码里没显式调用它的一些内部模块也会尝试读取导致控制台报错。虽然不影响功能但在内网这种信息敏感环境里最好在构建打包时就把相关模块剪掉或者从代码层面屏蔽跟在线服务相关的默认行为。还有Cesium.createWorldTerrain这个 API 是老版本里推荐的在线地形方案离线环境下绝对不能调用。我见过一个同事没注意用createWorldTerrain加载地形结果整个外网断开后连页面都打不开排查了好久才发现是这里在拖后腿。4.4 跨域与访问控制细节内网项目里前端页面和瓦片服务经常不在同一台机器上。跨域请求的配置错了瓦片会全部被浏览器拦截。影像、地形、动态数据接口只要是从别的域名或端口拿数据跨域头都不能省。nginx 里我加了add_header Access-Control-Allow-Origin *;这是最宽松的配置。如果你能做到前后端同源部署可以不带跨域头但开发期不建议这么做因为浏览器地址栏用localhost访问和用局域网 IP 访问是两种不同的源切来切去容易出问题。浏览器层面还有一个绕不开的机制——同源策略下的file://协议限制。本地直接双击 HTML 文件打开 Cesium 页面时很多浏览器会禁止内部模块加载本地文件资源导致各种报错。所以我建议从一开始就养成用本地静态服务器访问页面的习惯比如python -m http.server 8080临时起一个服务或者直接用 nginx 统一发布。5. 问题排查与避坑实录5.1 高频问题速查表实际操作中遇到的问题五花八门我把高频问题整理成了一个速查表方便后续排查时对照。现象可能原因解决方案页面黑屏地球看不到默认在线影像离线请求超时或 imageryProvider 初始化失败初始化时imageryProvider:false再手动挂载本地影像影像图块错位、平移tilingScheme或 0 级切分数与实际瓦片不一致核对切图工具的坐标系和 0 级行列数影像上下颠倒瓦片 y 轴编号方向相反url 模板改用{reverseY}或将 TMS y 转 XYZ地形加载后是平的terrainProvider赋值失败或网址指向层级目录错误确认指向根目录且layer.json可访问哈密周边出现凹陷大坑DEM 边界区域高度值为 0切图前对 DEM 做外扩填充瓦片请求 404切图级别不足或者maximumLevel设置过大检查layer.json元数据里的最大级别控制台报 CORS 错误瓦片服务缺少跨域响应头nginx 添加Access-Control-Allow-Origin内存涨得飞快瓦片缓存过大或无限请求未限定层级调小tileCacheSize设定maximumLevel这张表解决了我 90% 的现场问题。剩下那 10% 基本都是环境差异导致的需要具体看报错信息来定位。5.2 三个“说多了都是泪”的教训第一教训坐标系混用是真坑。我的同事处理影像数据时用的是 CGCS2000 国家坐标系切出来的瓦片标注的是 EPSG:4326但实际投影参数完全不同。加载到 Cesium 里之后影像整体偏移了大概几百米山峰和纹理位置完全对不上。排查了很久才发现是原始数据投影被强制覆盖了。这种问题在视觉上不明显但一旦叠加矢量数据或做量测就会发现误差巨大。我的建议是切图前先gdalsrsinfo看一遍原始数据的真实投影别盲目用-a_srs覆盖。第二教训地形瓦片生成时必须选对格式。刚开始我切地形时用的是带 normal 扩展的 1.1 格式想着光照效果更细腻。结果加载进 1.19.11 后页面直接提示地形解析异常。换成标准的 quantized-mesh 1.0 后一切正常。老版本的地形解析器只实现了 1.0 规范任何多余的数据结构都会让它崩溃。所以如果你的项目被锁定在老版本引擎切地形时直接选 1.0别整那些花活。第三教训影像瓦片切太深是灾难。我最初想着把哈密区域切到 20 级将来放大看细节也清楚。结果切图跑了近一天硬盘占掉 200 多 GB加载速度反而变慢了。原因在于瓦片数量随级别指数级增长16 级已经够用的场景切到 20 级完全是浪费。后来我砍掉 17 级以上的瓦片磁盘占用少了 95%加载速度也明显改善。切图前先想清楚业务上最精细需要看什么尺度再倒推切到几级。5.3 一套可复用的排查流程面对新问题时别慌我摸索出一套适合老版本 Cesium 离线加载的排查流程。第一步看控制台报错区分是网络请求问题、JavaScript 异常还是资源解析问题。第二步直接访问瓦片 URL 和服务地址验证静态文件服务是否正常。第三步浏览layer.json内容核对元数据里写的投影、层级、范围是否符合预期。第四步关掉所有自定义图层只加载影像或只加载地形二分定位是哪一类数据出问题。这套流程走完绝大多数问题都能定位到根因。测本地瓦片时我还会用 Firefox 和 Chrome 各测一遍因为两个浏览器对 CORS 和媒体类型的容错机制有差异。Firefox 在 MIME 类型不对时会严格拦截Chrome 则相对宽松。如果你在 Chrome 里一切正常、Firefox 里一片白多半是Content-Type设置少了。写在最后的个人体会这套方案做完到现在稳定跑了几个月哈密区域的三维场景从最初的黑地球到最终的山脉起伏、影像清晰整个过程里最有价值的不是某段代码而是对老版本 Cesium 数据加载机制的理解。搞清楚它期望的瓦片目录、坐标系、格式规范和在线依赖你就掌握了在任何本地化三维项目里自由组合数据源的能力。后续如果想扩展可以在这个基础上加矢量图斑、做路径巡航、堆粒子特效思路都是同一套先把数据准备好再用 provider 接进去。希望这篇记录能帮到和我一样在旧版本引擎和离线环境里折腾三维场景的朋友。
前阵子接了一个三维地理信息展示的活儿要求在内网环境里用 Cesium 搭建一个以哈密区域为核心的三维场景。客户端那边一口咬定必须用 1.19.11 这个老版本说是之前的系统全部基于这个版本扩展的升级换新引擎会让一堆历史功能和控件全部报废。接过需求后我才发现这事儿比想象中麻烦老版本 Cesium 默认会请求在线影像服务离线环境里一开页面就是黑地球影像纵使加载上来了还得考虑跟 DEM 地形数据叠加后的匹配问题哈密这边的地形数据还得自己预处理、切片、发布、调试。整套流程走下来从选型、切图到最终跑通前后折腾了小半个月。这篇文章就把这次基于 Cesium 1.19.11 加载自定义影像和哈密地形数据的完整过程记录下来包括方案选型的来龙去脉、参数配置的逐一讲解、我在实际操作中踩过的大坑以及最后总结出来的问题排查清单。如果你也正被要求在老版本引擎上做本地影像和地形叠加这篇应该能帮你少走不少弯路。1. 项目理解与技术选型思路1.1 为什么锁定 Cesium 1.19.11Cesium 1.19.11 是一个很特殊的版本。它发布于 2017 年底到 2018 年初那段区间恰好处于 WebGL 技术开始大规模普及、三维地球应用从 PC 桌面端向浏览器端迁移的关键节点。这个版本的 API 设计已经非常稳定内置了成熟的地理坐标系、影像图层管理、地形加载和相机控制机制同时还没有被后来 Cesium ion 在线资产服务捆绑。这就意味着你完全可以在纯离线环境下依靠自定义的本地数据源完成整套三维可视化。当时的第一感受是新版 Cesium 虽然功能强、效果好但它的很多默认行为都依赖 ion 在线服务。一旦项目部署在大西北的机关单位内网里外网访问全部掐断新版的很多便利特性反而变成累赘。而 1.19.11 的加载逻辑非常朴素——它不关心数据从哪里来只要你能提供一个 HTTP 接口返回瓦片数据它就能渲染出来。这种特性让它特别适合内网离线三维场景。从工程角度来说老版本还意味着你手上的很多历史代码都能直接复用。我这次接手场景里前端框架、UI 组件、交互逻辑都已经封装好了基于 1.19.11 的接口。如果贸然升级到新版引擎所有基于底层 API 封装的代码都得重新适配人力成本和时间成本都不可接受。所以锁定 1.19.11 不是怀旧是现实约束下的理性选择。1.2 “影像 地形”双通道架构理解 Cesium 的三维场景渲染逻辑最关键的一点就是分清影像图层和地形数据的区别。影像图层相当于贴在三维地球表面的一张“壁纸”负责把卫星遥感影像、扫描地图或手绘底图铺到球面上构成视觉画面的主体内容。而地形数据则是一个描述地表起伏的数字高程模型Cesium 根据这个模型对地球表面进行顶点位移让山脉、山谷、戈壁滩的起伏真实地呈现出来。这两套数据在架构上是完全独立的两个通道。影像走ImageryProvider地形走TerrainProvider。它们分别生成各自的瓦片金字塔在渲染管线里再做贴合。如果只加载影像而没有地形画面是平的像摊开的一张地图纸如果只加载地形而没有影像则是一个灰蒙蒙、只有起伏没有纹理的模型。在哈密的场景里我们想要的效果是把遥感影像当作真实地表纹理叠加在 30 米分辨率 DEM 生成的地形起伏之上这样用户拖拽地图时能感受到天山余脉的走势和盆地平原的平坦。数据流的走向也很明确原始影像文件和 DEM 文件分别经过预处理转成 Cesium 能识别的瓦片目录然后放到本地静态服务器上Cesium 通过 URL 模板按层级加载。整个过程不依赖任何在线服务数据的掌控权和获取速度都在本地完成。1.3 自定义影像加载的几种路线对比自定义影像加载在 Cesium 1.19.11 中有好几种实现方式但各有各的使用边界不能随便选。我把常见的几条路线整理成了对比表。方案适用场景优点缺点UrlTemplateImageryProvider本地瓦片目录、标准 XYZ/TMS 切片性能好按需加载支持大规模数据需要自己切瓦片目录规范必须匹配SingleTileImageryProvider单张大幅遥感图、简单底图配置最简单一张图片就能显示图片过大时加载慢且全局只能一整张纹理WebMapServiceImageryProvider已有 GeoServer / MapServer 服务后端切图灵活支持动态裁剪每次请求开销高交互流畅度一般TileMapServiceImageryProvider标准 TMS 元数据服务有 tileset.xml 元数据配置简单不如 UrlTemplate 那么直接可控这次项目里我优先采用的是UrlTemplateImageryProvider。原因很简单哈密区域的范围清楚我们可以用工具把影像提前切成 0-18 级的金字塔瓦片后续运行过程中零计算开销直接按级别拉图。而且瓦片方案里的坐标原点、级别范围、投影方式都是自己定的能跟地形数据严格对齐。那单张图片的方案行不行也能用。如果你是拿一张 JPG 或者 PNG 当底图范围不大、分辨率要求不高确实省事。但哈密的项目里我们有 2 米分辨率的影像单张图片放大到几十个像素级别之后没法看必须走切瓦片路线。2. 自定义影像加载核心实现2.1 UrlTemplateImageryProvider 参数配置逐项拆解在 Cesium 1.19.11 里一个最基础的本地瓦片影像加载代码是下面这个样子。var tmsProvider new Cesium.UrlTemplateImageryProvider({ url : http://192.168.1.100:8080/hami_imagery/{z}/{x}/{y}.png, tilingScheme : new Cesium.GeographicTilingScheme({ numberOfLevelZeroTilesX : 2, numberOfLevelZeroTilesY : 1 }), minimumLevel : 0, maximumLevel : 18, rectangle : Cesium.Rectangle.fromDegrees(91.0, 41.0, 97.0, 45.0) }); viewer.imageryLayers.addImageryProvider(tmsProvider);这里每个参数都不是随便填的我来逐个说清楚背景。url是瓦片的 HTTP 地址模板{z}表示层级、{x}表示列号、{y}表示行号。Cesium 在渲染时会把这三个占位符替换成真实数字去请求对应的瓦片文件。坑点在于{y}的方向。不同切图工具的瓦片编号起点不同有的是从左上角 0 开始向下递增有的是从左下角 0 开始向上递增。如果这个方向反了你加载出来的影像不是上下颠倒就是南北错位。tilingScheme是瓦片切分方案。它本质上规定了第 0 级地球被切成几块、每块的经纬度跨度是多少、后续每一级如何细分。我用的是GeographicTilingScheme也就是按经纬度等间隔切分的方案0 级把全球切为 2 列 1 行每块覆盖 180 度经度和 180 度纬度。这个方案比较适合国内多用经纬度坐标系的数据。如果你用的是 Web 墨卡托投影的瓦片那tilingScheme应该选WebMercatorTilingScheme它的 0 级是 1 列 1 行从左上角开始编号。minimumLevel和maximumLevel是瓦片请求的层级范围。哈密的瓦片我只切到了 18 级所以maximumLevel设为 18超过这个级别 Cesium 就不会再去请求不存在的瓦片。没切数据却允许请求最直接的结果就是 F12 控制台里一片红——全是在请求不存在的第四级目录。rectangle指定了影像数据覆盖的地理范围。设置它最大的好处是缩小渲染区域。Cesium 只需要在这个区域内请求瓦片区域外面的范围直接留空避免为了一个局部数据跑满全球的请求量。2.2 坐标系与瓦片编号规则中的关键选择这部分是新手最容易抓狂的地方。很多人影像加载不出来不是代码写错了而是瓦片数据的坐标系和 Cesium 默认的纹理映射方式对不上。首先要搞清楚Cesium 内部对地球表面做纹理采样时是根据tilingScheme来决定每个瓦片覆盖的经纬度范围的。如果你的瓦片是用 EPSG:4326 经纬度切出来的那么你在加载时就必须告诉 Cesium“我的瓦片是经纬度切法”也就是new Cesium.GeographicTilingScheme()。如果你的瓦片是用 EPSG:3857 Web 墨卡托切出来的那就必须用WebMercatorTilingScheme。两边不一致画面表现就是瓦片整体错位或者根本显示不出来。第二个关键点是 0 级切分的数量。GeographicTilingScheme的 0 级切 2 列 1 行每块正好是 180 度 × 180 度。WebMercatorTilingScheme的 0 级切 1 列 1 行覆盖全球。这个参数必须跟实际切图工具生成的目录结构一致。比如你用某切图工具默认参数切 4326 瓦片它 0 级生成 2 个目录 0/0 和 0/1那就对应numberOfLevelZeroTilesX : 2。第三点是{y}方向问题。如果你手上的瓦片是按 TMS 规范切的第 0 级从底部开始往上编行号那么 Cesium 的UrlTemplateImageryProvider默认按顶部起始的规则取行号时你会看到影像上下颠倒。这种情况下你可以在 url 模板里改用{reverseY}占位符解决。不过要注意{reverseY}在很多后期版本里才稳定支持1.19.11 里我实测是可以用的。如果你的切图工具是严格的 TMS推荐编码时直接用{reverseY}这样代码的可读性也更好。url : http://192.168.1.100:8080/hami_imagery/{z}/{x}/{reverseY}.png2.3 影像加载完成后的正确验证方式影像 provider 配置好之后不要急着看效果先做几个基本验证。第一件事打开浏览器开发者工具的 Network 面板过滤 XHR 和 Img 请求拖动地球到哈密区域观察是否有瓦片请求发出去。如果你的 rectangle 设的没问题网络请求里应该能看到http://192.168.1.100:8080/hami_imagery/...这样的地址。第二件事点开其中一张瓦片 URL看看图片是不是一张正常的宫格图。经常出现的情况是瓦片能请求到但是内容是空白或纯色块那可能是切图时数据范围选错了或者图片格式 Cesium 不认。Cesium 对 PNG、JPG、WebP 都支持但如果是带透明通道的怪异格式在小版本上偶尔会踩坑。第三件事是验证瓦片的排列逻辑。你可以把相机拉到最大范围看全局的地球轮廓是否正常。如果影像出现了横向平移或者上下颠倒说明tilingScheme或者y方向的配置有问题回到 2.2 节检查。我还习惯在代码里输出 provider 的ready状态tmsProvider.readyPromise.then(function() { console.log(影像 provider 就绪瓦片范围: tmsProvider.rectangle); }).otherwise(function(err) { console.error(影像 provider 加载失败: err); });1.19.11 里UrlTemplateImageryProvider是支持readyPromise的如果初始化的元数据读取失败这个 Promise 会进入失败状态方便我们第一时间发现问题。3. 哈密地形加载完整流程3.1 地形数据来源与预处理要点哈密区域的地形数据我采用的是开源 DEM 数据源常见的选项是 SRTM 和 ALOS。SRTM 的 30 米分辨率在哈密这种地貌反差大的区域表现尚可但如果需要更精细的峡谷、冲积扇等地形细节ALOS 的 12.5 米分辨率更好。拿到数据后不能直接用必须经过几个关键步骤。首先是坐标范围裁剪。哈密区域的大致范围在东经 91 度到 97 度、北纬 41 度到 45 度之间但这只是一个粗略的四边形。你从公开数据源下载的 DEM 往往是若干条带状的图幅文件需要用工具按你要的范围裁剪拼接成一张完整的 TIF。我在实际项目中使用的处理方式是用 GDAL 命令行做裁剪和重投影gdal_translate -projwin 91 45 97 41 -a_srs EPSG:4326 granule1.tif hami_dem_1.tif gdal_translate -projwin 91 45 97 41 -a_srs EPSG:4326 granule2.tif hami_dem_2.tif gdal_merge.py -o hami_dem_merged.tif hami_dem_1.tif hami_dem_2.tif-projwin后面的四个数字顺序是xmin ymax xmax ymin注意别看错。-a_srs EPSG:4326是为了强制把数据定义为 WGS84 经纬度坐标很多原始 DEM 自带投影信息但为了避免切图工具读不到元数据这里做一次显式声明更稳妥。接下来要用gdalwarp把 DEM 的像元分辨率统一成你需要的级别。我这次地形瓦片最高做到 16 级30 米分辨率的原始数据刚好够用再往上切也没意义纯属浪费存储空间和处理时间。处理完成后再转成 16 位整型或 32 位浮点型的单波段 GeoTIFF确保高度值不丢失。3.2 生成 Cesium 可识别的地形瓦片Cesium 不能直接加载 GeoTIFF它需要的是经过编码的地形瓦片格式专业术语叫 quantized-mesh。这种格式的瓦片金字塔和影像金字塔类似也是{z}/{x}/{y}三级目录但文件扩展名是.terrain并且在根目录有一个layer.json元数据文件描述瓦片的层级范围、投影信息等。切地形瓦片我采用的是开源地形切图工具核心原理是读入 DEM 影像按照指定的金字塔结构生成高程瓦片。切图命令大致如下。ctb-tile --output ./hami_terrain --terrain --format quantized-mesh --zoom 0-16 hami_dem_merged.tif切图完成后输出的目录结构应该是hami_terrain/ |-- layer.json |-- 0 | |-- 0 | | -- 0.terrain |-- 1 | |-- 0 | | -- 0.terrain |-- ... -- 16 |-- 3586 | -- 2543.terrain为什么 Cesium 1.19.11 能直接认这套格式因为它在底层实现了 quantized-mesh 1.0 解析。原来的 1.0 版本把每个地形瓦片的顶点按照四叉树细分然后用 16 位整型存储相对高度这样可以极大压缩体积。我特意确认过1.19.11 和这个地形格式的兼容性没有问题前提是你切图时一定要选 1.0 格式不要切那个带法线纹理扩展的新版 1.1 格式老引擎解析起来容易出问题。有一个切图时的操作细节值得留意原始 DEM 数据范围之外的那些区域会生成高度值为 0 的平坦瓦片。如果你在 Cesium 里加载后发现哈密区域边缘出现了一个大坑看起来像地陷了一样多半是这个问题。解决的办法是在切图前把 DEM 再向外扩一圈让边界外的区域也填上合理的高程值这样过渡会比较自然。3.3 地形瓦片发布与 Cesium 接入地形瓦片生成以后需要放到一个 HTTP 静态文件服务上。我用的是 nginx配置片段如下。server { listen 8080; server_name 192.168.1.100; location /hami_terrain/ { alias /data/terrain/; default_type application/vnd.quantized-meshoctet-stream; add_header Access-Control-Allow-Origin *; } location /hami_imagery/ { alias /data/imagery/; default_type image/png; add_header Access-Control-Allow-Origin *; } }default_type是必须写的一行。.terrain文件不是常见扩展名nginx 默认不认识会把它当application/octet-stream返回旧版 Cesium 对地形请求的响应媒体类型有校验类型不对就直接挂掉。写application/vnd.quantized-meshoctet-stream是标准做法实测下来 1.19.11 能正常解析。跨域头Access-Control-Allow-Origin *也是为开发方便加的。如果你的前端页面跑到另一台机器上而瓦片服务留在内网服务器跨域请求是少不了的。生产环境当然要收紧这个配置但开发调试阶段全放开才不容易被卡脖子。Cesium 侧加载地形的代码就更简单了。var terrainProvider new Cesium.CesiumTerrainProvider({ url : http://192.168.1.100:8080/hami_terrain }); viewer.terrainProvider terrainProvider; terrainProvider.readyPromise.then(function() { console.log(地形就绪最大级别: terrainProvider.maximumLevel); });这里注意url要指向发布目录的根路径不是layer.json的完整路径Cesium 会自己拼接layer.json去请求。如果你在浏览器里直接访问http://192.168.1.100:8080/hami_terrain/layer.json能看到一个 JSON 文件说明服务发布成功。3.4 镜头定位与高程夸张调整地形加载完成不是终点还得验证它和影像是否精确贴合。手动放大地图找到哈密区域太费事我习惯用相机飞行直接定位。viewer.camera.flyTo({ destination : Cesium.Cartesian3.fromDegrees(93.5, 42.8, 120000.0), orientation : { heading : 0, pitch : -Cesium.Math.PI_OVER_TWO, roll : 0 }, duration : 3 });飞到目标位置后如果地形和影像都正确你应该能看到哈密盆地的地貌轮廓——北部山体有明显的起伏南部平原地带相对平坦影像纹理贴合在山体表面。这时候还要检查一个参数高程夸张系数。Cesium 默认的高程缩放是 1.0意思是真实高程值不做放大。哈密这种区域整体海拔较高但相对高差并不是特别极端如果想让起伏更明显可以调高夸张系数。viewer.scene.globe.terrainExaggeration 1.5;但夸张系数调太高会有副作用——整个场景会变得“卡通化”视觉上非常假。我建议在 1.0 到 2.0 之间微调找到一个视觉舒服的点。4. 实操效果与联调优化4.1 影像与地形叠加后的渲染验证当影像和地形两个通道都正常工作后画面上的三维感会立刻显现出来。这时候我会做一组系统性检查确保叠加效果没有潜在问题。第一是看纹理贴合的姿态。当地形有起伏时影像纹理应该自然地包裹在山包上而不是像桌布一样平平地铺在半空中。如果你看到影像表面是平的、与地形的起伏脱节多半是terrainProvider没有赋值成功或者depthTestAgainstTerrain的设置导致半透明纹理把地形盖住了。第二是看细节层级。把镜头拉低到楼宇尺度观察地面纹理是否还是清晰的。如果到 15 级以上影像变得模糊说明切图级别不够需要回去补切瓦片或者考虑换更高效的纹理压缩方式。在没做任何影像金字塔扩展的情况下我这次切到 18 级基本满足了 15000 到 110000 尺度下的浏览需求。第三是看整体色调和范围过渡。哈密区域周边的戈壁滩、绿洲和山体在影像上有不同的色彩如果影像裁剪范围小于 DEM 范围边缘会出现一块无色区域。我在 3.2 节里提到过 DEM 外扩的问题影像同样要预留出一定范围的过渡带避免边界太生硬。4.2 性能优化与内存控制内网环境下性能问题同样不可忽视。老版本 Cesium 在低配工控机上跑起来很容易掉帧尤其是地形加载后顶点数量暴增对 GPU 的压榨很明显。我做了几个关键优化。第一是限定影像最大请求级别。maximumLevel定到 18但实际用户很少拉那么深。可以把默认最高级别设到 16只有滚轮放大到足够近时才请求更深层瓦片。这个 Cesium 会自动控制。第二是设置合理的瓦片缓存大小。TileMapServiceImageryProvider和UrlTemplateImageryProvider都使用内存内的瓦片缓存。在 1.19.11 里你可以通过这个属性控制缓存上限。viewer.scene.globe.tileCacheSize 512;这个属性不是越大越好。缓存越大重新浏览之前看过的区域时加载越快但内存占用也越高。我用 512 这个值在 8GB 内存的工控机上跑得很稳再往上就会开始吃紧。第三是关闭不必要的附加渲染。scene.requestRenderMode为 true 时画面静止时不再重复渲染只等有交互或数据请求时才重绘这在低功耗设备上非常有效。但要注意开启这个模式后偶尔会出现拖拽时画面滞后需要配合手动触发渲染的机制。viewer.scene.requestRenderMode false;我实际测试下来在交互频繁的场景里反而会卡所以默认保持 false只有在大屏展示这种几乎只做观赏的场景才考虑开启。4.3 离线环境里那些“隐形炸弹”老版本 Cesium 最坑人的地方就是离线环境下的隐性网络依赖。外网断开后Cesium 运行时依然尝试向在线服务请求资源导致各种不可预知的表现。先说几个最典型的。如果你直接new Cesium.Viewer(id)没有传任何地图参数新版会在后台请求 Cesium ion 的默认影像和地形。1.19.11 也是同样的逻辑它在没有显式指定imageryProvider时默认请求在线 Bing 影像。内网环境下这个请求会一直超时重试导致页面卡顿和黑屏。解决方法是初始化后立刻清掉默认图层再挂上自己的影像。var viewer new Cesium.Viewer(cesiumContainer, { imageryProvider : false }); viewer.imageryLayers.removeAll(); viewer.imageryLayers.addImageryProvider(tmsProvider); viewer.terrainProvider terrainProvider;另外一个隐性问题Cesium 默认会读取 Cesium ion 的 asset 访问凭据。即使你在代码里没显式调用它的一些内部模块也会尝试读取导致控制台报错。虽然不影响功能但在内网这种信息敏感环境里最好在构建打包时就把相关模块剪掉或者从代码层面屏蔽跟在线服务相关的默认行为。还有Cesium.createWorldTerrain这个 API 是老版本里推荐的在线地形方案离线环境下绝对不能调用。我见过一个同事没注意用createWorldTerrain加载地形结果整个外网断开后连页面都打不开排查了好久才发现是这里在拖后腿。4.4 跨域与访问控制细节内网项目里前端页面和瓦片服务经常不在同一台机器上。跨域请求的配置错了瓦片会全部被浏览器拦截。影像、地形、动态数据接口只要是从别的域名或端口拿数据跨域头都不能省。nginx 里我加了add_header Access-Control-Allow-Origin *;这是最宽松的配置。如果你能做到前后端同源部署可以不带跨域头但开发期不建议这么做因为浏览器地址栏用localhost访问和用局域网 IP 访问是两种不同的源切来切去容易出问题。浏览器层面还有一个绕不开的机制——同源策略下的file://协议限制。本地直接双击 HTML 文件打开 Cesium 页面时很多浏览器会禁止内部模块加载本地文件资源导致各种报错。所以我建议从一开始就养成用本地静态服务器访问页面的习惯比如python -m http.server 8080临时起一个服务或者直接用 nginx 统一发布。5. 问题排查与避坑实录5.1 高频问题速查表实际操作中遇到的问题五花八门我把高频问题整理成了一个速查表方便后续排查时对照。现象可能原因解决方案页面黑屏地球看不到默认在线影像离线请求超时或 imageryProvider 初始化失败初始化时imageryProvider:false再手动挂载本地影像影像图块错位、平移tilingScheme或 0 级切分数与实际瓦片不一致核对切图工具的坐标系和 0 级行列数影像上下颠倒瓦片 y 轴编号方向相反url 模板改用{reverseY}或将 TMS y 转 XYZ地形加载后是平的terrainProvider赋值失败或网址指向层级目录错误确认指向根目录且layer.json可访问哈密周边出现凹陷大坑DEM 边界区域高度值为 0切图前对 DEM 做外扩填充瓦片请求 404切图级别不足或者maximumLevel设置过大检查layer.json元数据里的最大级别控制台报 CORS 错误瓦片服务缺少跨域响应头nginx 添加Access-Control-Allow-Origin内存涨得飞快瓦片缓存过大或无限请求未限定层级调小tileCacheSize设定maximumLevel这张表解决了我 90% 的现场问题。剩下那 10% 基本都是环境差异导致的需要具体看报错信息来定位。5.2 三个“说多了都是泪”的教训第一教训坐标系混用是真坑。我的同事处理影像数据时用的是 CGCS2000 国家坐标系切出来的瓦片标注的是 EPSG:4326但实际投影参数完全不同。加载到 Cesium 里之后影像整体偏移了大概几百米山峰和纹理位置完全对不上。排查了很久才发现是原始数据投影被强制覆盖了。这种问题在视觉上不明显但一旦叠加矢量数据或做量测就会发现误差巨大。我的建议是切图前先gdalsrsinfo看一遍原始数据的真实投影别盲目用-a_srs覆盖。第二教训地形瓦片生成时必须选对格式。刚开始我切地形时用的是带 normal 扩展的 1.1 格式想着光照效果更细腻。结果加载进 1.19.11 后页面直接提示地形解析异常。换成标准的 quantized-mesh 1.0 后一切正常。老版本的地形解析器只实现了 1.0 规范任何多余的数据结构都会让它崩溃。所以如果你的项目被锁定在老版本引擎切地形时直接选 1.0别整那些花活。第三教训影像瓦片切太深是灾难。我最初想着把哈密区域切到 20 级将来放大看细节也清楚。结果切图跑了近一天硬盘占掉 200 多 GB加载速度反而变慢了。原因在于瓦片数量随级别指数级增长16 级已经够用的场景切到 20 级完全是浪费。后来我砍掉 17 级以上的瓦片磁盘占用少了 95%加载速度也明显改善。切图前先想清楚业务上最精细需要看什么尺度再倒推切到几级。5.3 一套可复用的排查流程面对新问题时别慌我摸索出一套适合老版本 Cesium 离线加载的排查流程。第一步看控制台报错区分是网络请求问题、JavaScript 异常还是资源解析问题。第二步直接访问瓦片 URL 和服务地址验证静态文件服务是否正常。第三步浏览layer.json内容核对元数据里写的投影、层级、范围是否符合预期。第四步关掉所有自定义图层只加载影像或只加载地形二分定位是哪一类数据出问题。这套流程走完绝大多数问题都能定位到根因。测本地瓦片时我还会用 Firefox 和 Chrome 各测一遍因为两个浏览器对 CORS 和媒体类型的容错机制有差异。Firefox 在 MIME 类型不对时会严格拦截Chrome 则相对宽松。如果你在 Chrome 里一切正常、Firefox 里一片白多半是Content-Type设置少了。写在最后的个人体会这套方案做完到现在稳定跑了几个月哈密区域的三维场景从最初的黑地球到最终的山脉起伏、影像清晰整个过程里最有价值的不是某段代码而是对老版本 Cesium 数据加载机制的理解。搞清楚它期望的瓦片目录、坐标系、格式规范和在线依赖你就掌握了在任何本地化三维项目里自由组合数据源的能力。后续如果想扩展可以在这个基础上加矢量图斑、做路径巡航、堆粒子特效思路都是同一套先把数据准备好再用 provider 接进去。希望这篇记录能帮到和我一样在旧版本引擎和离线环境里折腾三维场景的朋友。
