CesiumJS 离线部署完全指南切断外部数据源构建纯内网三维地球应用【免费下载链接】cesiumAn open-source JavaScript library for world-class 3D globes and maps :earth_americas:项目地址: https://gitcode.com/GitHub_Trending/ce/cesiumCesiumJS 默认会从 Cesium ion 等在线服务加载影像、地形与地理编码数据但这并非强制依赖。本指南基于 CesiumJS 官方离线指南结合本仓库源码系统梳理全部默认外部数据源、逐一给出替换或禁用方案并提供可直接复制的离线配置代码与本地静态资源服务搭建方法帮助你在无互联网的隔离内网环境中完整运行 CesiumJS 三维地球应用。CesiumJS 默认的联网依赖全景默认情况下CesiumJS 会在运行时访问多个外部数据源但它们都不是运行所必需的依赖。理解这些依赖藏在哪是构建离线应用的第一步依赖项默认数据源访问的域名/服务全球影像底图Cesium ion 全球影像当前为 Bing Mapsapi.cesium.com、dev.virtualearth.net及其多个virtualearth.net子域名瓦片服务器地形Cesium World Terrain可选未显式配置时默认启用api.cesium.com地理编码GeocoderCesium ion 地理编码 APIapi.cesium.comBaseLayerPicker 可选源一组示例在线影像与地形源api.cesium.com、OpenStreetMap 等仓库源码印证了这些默认行为createWorldImageryAsync.js 中createWorldImageryAsync通过IonImageryProvider.fromAssetId(style)创建默认全球影像其文档注释明确写着ions default global base imagery layer, currently Bing MapscreateWorldTerrainAsync.js 中createWorldTerrainAsync通过CesiumTerrainProvider.fromIonAssetId(1, ...)创建 Cesium World Terrain即 ion 资产 ID 为 1 的在线地形服务createDefaultImageryProviderViewModels.js 中默认的 BaseLayerPicker 列表包含了多个IonImageryProvider.fromAssetId(...)在线源以及OpenStreetMapImageryProvider在线源。这些默认行为都发生在你不做任何配置的前提下。离线部署的核心思路就是逐一切断或替换它们。第一步替换默认影像层从 Viewer 构造函数入手默认影像由Viewer构造函数自动创建。要换成离线可用的影像需要在构造Viewer时显式传入baseLayer选项。官方指南给出的对接方式如下const viewer new Cesium.Viewer(cesiumContainer, { baseLayer: Cesium.ImageryLayer.fromProviderAsync( Cesium.TileMapServiceImageryProvider.fromUrl( Cesium.buildModuleUrl(Assets/Textures/NaturalEarthII), ), ), baseLayerPicker: false, geocoder: false, });其中Cesium.buildModuleUrl(...)负责把相对路径解析为基于 Cesium 基础 URL 的绝对地址具体实现见 buildModuleUrl.js它优先使用 RequireJS 的require.toUrl否则基于自动探测或手动指定的 Cesium 基础 URL 派生资源地址。方案 A接入局域网影像服务器如果你在内网已有影像服务例如 WMS、ArcGIS Server、Google Earth Enterprise可以直接用对应的影像 Provider 替换默认底图。CesiumJS 内置了丰富的 Provider 类型常见的内网场景包括WebMapServiceImageryProvider标准 WMS 服务ArcGisMapServerImageryProviderArcGIS MapServer 服务TileMapServiceImageryProviderTMS 规范的瓦片服务离线瓦片包常用UrlTemplateImageryProvider任意 URL 模板规则的瓦片服务仓库 UrlTemplateImageryProvider.js 中也引用了NaturalEarthII相关能力。接入方式与内置示例一致构造对应的 Provider再包装成ImageryLayer传入baseLayer。方案 B使用仓库内置的 Natural Earth II 低分辨率影像如果内网没有任何影像服务CesiumJS 自带了 Natural Earth II 的低分辨率全球影像可直接作为底图。该资源位于仓库 packages/engine/Source/Assets/Textures/NaturalEarthII其目录结构是标准的 TMS 瓦片组织方式0/0/0.jpg、0/1/0.jpg等层级目录并带有tilemapresource.xml瓦片元数据描述文件因此可直接被TileMapServiceImageryProvider.fromUrl读取。使用它作为底图的完整写法即上一节示例代码所示。需要注意TileMapServiceImageryProvider.fromUrl返回的是 Promise因此要包在ImageryLayer.fromProviderAsync中等待异步创建完成这也是当前版本推荐的异步创建模式。第二步处理 BaseLayerPicker 可选源BaseLayerPicker是右上角切换底图的控件默认列出多个在线影像与地形源Cesium ion 资产、OpenStreetMap 等。在离线应用中它没有存在的意义处理方式有两种方式一彻底禁用控件在Viewer构造函数中传入baseLayerPicker: false控件将不会被创建const viewer new Cesium.Viewer(cesiumContainer, { baseLayerPicker: false, });方式二保留控件但替换为离线源如果仍然希望用户能切换底图/地形可以通过imageryProviderViewModels与terrainProviderViewModels两个选项把可选项换成你的离线 Provider 列表。这两个选项在 Viewer.js 的构造函数选项文档中有明确说明imageryProviderViewModelsBaseLayerPicker 中可选的影像 Provider 视图模型数组默认值为createDefaultImageryProviderViewModels()terrainProviderViewModels可选的默认地形 Provider 视图模型数组默认值同上。自定义示例仅保留一个离线底图选项const offlineImageryViewModel new Cesium.ProviderViewModel({ name: Natural Earth II (离线), iconUrl: Cesium.buildModuleUrl(Widgets/Images/ImageryProviders/naturalEarthII.png), tooltip: 内置的离线低分辨率全球影像, creationFunction: () Cesium.TileMapServiceImageryProvider.fromUrl( Cesium.buildModuleUrl(Assets/Textures/NaturalEarthII), ), }); const viewer new Cesium.Viewer(cesiumContainer, { baseLayerPicker: true, imageryProviderViewModels: [offlineImageryViewModel], terrainProviderViewModels: [], });对应地Viewer.js 中会使用options.imageryProviderViewModels ?? 默认值的方式读取这两个选项未提供时回落到包含大量在线源的默认列表——这正是离线应用必须显式覆盖它们的原因。注意ProviderViewModel的creationFunction中若使用在线资源如IonImageryProvider.fromAssetId离线环境下点击切换会失败务必全部替换为离线 Provider。第三步禁用 Geocoder 地理编码控件Geocoder控件支持搜索地址和地标并飞行定位但它依赖api.cesium.com的 Cesium ion 地理编码 API离线时必然失效。因此在离线应用中应当直接禁用它在Viewer构造函数中传入geocoder: false从源码看Viewer.js 中只有当options.geocoder未定义且不为false时才会创建Geocoder控件传入false后该控件完全不会出现在工具栏中也就不会发起任何对api.cesium.com的网络请求。完整离线配置示例综合以上三步一个完全规避在线数据源的Viewer初始化代码如下const viewer new Cesium.Viewer(cesiumContainer, { // 使用内置离线影像Natural Earth II替代默认的 Bing Maps 在线影像 baseLayer: Cesium.ImageryLayer.fromProviderAsync( Cesium.TileMapServiceImageryProvider.fromUrl( Cesium.buildModuleUrl(Assets/Textures/NaturalEarthII), ), ), // 禁用底图切换控件其默认列表包含在线源 baseLayerPicker: false, // 禁用依赖 Cesium ion 在线 API 的地理编码控件 geocoder: false, // 若未配置离线地形可显式关闭默认地形或替换为本地地形服务 // terrainProvider: Cesium.CesiumTerrainProvider.fromUrl(...) });这段代码同时完成了三件事替换影像、关闭 BaseLayerPicker、关闭 Geocoder是与本指南主题最直接对应的离线最小化配置。若还需要地形可通过terrainProvider选项传入内网地形服务如CesiumTerrainProvider.fromUrl不要使用默认的createWorldTerrainAsync()即 ion 资产 1 的在线世界地形。第四步搭建本地静态资源服务器为什么必须用 HTTP 服务器3D Tiles、glTF 等绝大多数 CesiumJS 加载的文件都是静态资源加载过程不需要任何服务器端计算。但浏览器通常会把file://协议下的资源请求视为跨域请求cross-origin request而拒绝因此直接双击 HTML 文件用file://打开无法正常加载 3D Tiles、模型等数据官方指南明确建议搭建一个本地 HTTP 服务器。使用 http-server 搭建按以下步骤即可完成以 Node.js 生态为例安装 Node.js下载并安装 Node.js安装完成后node -v可验证版本全局安装 http-servernpm install http-server -g在数据所在目录启动服务器http-server -a localhost -p 8003 --corshttp://localhost:8080/参数含义-a localhost指定监听地址为本机-p 8003指定端口为 8003--corshttp://localhost:8080/允许运行在 8080 端口的 CesiumJS 应用跨域访问该服务器上的数据。在 CesiumJS 应用中通过 URL 加载数据。例如数据目录下有一个example目录内含本地瓦片集加载方式如下try { const tileset await Cesium.Cesium3DTileset.fromUrl( http://localhost:8003/example/tileset.json, ); viewer.scene.primitives.add(tileset); } catch (error) { console.log(Error loading tileset: ${error}); }加载成功后Cesium3DTileset.fromUrl返回的瓦片集会异步请求tileset.json描述文件中列出的所有瓦片与内容文件这些请求同样只需静态文件服务器即可满足不涉及任何在线服务。其他本地服务器选项http-server只是最便捷的选项之一。任何能提供静态文件服务的 HTTP 服务器都可以胜任例如python3 -m http.server、nginx、或者 CesiumJS 仓库自带的开发服务器仓库根目录的 server.js 提供了带 MIME 与缓存控制的静态服务实现可通过node server.js方式启动。关键点只有一个应用页面与数据必须通过 HTTP(S) 协议访问且服务端允许跨域或同源请求。进阶资源路径与 CESIUM_BASE_URL离线部署时CesiumJS 自身脚本、Assets目录内置影像、着色器等、Workers目录Web Worker 脚本等静态资源的定位也值得注意。CesiumJS 会自动探测基础 URL但若打包或迁移导致自动探测失败可以通过全局变量CESIUM_BASE_URL显式指定。从 buildModuleUrl.js 的源码可见其解析顺序若定义了全局变量CESIUM_BASE_URL直接使用它作为基础 URLESM 环境下依据import.meta.url推导AMDRequireJS环境下通过require.toUrl解析IIFE 打包环境下从页面中引用Cesium.js的script标签地址推导。// 在引入 Cesium.js 之前设置 window.CESIUM_BASE_URL /cesium/;内置的 Natural Earth II 影像之所以能用Cesium.buildModuleUrl(Assets/Textures/NaturalEarthII)定位正是因为该路径是相对 Cesium 基础 URL 的。离线部署时务必确保Assets/、Workers/、Widgets/等目录随应用一同部署且与CESIUM_BASE_URL指向一致。离线环境的验证清单完成上述配置后可用以下清单逐项确认离线运行就绪Viewer构造时传入了baseLayer本地或内置影像未依赖默认的 Bing Maps/ion 影像baseLayerPicker为false或imageryProviderViewModels/terrainProviderViewModels已替换为离线源geocoder为false页面不会请求api.cesium.com地形使用本地terrainProvider未调用createWorldTerrainAsync()应用与数据均通过本地 HTTP 服务器访问未使用file://浏览器开发者工具 Network 面板中不存在对api.cesium.com、*.virtualearth.net等外域域名的请求。满足以上全部条件CesiumJS 即可在完全断网的隔离网络中稳定运行——这一定位同样适用于涉密内网、专网机房、离线展示终端等不允许访问公网的业务场景。本指南所对应的原始离线部署说明位于仓库 Documentation/OfflineGuide/README.md其中涉及的外部链接如 Node.js 下载页、http-server 项目主页、CesiumJS 参考文档建议在可联网环境下按需查阅文中所有离线配置与源码依据均可直接在本仓库中验证。【免费下载链接】cesiumAn open-source JavaScript library for world-class 3D globes and maps :earth_americas:项目地址: https://gitcode.com/GitHub_Trending/ce/cesium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考