Cesium三维WebGIS入门详解
浏览器端三维 GIS 要同时回答两件事：地球与地理坐标如何呈现 ，以及 大体量模型与矢量如何流畅渲染 。底层几乎都落在 WebGL ；上层框架里，面向「三维地球 / WebGIS」生态最完整、二次封装最多的是 Cesium。下文从 WebGL 与周边引擎选型切入，再落到 Cesium 的引用方式、核心类与数据加载思路------以《WebGIS 开发从入门到实践》三维篇笔记为纲并扩写。
目录
- [三维 WebGIS 在解决什么问题](#三维 WebGIS 在解决什么问题)
- WebGL：浏览器三维的底座
- [Web 三维框架怎么选](#Web 三维框架怎么选)
- [为什么 WebGIS 常选 Cesium](#为什么 WebGIS 常选 Cesium)
- [Cesium 如何引入工程](#Cesium 如何引入工程)
- 核心类与对象关系
- 交互、实体与数据源
- 落地清单与常见坑
- 延伸阅读
1. 三维 WebGIS 在解决什么问题
二维 Web 地图（瓦片 + 矢量叠加）擅长「平面位置与属性」；三维 WebGIS 额外要处理更多能力，也要付更多代价：
| 能力 | 含义 | 代价 / 门槛 |
|---|---|---|
| 地形 / 椭球 | 高程、曲率、全球尺度漫游 | 地形服务带宽与高精度 DEM 成本；弱设备掉帧 |
| 倾斜摄影 / BIM / 模型 | OSGB、3D Tiles、glTF 等上屏 | 预处理管线重（切片、坐标系、LOD）；存储与 CDN 压力大 |
| 时序与相机 | 飞行、日照、轨迹回放 | 状态机与交互复杂度上升；易与 UI 抢控制权 |
| 与二维数据互通 | GeoJSON、KML、WMS/WMTS 等 | 二维/三维双引擎时坐标与相机同步成本 |
| （共性） | 浏览器真三维 | WebGL 兼容性、首包体积、GPU 占用；低端 WebView 常直接劝退 |
决策时不要只看「三维能不能做」，要问：数据是否已有 3D Tiles/glTF 管线、用户设备是否扛得住、是否值得维护一套地球内核。很多业务继续用二维地图 + 局部 Three.js 弹窗就够。
工程上常见路径：业务二维地图（Mapbox / 高德 / Leaflet 等）+ 需要真三维时切 Cesium（或基于 Cesium 的商业封装）；纯可视化大屏也可能用 Three.js / deck.gl / L7，不一定上「地球内核」。
#mermaid-svg-Y3z1a4yfIUGzkAoG{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-Y3z1a4yfIUGzkAoG .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-Y3z1a4yfIUGzkAoG .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-Y3z1a4yfIUGzkAoG .error-icon{fill:#552222;}#mermaid-svg-Y3z1a4yfIUGzkAoG .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-Y3z1a4yfIUGzkAoG .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-Y3z1a4yfIUGzkAoG .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-Y3z1a4yfIUGzkAoG .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-Y3z1a4yfIUGzkAoG .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-Y3z1a4yfIUGzkAoG .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-Y3z1a4yfIUGzkAoG .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-Y3z1a4yfIUGzkAoG .marker{fill:#333333;stroke:#333333;}#mermaid-svg-Y3z1a4yfIUGzkAoG .marker.cross{stroke:#333333;}#mermaid-svg-Y3z1a4yfIUGzkAoG svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-Y3z1a4yfIUGzkAoG p{margin:0;}#mermaid-svg-Y3z1a4yfIUGzkAoG .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-Y3z1a4yfIUGzkAoG .cluster-label text{fill:#333;}#mermaid-svg-Y3z1a4yfIUGzkAoG .cluster-label span{color:#333;}#mermaid-svg-Y3z1a4yfIUGzkAoG .cluster-label span p{background-color:transparent;}#mermaid-svg-Y3z1a4yfIUGzkAoG .label text,#mermaid-svg-Y3z1a4yfIUGzkAoG span{fill:#333;color:#333;}#mermaid-svg-Y3z1a4yfIUGzkAoG .node rect,#mermaid-svg-Y3z1a4yfIUGzkAoG .node circle,#mermaid-svg-Y3z1a4yfIUGzkAoG .node ellipse,#mermaid-svg-Y3z1a4yfIUGzkAoG .node polygon,#mermaid-svg-Y3z1a4yfIUGzkAoG .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-Y3z1a4yfIUGzkAoG .rough-node .label text,#mermaid-svg-Y3z1a4yfIUGzkAoG .node .label text,#mermaid-svg-Y3z1a4yfIUGzkAoG .image-shape .label,#mermaid-svg-Y3z1a4yfIUGzkAoG .icon-shape .label{text-anchor:middle;}#mermaid-svg-Y3z1a4yfIUGzkAoG .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-Y3z1a4yfIUGzkAoG .rough-node .label,#mermaid-svg-Y3z1a4yfIUGzkAoG .node .label,#mermaid-svg-Y3z1a4yfIUGzkAoG .image-shape .label,#mermaid-svg-Y3z1a4yfIUGzkAoG .icon-shape .label{text-align:center;}#mermaid-svg-Y3z1a4yfIUGzkAoG .node.clickable{cursor:pointer;}#mermaid-svg-Y3z1a4yfIUGzkAoG .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-Y3z1a4yfIUGzkAoG .arrowheadPath{fill:#333333;}#mermaid-svg-Y3z1a4yfIUGzkAoG .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-Y3z1a4yfIUGzkAoG .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-Y3z1a4yfIUGzkAoG .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Y3z1a4yfIUGzkAoG .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-Y3z1a4yfIUGzkAoG .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Y3z1a4yfIUGzkAoG .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-Y3z1a4yfIUGzkAoG .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-Y3z1a4yfIUGzkAoG .cluster text{fill:#333;}#mermaid-svg-Y3z1a4yfIUGzkAoG .cluster span{color:#333;}#mermaid-svg-Y3z1a4yfIUGzkAoG div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-Y3z1a4yfIUGzkAoG .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-Y3z1a4yfIUGzkAoG rect.text{fill:none;stroke-width:0;}#mermaid-svg-Y3z1a4yfIUGzkAoG .icon-shape,#mermaid-svg-Y3z1a4yfIUGzkAoG .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Y3z1a4yfIUGzkAoG .icon-shape p,#mermaid-svg-Y3z1a4yfIUGzkAoG .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-Y3z1a4yfIUGzkAoG .icon-shape .label rect,#mermaid-svg-Y3z1a4yfIUGzkAoG .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Y3z1a4yfIUGzkAoG .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-Y3z1a4yfIUGzkAoG .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-Y3z1a4yfIUGzkAoG :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 三维地球 / BIM / 倾斜摄影
通用 3D 场景 / 游戏感
地理大数据可视化
图表型三维
业务应用
需求重心?
Cesium 系
Three.js / Babylon.js
deck.gl / L7
ECharts GL
2. WebGL：浏览器三维的底座
WebGL（Web Graphics Library） 是基于 OpenGL ES 的 JavaScript API，把三维绘制接到 HTML5 Canvas ，并走 GPU 加速。浏览器无插件即可渲染三维场景与模型，但页面必须跑在 支持 WebGL 的环境（多数现代桌面浏览器可用；部分嵌入式 WebView 需实测）。
对开发者而言：
- 直接写 WebGL：灵活，但缓冲、着色器、矩阵、资源管理成本高。
- 引擎 / 框架 ：封装场景图、相机、材质、加载器；WebGIS 框架再叠一层 地理投影、地形、瓦片、时间轴。
Cesium、Three.js、deck.gl、L7 等最终都建立在 WebGL（或其演进路径）之上。
3. Web 三维框架怎么选
笔记中列举的引擎可按「问题域」粗分，而不是比谁「更三维」。
| 框架 | 定位 | 更适合 | 相对短板 |
|---|---|---|---|
| Three.js | 通用浏览器三维引擎 | 产品可视化、展厅、自定义场景 | 不自带全球 GIS 栈 |
| Babylon.js | 偏应用 / 游戏向的 WebGL 框架 | 交互复杂的 3D 应用 | 同样不是地球 GIS 专用 |
| PlayCanvas | 带编辑器的游戏引擎 | 强交互、音效物理一体的场景 | 学习与部署偏游戏管线 |
| ECharts GL | ECharts 的三维图表扩展 | 已有 ECharts 的三维统计图 | 不是完整 GIS 地球 |
| deck.gl | Uber 开源的 WebGL 地理大数据可视化 | 海量点线面图层、与地图底图组合 | 地球级倾斜摄影 / BIM 非主场 |
| harp.gl | TypeScript 实验性三维地图渲染 | 跟进 HERE 地图渲染实验 | 生态与文档相对小众 |
| L7 | AntV 大规模地理空间可视分析 | 符号化表达、与高德 / Mapbox GL 结合 | 重「可视分析」而非完整 Cesium 式地球内核 |
| Cesium | 三维地球与地图的 JS 库 | 全球地形、3D Tiles、时序、WebGIS 二次开发底座 | 包体与概念面较广，需按模块裁剪 |
选型口诀：要「地球 + 地理数据 + 倾斜/BIM」→ Cesium 系；要「炫酷地理大数据图层」→ deck.gl / L7；要「任意 3D 物体与材质」→ Three.js / Babylon。
4. 为什么 WebGIS 常选 Cesium
Cesium 是跨平台、跨浏览器的 三维地球 / 地图 JavaScript 库，基于 WebGL 硬件加速，Apache 2.0，可商用。产业里大量三维 WebGIS 产品在其开源内核上再封装（如超图 SuperMap iClient3D for Cesium、火星科技 mars3d 等）。
| 能力点 | 说明 |
|---|---|
| 模型 | OBJ、glTF；OSGB / BIM / MAX / SKP 等常 转为 3D Tiles 后加载 |
| 矢量 / 标注数据 | GeoJSON、Shapefile、KML 等（经加载器进入场景） |
| 生态 | 文档、示例、社区案例相对丰富 |
| 扩展 | 商业与开源二次封装多，便于接国内底图与业务组件 |
它解决的是「在浏览器里把地球和地理三维资产跑起来」，而不是替代所有 Three.js 场景。
5. Cesium 如何引入工程
常见两种方式：
5.1 静态包 + script
从官方发行包下载后，用 <script> 引入构建产物，适合简单演示页或非打包老项目。
5.2 npm + 现代前端工程
bash
npm install cesium -S若使用 Vite，通常还需：
bash
npm i vite-plugin-cesium -D并在 vite.config.js 中启用 Cesium 相关插件配置（静态资源、Worker、WASM 等路径由插件处理）。
Webpack 没有 Vite 插件那层「开箱拷资源」时，经典坑是：编译成功，运行期 Assets / Workers 404 。实务上通常要用 copy-webpack-plugin （或等价手段）把 Cesium 的 Assets、Workers、ThirdParty 等拷到输出目录，并正确设置 CESIUM_BASE_URL / 公共路径；只改 resolve.alias 往往不够。细节随 Cesium 与 Webpack 大版本变化，以官方 Webpack 示例为准，但「必须显式处理静态资源」这条很少变。
注意：Cesium 资源体积不小（Workers、Assets、第三方库）；生产环境应按需加载影像/地形 Provider，避免首屏拉全量样例数据。
6. 核心类与对象关系
笔记列出的核心概念：Viewer、Scene、ScreenSpaceEventHandler、CesiumWidget、Entity、Camera、DatasourceCollection。可先建立如下关系：
#mermaid-svg-SEg0qK9zRvEn7eVC{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-SEg0qK9zRvEn7eVC .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-SEg0qK9zRvEn7eVC .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-SEg0qK9zRvEn7eVC .error-icon{fill:#552222;}#mermaid-svg-SEg0qK9zRvEn7eVC .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-SEg0qK9zRvEn7eVC .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-SEg0qK9zRvEn7eVC .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-SEg0qK9zRvEn7eVC .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-SEg0qK9zRvEn7eVC .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-SEg0qK9zRvEn7eVC .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-SEg0qK9zRvEn7eVC .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-SEg0qK9zRvEn7eVC .marker{fill:#333333;stroke:#333333;}#mermaid-svg-SEg0qK9zRvEn7eVC .marker.cross{stroke:#333333;}#mermaid-svg-SEg0qK9zRvEn7eVC svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-SEg0qK9zRvEn7eVC p{margin:0;}#mermaid-svg-SEg0qK9zRvEn7eVC .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-SEg0qK9zRvEn7eVC .cluster-label text{fill:#333;}#mermaid-svg-SEg0qK9zRvEn7eVC .cluster-label span{color:#333;}#mermaid-svg-SEg0qK9zRvEn7eVC .cluster-label span p{background-color:transparent;}#mermaid-svg-SEg0qK9zRvEn7eVC .label text,#mermaid-svg-SEg0qK9zRvEn7eVC span{fill:#333;color:#333;}#mermaid-svg-SEg0qK9zRvEn7eVC .node rect,#mermaid-svg-SEg0qK9zRvEn7eVC .node circle,#mermaid-svg-SEg0qK9zRvEn7eVC .node ellipse,#mermaid-svg-SEg0qK9zRvEn7eVC .node polygon,#mermaid-svg-SEg0qK9zRvEn7eVC .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-SEg0qK9zRvEn7eVC .rough-node .label text,#mermaid-svg-SEg0qK9zRvEn7eVC .node .label text,#mermaid-svg-SEg0qK9zRvEn7eVC .image-shape .label,#mermaid-svg-SEg0qK9zRvEn7eVC .icon-shape .label{text-anchor:middle;}#mermaid-svg-SEg0qK9zRvEn7eVC .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-SEg0qK9zRvEn7eVC .rough-node .label,#mermaid-svg-SEg0qK9zRvEn7eVC .node .label,#mermaid-svg-SEg0qK9zRvEn7eVC .image-shape .label,#mermaid-svg-SEg0qK9zRvEn7eVC .icon-shape .label{text-align:center;}#mermaid-svg-SEg0qK9zRvEn7eVC .node.clickable{cursor:pointer;}#mermaid-svg-SEg0qK9zRvEn7eVC .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-SEg0qK9zRvEn7eVC .arrowheadPath{fill:#333333;}#mermaid-svg-SEg0qK9zRvEn7eVC .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-SEg0qK9zRvEn7eVC .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-SEg0qK9zRvEn7eVC .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-SEg0qK9zRvEn7eVC .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-SEg0qK9zRvEn7eVC .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-SEg0qK9zRvEn7eVC .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-SEg0qK9zRvEn7eVC .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-SEg0qK9zRvEn7eVC .cluster text{fill:#333;}#mermaid-svg-SEg0qK9zRvEn7eVC .cluster span{color:#333;}#mermaid-svg-SEg0qK9zRvEn7eVC div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-SEg0qK9zRvEn7eVC .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-SEg0qK9zRvEn7eVC rect.text{fill:none;stroke-width:0;}#mermaid-svg-SEg0qK9zRvEn7eVC .icon-shape,#mermaid-svg-SEg0qK9zRvEn7eVC .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-SEg0qK9zRvEn7eVC .icon-shape p,#mermaid-svg-SEg0qK9zRvEn7eVC .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-SEg0qK9zRvEn7eVC .icon-shape .label rect,#mermaid-svg-SEg0qK9zRvEn7eVC .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-SEg0qK9zRvEn7eVC .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-SEg0qK9zRvEn7eVC .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-SEg0qK9zRvEn7eVC :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} Viewer 场景壳
CesiumWidget
Scene 场景图
Globe 地球
Camera
primitives
Entity / DataSource
ScreenSpaceEventHandler
imageryLayers
terrainProvider
6.1 Viewer
Viewer 是最常用的入口组件：创建并管理三维场景所需的基本能力------加载模型与影像、叠图层、设置相机、处理输入等。创建时绑定页面中的容器（通常是一个 div，内部使用 Canvas 呈现）。之后通过 API 添加实体、图层并驱动相机。
多数业务项目从 new Cesium.Viewer(container, options) 起步；可用 options 关掉不需要的底图控件、动画条等以减负。
6.2 Scene
Scene 是三维图形对象的容器（对应 Canvas 上的场景），由 Viewer 或 CesiumWidget 内部创建。通过 Scene 可触及例如：
| 成员 / 概念 | 作用 |
|---|---|
| Globe | 地球球体 |
| imageryLayers | 影像底图层 |
| terrainProvider | 地形 |
| camera | 相机 |
| skyBox / sun / moon | 天空盒与天体 |
| primitives | 偏底层的图元集合 |
| postProcessStages | 后处理效果 |
理解 Scene，有助于区分「改地球表现」和「改相机/后处理」。
6.3 CesiumWidget 与 Viewer
CesiumWidget 是「带 Cesium 场景的轻量部件」，与 Scene 为包含关系。它与 Viewer 在用法上常被看作两种入口：二者都能拉起三维地球；Viewer 更「全家桶」（控件、默认帮助、数据源管理等更全），CesiumWidget 更精简，适合深度定制 UI 的壳。
6.4 Camera
Camera 控制视图：旋转、缩放、平移、flyTo 飞入等。Cesium 内置鼠标与触摸交互；也可用 API 编程控制。业务里常见需求是「定位到某经纬高 + 朝向」和「沿路径漫游」。
flyTo 相关坑放到 §8；实现 POI 连点时务必考虑取消上一次飞行。
6.5 Entity：先会用，再知道何时不用
Entity 是偏业务的高级对象：把可视化与属性收进统一结构，关注「展示什么数据」。适合点线面标注、随时间变化的样式、与属性面板绑定的业务图层。
什么时候不该（只）用 Entity
| 场景 | 更合适的方向 |
|---|---|
| 海量静态点（十万级+）频繁刷新 | Primitive / PointPrimitive / 聚合，或抽稀 |
| 城市级倾斜摄影、大型 BIM | 3D Tiles，不要拆成巨量 Entity |
| 需要极致合批、自定义 shader | 下沉到 Primitive / 自定义外观 |
| 一次性加载巨大 glTF 且无明显 LOD | 先做切片或减面，而不是堆 Entity |
入门与多数业务叠加层仍优先 Entity；性能问题出现时，再按上表降级，而不是一上来就写底层 API。
7. 交互、实体与数据源
7.1 ScreenSpaceEventHandler
用于屏幕空间输入：单击、右击、双击、移动、滚轮等。典型流程是监听事件 → scene.pick / 拾取笛卡尔或地理坐标 → 高亮实体或弹出属性。
| 意图 | 事件类型（现行 API） |
|---|---|
| 单击 | ScreenSpaceEventType.LEFT_CLICK |
| 移动 | ScreenSpaceEventType.MOUSE_MOVE |
| 滚轮 | ScreenSpaceEventType.WHEEL |
旧资料或读书笔记里常见的 MOUSE_CLICK 属于过时/不准确写法 ，以当前文档中的 LEFT_CLICK 等为准。实现拾取时还要注意：地形深度检测、被模型遮挡、以及移动端触摸与鼠标差异。
7.2 Entity 与数据如何进场景
Entity 的定位见 §6.5。矢量进场景时，多数数据源最终仍落到 Entity（或对应图元）上参与渲染与拾取。
7.3 DatasourceCollection
DatasourceCollection 管理可挂接的数据源（如 CZML、GeoJSON、KML 等）。不同格式是 输入形态 差异；进入 Cesium 后，多数仍落到 Entity 集合上。
#mermaid-svg-gQw41Xal27RDw3UL{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-gQw41Xal27RDw3UL .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-gQw41Xal27RDw3UL .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-gQw41Xal27RDw3UL .error-icon{fill:#552222;}#mermaid-svg-gQw41Xal27RDw3UL .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-gQw41Xal27RDw3UL .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-gQw41Xal27RDw3UL .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-gQw41Xal27RDw3UL .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-gQw41Xal27RDw3UL .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-gQw41Xal27RDw3UL .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-gQw41Xal27RDw3UL .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-gQw41Xal27RDw3UL .marker{fill:#333333;stroke:#333333;}#mermaid-svg-gQw41Xal27RDw3UL .marker.cross{stroke:#333333;}#mermaid-svg-gQw41Xal27RDw3UL svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-gQw41Xal27RDw3UL p{margin:0;}#mermaid-svg-gQw41Xal27RDw3UL .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-gQw41Xal27RDw3UL .cluster-label text{fill:#333;}#mermaid-svg-gQw41Xal27RDw3UL .cluster-label span{color:#333;}#mermaid-svg-gQw41Xal27RDw3UL .cluster-label span p{background-color:transparent;}#mermaid-svg-gQw41Xal27RDw3UL .label text,#mermaid-svg-gQw41Xal27RDw3UL span{fill:#333;color:#333;}#mermaid-svg-gQw41Xal27RDw3UL .node rect,#mermaid-svg-gQw41Xal27RDw3UL .node circle,#mermaid-svg-gQw41Xal27RDw3UL .node ellipse,#mermaid-svg-gQw41Xal27RDw3UL .node polygon,#mermaid-svg-gQw41Xal27RDw3UL .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-gQw41Xal27RDw3UL .rough-node .label text,#mermaid-svg-gQw41Xal27RDw3UL .node .label text,#mermaid-svg-gQw41Xal27RDw3UL .image-shape .label,#mermaid-svg-gQw41Xal27RDw3UL .icon-shape .label{text-anchor:middle;}#mermaid-svg-gQw41Xal27RDw3UL .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-gQw41Xal27RDw3UL .rough-node .label,#mermaid-svg-gQw41Xal27RDw3UL .node .label,#mermaid-svg-gQw41Xal27RDw3UL .image-shape .label,#mermaid-svg-gQw41Xal27RDw3UL .icon-shape .label{text-align:center;}#mermaid-svg-gQw41Xal27RDw3UL .node.clickable{cursor:pointer;}#mermaid-svg-gQw41Xal27RDw3UL .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-gQw41Xal27RDw3UL .arrowheadPath{fill:#333333;}#mermaid-svg-gQw41Xal27RDw3UL .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-gQw41Xal27RDw3UL .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-gQw41Xal27RDw3UL .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-gQw41Xal27RDw3UL .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-gQw41Xal27RDw3UL .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-gQw41Xal27RDw3UL .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-gQw41Xal27RDw3UL .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-gQw41Xal27RDw3UL .cluster text{fill:#333;}#mermaid-svg-gQw41Xal27RDw3UL .cluster span{color:#333;}#mermaid-svg-gQw41Xal27RDw3UL div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-gQw41Xal27RDw3UL .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-gQw41Xal27RDw3UL rect.text{fill:none;stroke-width:0;}#mermaid-svg-gQw41Xal27RDw3UL .icon-shape,#mermaid-svg-gQw41Xal27RDw3UL .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-gQw41Xal27RDw3UL .icon-shape p,#mermaid-svg-gQw41Xal27RDw3UL .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-gQw41Xal27RDw3UL .icon-shape .label rect,#mermaid-svg-gQw41Xal27RDw3UL .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-gQw41Xal27RDw3UL .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-gQw41Xal27RDw3UL .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-gQw41Xal27RDw3UL :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} GeoJSON / KML / CZML
DataSource
Entity 集合
Scene 渲染与拾取
3D Tileset
glTF 模型
8. 落地清单与常见坑
| # | 建议 |
|---|---|
| 1 | 先确认浏览器 / WebView 的 WebGL 可用性 |
| 2 | 影像与地形 Provider 按环境配置（密钥、跨域、CRS） |
| 3 | 大体量倾斜摄影走 3D Tiles，避免浏览器端硬啃原始 OSGB |
| 4 | 区分 Entity（好用）与 Primitive / Tiles（性能）；见 §6.5 |
| 5 | 打包器必须正确处理 Cesium 静态资源与 Worker（Vite 插件或 Webpack CopyPlugin） |
| 6 | 国内项目评估是否直接用 Cesium，或用基于 Cesium 的国产封装（底图、控件、合规） |
| 7 | 与二维地图并存时，统一坐标与相机状态同步策略 |
| 8 | POI / 定位：flyTo 连点前取消未完成的飞行，避免相机「抽搐」 |
常见坑
| 现象 | 常见原因 |
|---|---|
| 底图空白 | token / 密钥失效、跨域、Provider 配错 |
| 编译过、运行 404 | 未拷贝 Assets / Workers（Webpack 尤甚） |
| 白屏 | WebView 无 WebGL；或 JS 初始化抛错未看控制台 |
| 相机乱飞 | 连续 flyTo 未 cancelFlight / 未串行化 |
| 卡顿 | Entity 过多或未切片的大体量模型 |
| 坐标错位 | 把 Three.js 局部坐标习惯硬套到笛卡尔 / 地理坐标 |
关于 flyTo ：默认带飞行时长与视角过渡；用户快速连点多个 POI 时，若不上一次结束又开下一次，相机会叠加动画显得抽搐。业务上应在新定位前取消当前飞行（如 camera.cancelFlight()，以当前 API 为准），或自行队列化「只保留最后一次点击」。
9. 延伸阅读
| 资源 | 说明 |
|---|---|
| Cesium 官方文档与 Sandcastle 示例 | API 与交互样例 |
| 3D Tiles 规范 | 海量三维资产流式加载 |
| deck.gl / L7 文档 | 地理大数据可视化另一条路线 |
| glTF | 运行时三维模型交换格式 |
收束 ：三维 WebGIS 的底座是 WebGL；框架按问题域分流------要地球走 Cesium，要大数据图层走 deck.gl/L7，要自由造型走 Three.js。Cesium 的学习曲线往往不是陡峭，而是漫长：API 本身相对好懂，大部分时间耗在数据预处理、瓦片与 Provider、打包资源路径和真机性能上。先把 Viewer / Scene / Camera / Entity / 事件跑通，再心平气和地跟 3D Tiles 与工程配置较劲。
整理自《WebGIS 开发从入门到实践》（吕利利、牛健平）三维篇相关笔记，并补充选型与工程注意。具体 API 以 Cesium 当前版本为准。