有前端基础再上手Cesium，难住人的往往不是代码本身——真正容易卡住的，是token、地形服务、静态资源配置这些GIS特有的概念。这篇一次讲清楚：用一个HTML文件，把带真实地形的三维地球在浏览器里跑起来——珠峰的每一道山脊，都来自官方数据。
这是「Cesium入门与实战」合集的入门篇。合集里已经有可视域分析、大雁塔模型剖切、土方计算三篇实战，回头补这篇地基：Cesium到底是什么、环境怎么搭、第一段代码怎么写。后续每一篇的代码，都建立在这篇的基础上。
一、CesiumJS是什么
一句话：CesiumJS 是开源的三维地球引擎，把整个地球装进浏览器，地形、影像、3D Tiles模型、矢量数据都能加载，Apache 2.0协议商用免费。智慧城市、数字孪生、军事推演这些项目里，前端三维部分十有八九是它。
常和它搞混的是另外两个引擎，一张表说清区别：
| Three.js | 通用WebGL渲染库 | 纯三维展示、产品可视化，没有地理概念 |
| MapLibre / Leaflet | 二维（或2.5D）地图 | 普通WebGIS底图应用，轻量 |
| CesiumJS | 三维地球引擎 | 有真实地球、地形、模型、坐标系的场景 |
简单说：要做"真实地球"，直接上CesiumJS。
二、准备工作：一个HTML文件 + 一个token + 一个本地服务
为了聚焦概念本身，本文用CDN引入Cesium，代码写在一个独立的HTML里；跑通原理之后，后面深入篇再切到npm + Vite的完整工程也不迟。新建好index.html——但注意，别双击打开它：浏览器禁止file://页面跨源拉取瓦片数据，直接双击只会看到一片星空（这是新手第一大坑，第五节细说）。正确姿势二选一：
VS Code + Live Server插件（推荐）：装好插件后右键index.html → Open with Live Server，浏览器自动弹出；
一行命令：在HTML文件所在目录执行python -m http.server 8000，然后浏览器访问 http://localhost:8000/index.html。
和一般Web项目不同，Cesium的token这一步省不掉：本文要加载的Cesium World Terrain（全球真实地形）存在官方云服务Ion上，没有token就拿不到数据。去 ion.cesium.com/tokens 注册个免费账号，创建一个token，复制备用——免费额度对学习来说绰绰有余。
三、第一段代码：把地球转起来
完整代码贴出，跟着敲就能跑：
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<title>加载地球与地形</title>
<script>window.CESIUM_BASE_URL = 'https://cdn.jsdelivr.net/npm/cesium@1.132/Build/Cesium/';</script>
<script src="https://cdn.jsdelivr.net/npm/cesium@1.132/Build/Cesium/Cesium.js"></script>
<link href="https://cdn.jsdelivr.net/npm/cesium@1.132/Build/Cesium/Widgets/widgets.css" rel="stylesheet">
<style>
html, body, #cesiumContainer { width: 100%; height: 100%; margin: 0; padding: 0; overflow: hidden; }
</style>
</head>
<body>
<div id="cesiumContainer"></div>
<script>
Cesium.Ion.defaultAccessToken = '把你的token粘到这里';
var viewer = new Cesium.Viewer('cesiumContainer');
</script>
</body>
</html>
通过本地服务打开，一颗能拖能转的三维地球就出现在浏览器里。三个关键点：
CESIUM_BASE_URL 必须写在引入Cesium.js之前。引擎运行时要去这个目录拉控件图标、Web Worker等静态资源，不设的话地球能出来、控件全是裂图。
Cesium.Ion.defaultAccessToken 填你的token。只新建Viewer不传参数，默认加载Ion的Bing影像，效果最漂亮。
全局样式把#cesiumContainer撑满窗口，这是三维应用的标准起手式。
此时地球还是个"光球"——影像有、地形没有。喜马拉雅摸上去和平原一样平。下一步把山请回来。
四、加载世界地形，镜头对准珠峰
给Viewer加一个terrain参数，再控制镜头，完整的<script>部分升级成：
// Ion token：去 ion.cesium.com/tokens 免费注册（地形数据在官方云端）
Cesium.Ion.defaultAccessToken = '把你的token粘到这里';
// 创建三维地球，terrain 一行挂上官方世界地形
var viewer = new Cesium.Viewer('cesiumContainer', {
terrain: Cesium.Terrain.fromWorldTerrain(),
baseLayerPicker: false,
geocoder: false,
animation: false,
timeline: false,
navigationHelpButton: false,
homeButton: false,
fullscreenButton: false,
sceneModePicker: false
});
// 让后续贴地的模型、绘制贴合地形起伏（实战篇的前置开关）
viewer.scene.globe.depthTestAgainstTerrain = true;
// 镜头飞到珠峰上空，-35° 斜视，山体立体感才出得来
viewer.camera.setView({
destination: Cesium.Cartesian3.fromDegrees(86.925, 27.90, 9000),
orientation: {
heading: 0,
pitch: Cesium.Math.toRadians(-35),
roll: 0
}
});
四个关键点：
terrain: Cesium.Terrain.fromWorldTerrain() 就是加载地形的全部。1.107后的推荐写法，一行挂上全球地形，珠峰、科罗拉多大峡谷都长在数据里。地形是异步加载的，页面转几秒山才隆起，别急着关。
后面一串false是关掉默认控件（底部动画条、时间轴这些学习阶段用不上的），画面清爽。
depthTestAgainstTerrain = true打开地形深度测试：后续篇章里模型贴地、可视域分析、地表绘制，都依赖这个开关，这里先埋个伏笔。
镜头destination三个参数是经度、纬度、高度（米），落点在珠峰南侧10公里的上空。这里的坑必须划重点：orientation不写时pitch默认0度，是平视地平线——很多人第一次跑完发现画面里只有星空，就是这个原因。而看地形也别给-90°正俯视，从头顶往下看山就是一个平面，-35°斜着看，山体的立体感才出得来。
刷新页面，世界之巅的雪山山脊、冰川谷地就这样铺在你浏览器里。到这里，恭喜，三维GIS的门算是推开了——后面无非是往这颗真实地球上放更多东西：模型、轨迹、分析。
五、高频报错与排查
最后把入门阶段最常见的五个报错集中收一下，对照排查：
1. 双击打开，画面只有一片星空 你是双击（file://协议）打开的。浏览器安全策略禁止file://页面跨源拉取影像和地形瓦片，本地渲染的星空还在，瓦片全被拦了。按第二节的两种方式，通过本地http服务打开即可。
2. 控制台报 401，地球出不来 Ion token 没填、失效或粘贴不完整。去 ion.cesium.com 的 Tokens 页面核对，确认复制的是完整一串。
3. 地球能转，但山始终不隆起 地形是异步加载的，等几秒再看；另外检查写法——网上老教程的 terrainProvider 参数已过时，1.107后用 terrain: Cesium.Terrain.fromWorldTerrain()。
4. 地球能出来，控件图标全是裂图/404 CESIUM_BASE_URL 没设置，或者写在了引入 Cesium.js 之后。它必须写在前面。
5. CDN 加载慢，白屏半天 把 jsdelivr 换成 unpkg 试试；或者干脆去 npm 下载 cesium 包，把 Build/Cesium 整个目录拷到项目里本地引用，一劳永逸。
