第三篇：打包与API文档 - 让我们的 SDK 能用、能看、能分享！

📘 专栏说明

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

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

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

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

大家好，我是 Cesium 酱（也可以叫我“本猿”），一名在 WebGIS 领域摸爬滚打多年的前端开发者。上一期，我们一起初始化了项目骨架，完成了开发环境搭建。

这一期，我们要解决两个关键问题：

• 如何把 TypeScript 代码打包成别人能用的 SDK？
• 如何自动生成清晰、易读的中文 API 文档？

答案就是：Rollup + TypeDoc。

下面，我们逐行拆解配置文件，搞懂每一行代码的意义。

---

🔧 一、打包配置：rollup.config.js 全解析

我们的 rollup.config.js 不长，但每一行都至关重要。来看完整配置：

import resolve from "rollup-plugin-node-resolve"
import commonjs from "rollup-plugin-commonjs"
import typescript from "rollup-plugin-typescript2"
import peerDepsExternal from "rollup-plugin-peer-deps-external"
import copy from "rollup-plugin-copy"
const libraryName = "arc3dlab"
export default {
  input: "src/index.ts",
  output: [
    { file: `dist/${libraryName}.cjs.js`, format: "cjs", sourcemap: true },
    { file: `dist/${libraryName}.esm.js`, format: "esm", sourcemap: true },
    { file: `dist/${libraryName}.umd.js`, format: "umd", name: "Arc3DLab", sourcemap: true },
  ],
  plugins: [
    peerDepsExternal(),
    resolve(),
    commonjs(),
    typescript({ tsconfig: "./tsconfig.json" }),
    copy({ targets: [{ src: "src/static/*", dest: "dist/static" }] }),
  ],
  external: (id) => /^(cesium)/.test(id)
}

✅ 1. 为什么选 Rollup？

• 专为 库（Library） 设计，输出干净无冗余
• 天然支持 Tree Shaking
• 可同时输出 多种模块格式

✅ 2. 三种输出格式，分别给谁用？

文件	模块格式	使用场景
arc3dlab.cjs.js	CommonJS	Node.js 环境、Webpack 项目（require 引入）
arc3dlab.esm.js	ES Module	现代前端（Vite、Rollup、Webpack 5+），支持 import
arc3dlab.umd.js	UMD	直接在浏览器 <script> 标签中使用，全局变量 Arc3DLab

💡 举例：

· Vue3 + Vite 项目 → 用 .esm.js

· 老旧 jQuery 项目 → 用 .umd.js

· SSR 后端渲染 → 用 .cjs.js

✅ 3. 关键插件作用

插件	作用
peerDepsExternal()	自动将 peerDependencies（如 cesium）标记为外部依赖，不打包进 SDK
resolve()	让 Rollup 能找到 node_modules 中的第三方包
commonjs()	将 CommonJS 模块（如部分工具库）转为 ES6，供 Rollup 处理
typescript()	编译 TS → JS，并生成 .d.ts 类型声明文件
copy()	复制静态资源（如 Cesium 所需的 Workers、Assets）到 dist/static

✅ 4. 为什么 cesium 是 external？

external: (id) => /^(cesium)/.test(id)

⚠️支持用户自己安装 Cesium（版本可控）；同时避免重复打包（Cesium 本身很大，总包约 50MB+）

---

📚 二、API 文档生成：typedoc.json + generate-docs.js

由于我们用 TypeScript 开发，天然具备类型信息，TypeDoc 可以自动提取注释生成专业文档。

✅ 1. 核心依赖说明

"typedoc": "^0.28.15",                // 文档生成核心
"typedoc-material-theme": "^1.4.1",   // Material Design 风格主题
"typedoc-plugin-markdown": "^4.9.0"   // 支持 Markdown 输出（提前规划的，本项目暂未启用）

🙈 坦白说：目前没找到特别好看的中文 TypeDoc 主题，Material 主题虽然“略丑”，但至少支持中文、结构清晰、响应式。如果各位有更好看的主题，欢迎推荐！

✅ 2. typedoc.json 配置详解

{
  "entryPoints": ["./src/index.ts"],
  "out": "api-docs/api",
  "name": "Arc3DLab SDK API 文档",
  "includeVersion": true,
  "plugin": ["typedoc-material-theme"],
  "excludePrivate": true,
  "excludeProtected": true,
  "readme": "README.md",
  "categorizeByGroup": true,
  "sort": ["source-order"],
  "exclude": ["**/node_modules/**", "**/demo-*/**", "**/dist/**"],
  "tsconfig": "./tsconfig.json",
  "locales": {
    "zh-CN": {
      "name": "Arc3DLab SDK API 文档",
      "description": "基于 Cesium 构建的 WebGIS 应用框架"
    }
  }
}

配置项	作用
entryPoints	从 src/index.ts 开始分析导出的 API
out	文档输出到 api-docs/api
excludePrivate	不生成 private 成员文档
plugin	启用 Material 主题
locales	设置中文站点名称和描述
exclude	忽略示例、构建产物等无关目录

✅ 3. 自定义脚本：generate-docs.js

这个脚本做了两件事：

1. 调用 npx typedoc 生成 API 文档
2. 在 api-docs/ 下创建 index.html，用于重定向到 /api/

// 创建 index.html 重定向页
fs.writeFileSync(indexPath, `正在跳转到 [API 文档](./api/)...`);

🎯 目的：未来文档我肯定是要部署 GitHub Pages 的，设置访问根路径自动跳转到 API 文档。

---

🧪 三、如何本地生成文档

只需一条命令：

npm run docs

它会执行：

"scripts": {
  "docs": "node scripts/generate-docs.js"
}

生成后，打开 api-docs/index.html 即可查看。

🔜 后续计划：将文档自动部署到 GitHub Pages，实现在线访问！

---

❤️ 写在最后

打包和文档，是开源项目走向“可用”的关键一步。

但 Arc3DLab 依然稚嫩——

• 文档样式不够美观
• 打包细节还可优化
• 静态资源处理有待完善

欢迎每一位小伙伴参与！

• 知道更好看的 TypeDoc 主题
• 有 Rollup 优化经验
• 有迫切的需求示例

欢迎来 GitHub 提 Issue 或 PR！

---

🌟 项目开源，欢迎Star✨！

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

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