Cesium 入门安装与本地环境配置
Cesium 入门安装与本地环境配置，关键是选好加载方式，并在创建 Viewer 前正确设置 Ion Access Token 与静态资源基址。截至 2026 年 11 月，稳定可用的版本是 CesiumJS 1.147（npm 包为 1.147.0，约 2026-11-02 发布）；新手可先用 CDN 几分钟跑通三维地球，再把同一套依赖接到 Vite 或 Webpack 本地工程。准备好现代浏览器、开发用 Node.js（构建 Cesium 源码时一般要求 22.17.0 及以上）以及免费的 Cesium ion 账号后，能正常显示地形与影像，即算本机环境验收通过。
安装前要准备什么
和桌面 GIS 软件先装运行时、再配许可类似，CesiumJS 也是「运行环境 + 凭证 + 资源路径」三件事一起做。若你刚配过桌面端，可对照本站的 ArcGIS 入门教程一：软件怎么安装与环境怎么配置 或 零基础入门 QGIS 教程（含插件与环境避坑），把思路迁移到 Web：先保证浏览器能开 WebGL，再保证脚本、Worker、样式能被 HTTP 正确加载。
- 浏览器：最新 Chrome、Edge、Firefox、Safari；Firefox 一般需 115 或 ESR 及以上；需开启硬件加速与 WebGL。
- Node.js：仅 CDN 演示可不装；用 npm、Vite、Webpack 或从源码构建时再装。构建官方仓库时通常要求 Node 22.17.0 或更新，具体以构建说明为准。
- Cesium ion 账号：免费注册后创建带有合适权限的 Access Token，否则默认演示令牌会提示告警或请求失败。
- 本地 HTTP 服务：不要用 file:// 直接打开含 Worker 的页面，易触发跨域；本地数据用静态服务器托管。
两种方式怎么选：CDN 还是 npm
目标不同，选型不同。只想验证本机能否出图，用 CDN；要做正式前端工程、做打包与 tree-shaking，用 npm。
| 方式 | 适合场景 | 优点 | 要注意 |
|---|---|---|---|
| CDN / 官方 ZIP | 课堂演示、快速验收、单页 HTML | 几乎零配置，复制示例即可 | 版本路径要一致；仍需设置 Ion Token |
| npm（cesium） | Vite / Webpack 等工程化项目 | 可按需导入、便于版本锁定 | 必须复制 Workers 等静态目录并设置 CESIUM_BASE_URL |
| 从源码构建 | 二次开发、跟官方主干 | 可改引擎再打包 | Node 版本要求更高，步骤更长 |
官方还拆出了 @cesium/engine、@cesium/widgets，自 1.146 起另有 @cesium/core。入门阶段直接 npm install cesium 即可，不必一开始就拆包。
用 CDN 快速跑通第一个 Viewer
到 Cesium 官网 Downloads 选择当前发布包（写作时为 1.147），按 Quickstart 思路写一个最小 HTML：引入同版本的 Cesium.js 与 Widgets/widgets.css，在创建 Viewer 之前写入自己的 Token，再初始化地形与相机。
- 注册并登录 Cesium ion，创建 Access Token（至少具备读取资产等必要权限）。
- 新建 index.html，用官方同版本脚本与样式地址（从 Downloads 复制，避免版本错配）。
- 在脚本里设置 Cesium.Ion.defaultAccessToken = “你的Token”。
- 创建 Viewer，按需挂载世界地形；调用 camera.flyTo 飞到已知经纬度，确认球体能渲染。
- 用本地静态服务器打开页面（例如本机 http-server），不要双击用文件协议打开。
验收标准很直接：页面无大面积黑屏，控制台没有 Workers/Assets 404，地形或底图能出来。若只见球体无纹理，优先核对脚本版本是否成套、Token 是否在 Viewer 之前赋值。Token 权限与失效问题可对照 Cesium ion Access Tokens 官方说明 自查。
npm 安装与 Vite / Webpack 本地配置
工程化路径和桌面 GIS 的「安装后还要配环境变量、工作空间」很像：包装上了不够，还要把运行时资源拷到可访问目录。步骤可按下面执行。
- 在项目根目录执行 npm install cesium（需要时再锁到 1.147.0）。
- 在入口文件导入 Cesium 之前设置 window.CESIUM_BASE_URL（或用打包器的 define），指向最终能访问到的静态根路径。
- 导入样式：import “cesium/Build/Cesium/Widgets/widgets.css”；业务代码推荐 named import，例如 import { Viewer } from “cesium”，便于 tree-shaking。
- 把构建产物里的 Workers、ThirdParty、Assets、Widgets 四个目录复制到输出目录（Vite 可用静态复制插件，Webpack 常用 Copy 插件）。自 1.114 起，多数场景不再需要把某些 Node 内置包声明为 external，但仍以当前官方配置说明为准。
- 开发服务器启动后打开页面，同样先设 Token，再 new Viewer(…)。
若要从源码参与构建，需满足较高 Node 版本，再执行安装、构建与本地启动；细节见 Cesium 官方 BuildGuide。社区也有面向 Vite 的脚手架与插件可自动处理 CESIUM_BASE_URL 与资源复制，入门时用官方示例仓库对照改自己的工程更稳妥。
本地只加载自己的 3D Tiles、glTF 时，同样用 HTTP 服务托管，并视情况关掉依赖在线的 baseLayerPicker、geocoder 等控件；离线底图可改用自带的 NaturalEarthII 一类本地影像。这和本站在 ArcGIS 安装步骤与环境配置 里强调「服务地址、许可、数据路径一次对齐」是同一类验收思维。
常见问题
页面空白或黑球，控制台报 Workers / Assets 404？
多半是 CESIUM_BASE_URL 没设、设晚了，或四个静态目录没拷到构建输出。把基址设到导入 Cesium 之前，并确认浏览器能直接打开该路径下的 Worker 脚本。
提示默认 Token、401 或 InvalidCredentials？
在创建 Viewer 之前写入自己的 Token；检查令牌权限范围，以及 World Terrain 等资产是否已加入自己的 My Assets。演示令牌会随版本轮换，生产环境不要依赖它。
用 file:// 打开一切正常，一上服务器就花屏或跨域？
浏览器对本地文件协议限制更严。始终用本地 HTTP 服务（并按需开 CORS）托管页面与数据，保持脚本、Worker、瓦片同源或正确跨域头。
CDN 有球无纹理，和示例不一致？
优先核对 Cesium.js、widgets.css、Workers 是否同属一个发布版本；版本错配或 Worker 加载失败都会导致贴图异常。改用官网 Downloads 成套路径，并再次确认 Token 时机。
本阶段只要求：选定 CDN 或 npm 之一，装上 CesiumJS 1.147，配好 Ion Token 与静态资源基址，用本地 HTTP 打开后能稳定看到三维地球。建议新手先用 CDN 完成第一次验收，再把同一套 Token 与资源复制规则迁到 Vite/Webpack；正式项目里固定版本号，并把 Token 放进环境变量而非提交到仓库。