Overview
这篇教程解决什么问题
它解决的是“第一个可运行项目怎么搭”的问题。你会得到一个包含 `Viewer`、真实地球、`World Terrain` 和 `OSM Buildings` 的基础场景，并理解 Cesium ion token 在整个链路里的作用。
如果你后面要做航迹回放、建筑可视化、影像叠加或 3D Tiles，基本都应该先完成这一篇。
What You Build
完成后你会得到什么
- 一个可以稳定加载 CesiumJS 的基础页面骨架。
- 一个启用了全球地形和 OSM 建筑的真实世界场景。
- 一套适合继续扩展业务功能的初始化代码。
Suggested Flow
建议跟着做的顺序
- 创建容器元素，让 `Viewer` 有稳定的挂载区域。
- 通过 CDN 或 NPM 引入 CesiumJS。
- 配置 Cesium ion token，并确认服务可以访问。
- 实例化 `Viewer`，先跑通一个空白地球。
- 挂接 `World Terrain`，观察地表从平面变成高程地形。
- 加入 `OSM Buildings`，验证场景真实感提升。
- 测试缩放、旋转和镜头操作，确认最小闭环完成。
Starter Code
最小代码骨架
import { Ion, Viewer, createOsmBuildingsAsync, Terrain } from "cesium";
Ion.defaultAccessToken = "YOUR_TOKEN";
const viewer = new Viewer("cesiumContainer", {
terrain: Terrain.fromWorldTerrain(),
});
const buildings = await createOsmBuildingsAsync();
viewer.scene.primitives.add(buildings);Project Tips
落地项目时的建议
先保守初始化
先把默认控件和基础场景跑通，再考虑扩展 geocoder、timeline 或自定义 UI。
把 token 管理提早纳入工程
不要把 token 硬写死在多个页面里，最好提前规划环境变量或配置文件。
先做一个稳定模板
Quickstart 页面应沉淀成团队内部模板，而不是做完一次就丢。
Key Points
学习重点
- `Viewer` 是大多数 CesiumJS 项目的主入口。
- token 不是可选项，很多官方数据能力都依赖它。
- Terrain 和 Buildings 会立刻改变场景的空间感和产品观感。
Pitfalls
常见问题
- 容器高度没设置时，页面看起来像是“什么都没加载”。
- token 配置错误时，地形和建筑常常直接加载失败。
- 资源路径配置不对时，Cesium 的静态资源可能找不到。
Checklist
完成标志
- 页面能正常显示全球场景。
- 相机可以稳定缩放和旋转。
- 地形与建筑都能成功加载。
SEO / Demo
适合展示什么
- 产品首页 demo。
- 项目可行性验证页面。
- 团队内部 CesiumJS 起步模板。
Avoid
不要一开始做
- 不要先堆复杂 UI。
- 不要先引入多数据源。
- 不要跳过 token 与资源路径配置验证。
Next