第二篇：从零开始造轮子：今天，我们正式启动 Arc3DLab SDK！

公告

View Post

📘 专栏说明

本专栏旨在手把手带你从零开始，基于开源三维地球引擎 Cesium 封装一套功能完善、可复用的 WebGIS 增强型 SDK。内容涵盖核心封装思路、关键代码实现、常用 GIS 功能抽象，以及基于该 SDK 构建的 UI 组件库开发。如果你更关注结果而非实现过程，也可直接使用已发布的成果：

🌟 GitHub仓库 📦 NPM 包 ✨ 公众号：经纬码客（欢迎关注）

💡 建议：即便你打算直接使用 SDK，也推荐订阅本专栏 -- 理解设计思路，才能更灵活地扩展属于你自己的专属 GIS 能力！

由于作者需兼顾全职工作，更新主要安排在晚间或节假日，无法保证高频发布，但会持续迭代，直至 SDK 达到实际项目落地标准。届时将完整开源所有源码，供学习与商用（遵循许可证协议）。

大家好，我是 Cesium 酱（也可以叫我“本猿”），一名在 WebGIS 领域摸爬滚打多年的前端开发者。上一期我们聊了 Cesium 的故事，也立下了一个 flag：要一起从头构建一个属于前端开发者的 Cesium 增强 SDK，暂定名 — Arc3DLab。

今天，就是正式开工的日子！

这不是一个已经完成的项目，而是一场开源共建实验。
你看到的每一行代码，都将从 npm init 开始；
你参与的每一个建议，都可能成为 SDK 的一部分。

准备好了吗？让我们一起敲下第一行代码！

🔨 第一步：明确目标 —— 我们要造一个什么样的 SDK？

在动手前，先想清楚“为什么造”：

✅ 不是重复造 Cesium
✅ 而是封装常用功能，提升开发效率
✅ 让 Cesium 更好用、更易集成、更符合国内开发者习惯

初步规划的功能模块包括：

智能 Viewer 初始化（自动处理 token、资源路径）
内置图层管理器（影像/地形/矢量一键切换）
测量工具（距离、面积、高度）
漫游与视角控制
事件系统增强
Vue 插件支持（至于React，本猿后续视情况更新）

📌 重要原则：核心轻量 + 插件可选，绝不搞“全家桶”。

🛠️ 第二步：搭建基础开发环境

我们要用现代前端工程化的方式，从零初始化项目。

本人开发环境清单

编程语言：TypeScript（类型安全，开发更稳）
打包工具：Rollup（轻量、高效，专为库设计）
Node.js 版本：v22.20.0
npm 版本：v9.4.0
Cesium 版本：v1.136.0
代码编辑器：VS Code（搭配 ESLint + Prettier 插件）

💡 为什么用 Rollup而不是 Webpack？
因为我们要打包的是第三方库（Library），不是应用。Rollup 输出更干净，天然支持 ESM/CJS 双格式。

1. 创建项目目录

mkdir Arc3DLab_SDK
cd Arc3DLab_SDK

2. 初始化 npm 包

npm init -y

这会生成最基础的 package.json。

3. 安装核心依赖

# 开发依赖
npm install -D typescript rollup @rollup/plugin-typescript @rollup/plugin-node-resolve @rollup/plugin-commonjs
# 对等依赖（本猿这里直接安装了当前最新的Cesium版本1.136.0）
npm install -D cesium@1.136.0

4. 初始化 TypeScript 配置

npx tsc --init --declaration --allowSyntheticDefaultImports --target es2020 --module esnext --outDir dist

然后修改 tsconfig.json，确保：

{
  "compilerOptions": {
    "declaration": true,
    "sourceMap": true,
    "esModuleInterop": true,
    "strict": true,
    "lib": ["ES2020", "DOM"]
  }
}

5. 配置 Rollup 打包

创建 rollup.config.js：

