CesiumJS 项目脚手架

通过 npm create cesiumjs（或 npm init cesiumjs，两者功能一致）可在几秒内创建一个生产级别的 CesiumJS 地理信息可视化项目。这款官方风格的脚手架会自动完成项目初始化、依赖安装和 Cesium 资源配置，支持 HTML（无框架）、Vue3 + Vite、React18 + Vite 三种模板，让你快速开启 3D 地图开发。

快速开始

只需 3 步，即可启动一个 CesiumJS 项目：

1. 初始化项目

运行以下任意一条命令（功能完全相同，前者是现代 npm 约定，后者兼容旧版本）：

# 使用 "create" 命令（推荐，符合当前 npm 生态习惯）
npm create cesiumjs@latest

# 或使用 "init" 命令（兼容旧版 npm，效果一致）
npm init cesiumjs@latest

2. 回答交互提示

CLI 工具会通过简单提问引导你完成配置，无需手动修改复杂文件：

• 项目名称：默认值为 cesiumjs-project，按回车键直接使用，或输入自定义名称（如 my-3d-map）。
• 模板选择：根据技术栈需求选择：
  • HTML（无框架，纯前端演示）：适合快速原型开发或原生 JS 项目
  • Vue3 + Vite（组件化开发）：适合 Vue 技术栈项目，已集成 Vite 热更新
  • React18 + Vite（组件化开发）：适合 React 技术栈项目，适配 React 18 特性
• Cesium 版本：默认使用 latest（最新稳定版），也可指定具体版本（如 1.117.0，需确保版本存在于 npm 仓库）。
• 是否立即安装依赖：默认选择 是（自动执行 npm install），若需手动控制依赖安装可选择 否。

3. 启动项目

进入项目目录，运行开发服务器即可预览 3D 地球效果：

# 进入项目文件夹（将 "your-project-name" 替换为你的项目名）
cd your-project-name

# 启动开发服务（所有模板通用，Vite 会自动打开浏览器）
npm run dev

打开浏览器访问 http://localhost:5173（Vite 默认端口），即可看到一个可交互的 Cesium 3D 地球，直接基于此进行二次开发。

生成的项目包含什么？

npm create cesiumjs 会根据你选择的模板，生成一套完整且优化的项目结构，无需额外配置即可投入开发：

• 适配模板的目录结构：如 Vue/React 项目的 src/components 组件目录、HTML 项目的单文件结构。
• 预安装的依赖：自动安装 CesiumJS 核心库及对应框架依赖（如 Vue3、React18、Vite 等）。
• 自动复制的 Cesium 资源：将 Workers（后台计算脚本）、Widgets（UI 控件）等核心资源复制到 public/cesium 目录，避免手动配置路径错误。
• 可运行的演示代码：内置基础 Cesium Viewer 初始化逻辑，包含默认地形和影像，不会出现「空白屏幕」。
• 生产级脚本：支持 npm run build（打包生产版本）、npm run preview（预览生产包）等标准化命令。

项目结构说明

不同模板的目录结构会适配对应技术栈，以下是各模板的核心结构示例：

1. HTML 模板（无框架）

适合快速原型开发或原生 JavaScript 项目：

your-project-name/
├── public/
│   └── cesium/          # Cesium 核心资源（自动复制，无需修改）
│       ├── Assets/      # 地形、影像、3D 模型等资源文件
│       ├── ThirdParty/  # 第三方依赖（如 require.js、gl-matrix）
│       ├── Workers/     # 后台计算脚本（处理地理数据，不阻塞主线程）
│       ├── Widgets/     # UI 控件（缩放按钮、时间轴、图层切换等）
│       ├── Cesium.js    # CesiumJS 全量 UMD 包（适合原生引入）
│       └── index.js     # CesiumJS ES 模块入口（支持 import 引入）
├── index.html           # 主文件（包含 Cesium Viewer 初始化代码）
├── package.json         # 项目依赖和脚本配置
└── README.md            # 项目说明文档（根据你的模板自动生成）

2. Vue3 + Vite 模板

适合 Vue 组件化开发，已集成 vite-plugin-cesium 优化插件：

your-project-name/
├── public/
│   └── cesium/          # Cesium 资源（自动配置路径，可直接引用）
├── src/
│   ├── components/
│   │   └── CesiumMap.vue # 可复用的 Cesium 地图组件（封装 Viewer 逻辑）
│   ├── main.js          # Vue 入口文件（挂载根组件）
│   └── App.vue          # 根组件（引入并使用 CesiumMap 组件）
├── index.html           # Vite 入口 HTML（自动注入打包后的 JS/CSS）
├── package.json         # 依赖配置（含 Vue、Vite、Cesium 等）
├── vite.config.js       # Vite 配置（已集成 Cesium 插件，无需手动改）
└── README.md            # 项目文档

3. React18 + Vite 模板

适合 React 技术栈，适配函数组件和 Hooks 语法：

your-project-name/
├── public/
│   └── cesium/          # Cesium 资源（路径已配置，直接使用）
├── src/
│   ├── components/
│   │   └── CesiumMap.jsx # Cesium 地图组件（用 React Hooks 管理状态）
│   ├── main.jsx         # React 入口文件（渲染根组件）
│   └── App.jsx          # 根组件（使用 CesiumMap 组件）
├── index.html           # Vite 入口 HTML
├── package.json         # 依赖配置（含 React、ReactDOM、Cesium 等）
├── vite.config.js       # Vite 配置（已优化 Cesium 打包）
└── README.md            # 项目文档

