WebGIS

Cesium 实例教程：常用三维场景与代码示例

2026-11-11 WebGIS

wowwwai GIS研习社 · 工具流程与项目排障

Cesium 常用三维场景实例，核心就是用 Viewer 拉起带全球地形的地球，再叠加 OSM Buildings 或 Photorealistic 3D Tiles、Entity 多边形/折线/模型，并用相机 flyTo 定位。这些场景用 Entity API 或 createOsmBuildingsAsync 等几行代码就能跑通，适合 GIS 动态数据可视化。截至 2026 年 11 月，推荐基于 CesiumJS 1.147 编写；本文只给高频场景的可执行写法与验收要点，方便直接粘贴调试。

基本 Viewer、地形与相机飞行怎么写

先解决“地球有没有起伏、镜头怎么飞过去”的问题。默认 Viewer 只显示 WGS84 椭球；加上 Cesium World Terrain 后才有真实高程。相机用 flyTo 指定经纬度高度和朝向即可。

设置 Ion 访问令牌（生产环境必须换成自己的，默认 demo token 仅限测试）。
创建 Viewer，开启 fromWorldTerrain；可选 requestVertexNormals 与 requestWaterMask 增强光照和水面。
调用 camera.flyTo，destination 用 Cartesian3.fromDegrees(经度, 纬度, 高度)，orientation 控制 heading/pitch。

示例代码（可直接放到页面脚本里）：

Cesium.Ion.defaultAccessToken = “your_access_token”; const viewer = new Cesium.Viewer(“cesiumContainer”, { terrain: Cesium.Terrain.fromWorldTerrain({ requestVertexNormals: true, requestWaterMask: true }) }); viewer.scene.globe.enableLighting = true; viewer.camera.flyTo({ destination: Cesium.Cartesian3.fromDegrees(-122.4175, 37.655, 400), orientation: { heading: Cesium.Math.toRadians(0.0), pitch: Cesium.Math.toRadians(-15.0) } });

验收标准：地球表面有起伏阴影，镜头平滑飞到目标点且俯仰角正确。若无 token，地形加载会失败，需改用自托管瓦片或关闭默认 ion 资源。更完整的 Fundamentals 与 Quickstart 说明见 CesiumJS 官方学习路径。

如何叠加 OSM Buildings 与 Photorealistic 3D Tiles

建筑和实景是三维场景里最直观的一层。OSM Buildings 提供全球矢量建筑，Google Photorealistic 3D Tiles 则是照片级瓦片；两者都走 3D Tiles，加到 scene.primitives 即可。

OSM Buildings：const buildingTileset = await Cesium.createOsmBuildingsAsync(); viewer.scene.primitives.add(buildingTileset);
Photorealistic：await Cesium.createGooglePhotorealistic3DTileset()，通常建议关闭默认 globe 影像，并配合 Google geocoder。
注意异步：必须 await，否则 tileset 未就绪就 add 会报错。
性能：大城市区域先缩小视野或设置 maximumScreenSpaceError，避免一次加载过多瓦片导致卡顿。

常见搭配是地形 + OSM Buildings，再 flyTo 城市中心。若只做示意、不依赖 ion，可换成自托管 3D Tiles 服务。加载成功后，建筑物应随地形贴合，点击可选中要素（需开启 feature picking）。

CesiumJS 官方下载页，可查看 1.147 版本与资源包（截图来源：cesium.com）

Entity API：多边形、折线与模型怎么加

Entity 是高层数据驱动接口，适合点、线、面、体积和 glTF 模型，比直接写 Primitive 更省事。多边形用 hierarchy + material，折线用 polyline，模型用 model.uri 指向 glb/glTF。

多边形示例（怀俄明州示意）：

const wyoming = viewer.entities.add({ polygon: { hierarchy: Cesium.Cartesian3.fromDegreesArray([经度1, 纬度1, 经度2, 纬度2, …]), height: 0, material: Cesium.Color.RED.withAlpha(0.5), outline: true, outlineColor: Cesium.Color.BLACK } }); viewer.zoomTo(wyoming);

折线：entities.add({ polyline: { positions: Cesium.Cartesian3.fromDegreesArrayHeights([…]), width: 5, material: Cesium.Color.YELLOW } })
模型：entities.add({ position: Cesium.Cartesian3.fromDegrees(lon, lat, height), model: { uri: “path/to/model.glb”, scale: 1.0 } })
还支持 box、ellipse、corridor、cylinder、rectangle、ellipsoid、wall 等；材料可用 Color、ImageMaterialProperty 等。

坐标一律用经纬度度数再转 Cartesian3；height 为相对椭球高。写完用 zoomTo 或 flyTo 验收。官方 Creating Entities 教程对每种形状有更细参数说明，见 Creating Entities 官方教程。

场景元素	主要 API	典型用途	注意事项
全球地形	Terrain.fromWorldTerrain()	真实高程、光照水面	需 Ion token；可加 vertexNormals
OSM 建筑	createOsmBuildingsAsync()	城市矢量楼块	异步加载；控制屏幕误差
多边形/折线	viewer.entities.add	区域标注、路径	fromDegreesArray 坐标顺序
三维模型	entity.model.uri	设备、建筑单体	glb/glTF；注意缩放与朝向

相机控制与场景稳定性要注意什么

相机写错最容易出现“飞到地下”或“黑屏”。destination 高度过低会穿模；pitch 接近 -90° 时接近垂直俯视。复杂场景建议：

开启 globe.enableLighting，并保证地形请求了法线。
大数据集时限制 camera 的 minimumZoomDistance / maximumZoomDistance。
浏览器需支持 WebGL（推荐 WebGL 2），最新 Chrome、Edge、Firefox（≥115）、Safari；集成显卡能跑但帧率偏低，复杂 3D Tiles 建议独显。
模块打包时设置 window.CESIUM_BASE_URL，并正确复制 Workers、Assets、Widgets 等静态目录，否则 Worker 报错。

CesiumJS 1.147（2026 年 11 月 2 日发布）增强了部分 glTF 材质扩展与 ion 资产查询能力，视觉与性能 bug 也有修复，示例代码在 1.145～1.147 间一般可直接复用。

常见问题

为什么地形或建筑加载不出来？

最常见是 Ion token 无效或未设置。把 Cesium.Ion.defaultAccessToken 换成自己账户的 token，并确认网络能访问 ion 服务；无 token 时需改用开源瓦片并关闭默认 World Terrain。

Entity 多边形显示位置不对怎么办？

检查 fromDegreesArray 的经纬度顺序与闭合情况，height 是否设为 0 或合理海拔；用 viewer.zoomTo(entity) 确认包围盒，必要时打印 Cartesian3 坐标核对。

页面白屏或 WebGL 报错怎么排查？

先打开 https://get.webgl.org/ 确认立方体能旋转；关闭浏览器硬件加速再开；检查 CESIUM_BASE_URL 与 widgets.css 是否正确引入。仍失败时换最新版 Chrome 并清缓存。

本地跑 Sandcastle 示例报 CORS 怎么办？

自托管数据必须配置 CORS；开发阶段可用本地静态服务器，生产环境把瓦片与模型放到同域或正确配置 Access-Control-Allow-Origin。

常用三维场景先从 Viewer + World Terrain + flyTo 打底，再叠加 OSM Buildings 或 Entity 多边形/模型，最后用 zoomTo 验收。建议先在官方示例环境验证坐标与 token，再拷贝到项目；生产环境务必使用自有 Ion token，并按数据量调节 maximumScreenSpaceError 以保证流畅。