import typescript from '@rollup/plugin-typescript';
import { nodeResolve } from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';
export default {
  input: 'src/index.ts',
  output: [
    {
      file: 'dist/arc3dlab.esm.js',
      format: 'es'
    },
    {
      file: 'dist/arc3dlab.cjs.js',
      format: 'cjs'
    }
  ],
  plugins: [
    typescript(),
    nodeResolve(),
    commonjs()
  ],
  external: ['cesium'] // 我们默认不打包Cesium到SDK中
};

【本猿最终package.json 和 rollup.config.js 配置如下，方便省流可以直接在文末到仓库取】

package.json

rollup.config.js

📁 第三步：设计初始目录结构

现在，我们手动创建第一个目录结构：

mkdir -p src/core src/utils src/types
touch src/index.ts src/core/Viewer.ts

最终目录长这样：

Arc3DLab_SDK/
├── .git/                    # Git 版本控制目录
├── .gitignore              # Git 忽略文件配置
├── .prettierrc             # Prettier 代码格式化配置
├── CHANGES.md              # 项目变更记录
├── LICENSE                 # 项目许可证
├── LOG.md                  # 项目日志
├── README.md               # 项目说明文档
├── demo-html/              # HTML 示例项目目录
├── demo-vue3/              # Vue3 示例项目目录
├── docs/                   # API文档目录
├── package-lock.json       # NPM 包锁定文件
├── package.json            # 项目配置文件
├── rollup.config.js        # Rollup 打包配置
├── scripts/                # 构建脚本目录
│   └── generate-docs.js    # 文档生成脚本
├── src/                    # 源代码目录
│   ├── core/               # 核心功能模块
│   │   ├── EventEmitter.ts # 事件发射器类
│   │   ├── Viewer.ts       # 增强型 Cesium Viewer 类
│   │   └── index.ts        # 核心模块导出
│   ├── index.ts            # 主入口文件
│   ├── types/              # 类型定义目录
│   └── utils/              # 工具函数目录
├── tsconfig.json           # TypeScript 配置
└── typedoc.json

✨ 设计理念：核心最小化，扩展自由化。

所有增强功能都封装在 core/ 中，不污染原生 Cesium。

⚙️第四步：关键配置说明

1. 依赖管理

在 package.json 中，Cesium 被声明为 peerDependencies：

"peerDependencies": {
  "cesium": "1.136.0"
}

这意味着：

SDK 不捆绑 Cesium，避免重复打包
使用者需自行安装指定版本的 Cesium
更灵活，也更符合库的最佳实践

2. 构建脚本

"scripts": {
    "build": "rollup -c",
    "build:copy": "rollup -c && xcopy /E /I /Y \"dist\" \"demo-html\\public\\lib\"",
    "format": "prettier --write \"src/**/*.ts\"",
    "docs": "node scripts/generate-docs.js",
    "docs:watch": "typedoc --options typedoc.json --watch",
    "docs:build": "typedoc --options typedoc.json"
  },

🎯 小技巧：开发时可先 npm run build:copy，然后直接刷新 demo-html/index.html 查看效果！

🧪 第五步：省流，如何本地跑起来？

1. 克隆仓库

git clone https://github.com/jianlei-wang/Arc3DLab_SDK.git
cd Arc3DLab_SDK

2. 安装依赖

npm install
# 注意：不需要单独安装 cesium

3. 构建 SDK

npm run build

4. 运行示例

进入 demo-html目录，执行 npm install && npm run dev
或进入 demo-vue3 目录，执行 npm install && npm run dev

📚 最后说明：文档与类型支持

TypeScript 类型：完整 .d.ts 文件随包发布，IDE 自动提示
API 文档：通过 TypeDoc 生成，支持中文，后续将部署到 GitHub Pages
代码风格：Prettier 统一格式，提交前自动校验

🌟 项目开源，欢迎Star✨！

GitHub：https://github.com/jianlei-wang/Arc3DLab_SDK

NPM：https://www.npmjs.com/package/arc3dlab

Cesium 酱の百宝箱 · 第 2 篇
写于 2025 年冬夜，代码未冷，热忱依旧。

posted on 2026-01-13 23:56 Arc3DLab 阅读(1) 评论(0) 收藏举报

刷新页面返回顶部