关键步骤：配置 Cesium Ion Token

CesiumJS 需要 Ion Token 才能访问云端地形、影像（如 Bing 地图）和 3D 模型资源，步骤如下：

1. 获取免费 Token

1. 访问 Cesium Ion 官网，注册一个免费账号（无需付费，基础功能完全满足开发）。
2. 登录后，在右上角「个人头像」下拉菜单中选择「Access Tokens」。
3. 使用默认的「Cesium World Terrain」Token（已授权基础地形和影像），或点击「Create Token」创建自定义 Token（按需勾选权限）。

2. 替换项目中的 Token 占位符

项目代码中会有 YOUR_CESIUM_ION_TOKEN 占位符，根据模板类型修改对应文件： | 模板类型 | 需要修改的文件路径 | |----------------|---------------------------------------------| | HTML 模板 | index.html（搜索 Cesium.Ion.defaultAccessToken） | | Vue3 模板 | src/components/CesiumMap.vue | | React18 模板 | src/components/CesiumMap.jsx |

示例（HTML 模板修改）：

// 修改前（占位符）
Cesium.Ion.defaultAccessToken = "YOUR_CESIUM_ION_TOKEN";

// 修改后（替换为你的真实 Token）
Cesium.Ion.defaultAccessToken = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."; // 你的 Token

常用 NPM 脚本

所有模板生成的项目都包含标准化的 npm 脚本，覆盖开发、打包、预览全流程：

| 脚本命令 | 功能说明 | |-------------------|--------------------------------------------------------------------------| | npm run dev | 启动开发服务器，支持热更新（代码修改后浏览器自动刷新，无需手动重启） | | npm run build | 打包生产版本，生成 dist 目录（代码会被压缩、混淆，适合部署到服务器） | | npm run preview | 本地预览生产包（在 npm run build 后执行，模拟服务器环境，检查打包效果） | | npm run clean | 清理打包缓存（删除 dist 目录和 node_modules/.cache，解决缓存导致的问题） |

常见问题排查

1. 提示「命令不存在：npm create cesiumjs」

• 原因：npm 版本过低（npm create 需 npm 7+，npm init 需 npm 6+）。
• 解决方法：更新 npm 到最新版本：

  npm install -g npm@latest

  更新后重新运行 npm create cesiumjs@latest。

2. Cesium 资源加载失败（浏览器控制台报 404）

• 原因：Cesium 核心资源（如 Workers、Widgets）未成功复制到 public/cesium 目录（可能是安装依赖时跳过了资源复制步骤）。
• 解决方法：手动执行资源复制脚本（项目已内置）：

  npm run copy:cesium-assets

  执行后重启开发服务器即可。

3. Vue/React 项目中提示「Cesium is not defined」

• 原因：未正确导入 Cesium 模块，或 Vite 配置未适配 Cesium。
• 解决方法：确保使用项目生成的 CesiumMap 组件——该组件已包含正确的导入逻辑：

  // Vue 组件示例（无需手动修改）
  import { Viewer } from 'cesium'; // 导入 Cesium 核心类
  import 'cesium/Build/Cesium/Widgets/widgets.css'; // 导入 UI 样式

  若仍有问题，检查 vite.config.js 中是否存在 vite-plugin-cesium 配置（脚手架已自动添加，无需手动改）。

自定义开发建议

• 添加地形/影像：在 Cesium Ion 中选择更多资产（如「NASA 全球地形」「高德地图影像」），复制资产 ID 替换代码中的 assetId 即可切换。
• 加载 3D 模型：将 glTF 格式的 3D 模型上传到 Cesium Ion，通过 Cesium.IonResource.fromAssetId(模型ID) 加载到场景中。
• 添加交互逻辑：使用 CesiumJS API 扩展功能，例如：
  • viewer.entities.add()：添加点、线、面等地理要素。
  • viewer.camera.flyTo()：设置相机飞行动画（如飞到北京：destination: Cesium.Cartesian3.fromDegrees(116.40, 39.90, 10000)）。
  • viewer.imageryLayers.add()：叠加自定义影像图层（如本地瓦片地图）。

依赖说明

脚手架会根据模板自动安装所需依赖，无需手动 npm install 单个包，核心依赖如下：

| 模板类型 | 核心依赖列表 | |------------------------|------------------------------------------------------------------------------| | HTML 模板 | cesium（CesiumJS 核心库）、serve（静态文件服务器，用于开发预览） | | Vue3 + Vite 模板 | cesium、vue@^3.4.0（Vue 核心）、vite@^5.0.0（构建工具）、@vitejs/plugin-vue（Vue 插件）、vite-plugin-cesium（Cesium 适配插件） | | React18 + Vite 模板 | cesium、react@^18.2.0（React 核心）、react-dom@^18.2.0（DOM 渲染）、vite@^5.0.0、@vitejs/plugin-react（React 插件）、vite-plugin-cesium |

学习资源

• CesiumJS 官方文档：CesiumJS 参考手册（包含所有 API 说明和示例代码）。
• Cesium Ion 教程：Cesium Ion 使用指南（学习如何管理地形、影像和 3D 资产）。
• Vite + Cesium 配置：Cesium 官方 Vite 集成教程（深入理解打包优化细节）。

若遇到脚手架 Bug 或需要新功能，可访问 CesiumJS 脚手架 Git 仓库（示例链接，用于文档完整性）提交 Issue 或 Pull Request。