create-cesiumjs/README.zh.md

A scaffolding tool to quickly create CesiumJS geospatial visualization projects, supporting HTML, Vue3 + Vite, and React18 + Vite templates

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


## 快速开始
只需 3 步，即可启动一个 CesiumJS 项目：

### 1. 初始化项目
运行以下任意一条命令（功能完全相同，前者是现代 npm 约定，后者兼容旧版本）：
```bash
# 使用 "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 地球效果：
```bash
# 进入项目文件夹（将 "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 官网](https://cesium.com/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 模板修改）：
```javascript
// 修改前（占位符）
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 到最新版本：
  ```bash
  npm install -g npm@latest
  ```
  更新后重新运行 `npm create cesiumjs@latest`。

### 2. Cesium 资源加载失败（浏览器控制台报 404）
- **原因**：Cesium 核心资源（如 `Workers`、`Widgets`）未成功复制到 `public/cesium` 目录（可能是安装依赖时跳过了资源复制步骤）。
- **解决方法**：手动执行资源复制脚本（项目已内置）：
  ```bash
  npm run copy:cesium-assets
  ```
  执行后重启开发服务器即可。

### 3. Vue/React 项目中提示「Cesium is not defined」
- **原因**：未正确导入 Cesium 模块，或 Vite 配置未适配 Cesium。
- **解决方法**：确保使用项目生成的 `CesiumMap` 组件——该组件已包含正确的导入逻辑：
  ```javascript
  // 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 参考手册](https://cesium.com/docs/cesiumjs-ref-doc/)（包含所有 API 说明和示例代码）。
- **Cesium Ion 教程**：[Cesium Ion 使用指南](https://cesium.com/learn/ion/)（学习如何管理地形、影像和 3D 资产）。
- **Vite + Cesium 配置**：[Cesium 官方 Vite 集成教程](https://cesium.com/learn/cesiumjs-vite/)（深入理解打包优化细节）。

若遇到脚手架 Bug 或需要新功能，可访问 [CesiumJS 脚手架 Git 仓库](https://gitee.com/cesiumjs/create-cesiumjs.git)（示例链接，用于文档完整性）提交 Issue 或 Pull Request。