项目地址: https://github.com/mlt131220/Astral3D(Gitee 镜像 https://gitee.com/mlt131220/Astral3D)
官方文档: http://editor-doc.astraljs.com/
在线编辑器: https://editor.astraljs.com/
许可证: Apache-2.0(README 声明个人学习与二次开发免费、商业使用需授权,以仓库为准)
包管理器: pnpm workspace(
packageManager: pnpm@10.8.1);npm 包astral3d1.0.0 因保留catalog:依赖不能直接npm install(截至 2026-10)版本: SDK/编辑器
1.0.0(GitHub Release1.0.0),npm 包astral3d同为1.0.0中文教程(12 章): https://znlgis.github.io/cad/Astral3D/
概述
Astral3D 是杭州星孪数字科技团队开源的「Web 3D 编辑器 + 三维引擎」一体化项目,仓库是 pnpm monorepo:packages/editor 是 Vue 3 + Naive UI 的可视化编辑器,packages/sdk(工作区包名 @astral3d/engine)抽出渲染、加载、特效、脚本等运行时能力,packages/docs 是文档站。定位面向数字孪生与工程可视化:30+ 模型格式、BIM(RVT/IFC)轻量化展示、CAD 图纸(DWG/DXF)解析预览、场景分包存储与按需加载、关键帧动画编辑器、插件系统、脚本运行时、粒子与天气系统。
| 能力 | 实现依赖(取自仓库 catalog 与 package.json) |
|---|---|
| 3D 渲染 | three 0.176.0(WebGL),three-gpu-pathtracer、three-mesh-bvh、three-viewport-gizmo |
| 前端框架 | vue ^3.5.22 + naive-ui ^2.43.1 + unocss + pinia ^2.1.4 + vue-i18n |
| 构建 | vite ^6.2.5、typescript ^5.4.5、@vitejs/plugin-vue ^6 |
| 相机控制 | camera-controls ^2.9.0(配合 three 的 TransformControls) |
| 事件 | signals ^1.0.0(Viewer 的 registerSignal 模块) |
| BIM | web-ifc-three ^0.0.126(IFC 解析,含 IFCWorker.js) |
| CAD | 内置 DxfParser / DxfViewer |
| 瓦片/倾斜摄影 | 3d-tiles-renderer(TilesManage 模块) |
| 粒子 | three-nebula(以 Particle 命名空间导出) |
| 序列化 | localforage、jszip、pako(场景分包与离线包) |
开源版 / 商业版 / 企业版功能差异较大;本 SKILL 只覆盖开源仓库源码与已发布类型声明能够核对的用法。
环境准备
前置要求
- Node.js ≥ 23.0.0(根
package.json的engines声明) - pnpm(
packageManager: pnpm@10.8.1) - 支持 WebGL2 的现代浏览器;编辑器是纯前端工程,本地跑通不依赖后端
源码克隆与运行(推荐路径)
git clone https://github.com/mlt131220/Astral3D.git
cd Astral3D
pnpm install
# 1) 先构建 SDK:编辑器依赖工作区包 @astral3d/engine 的产物
pnpm run sdk:build
# 2) 启动编辑器开发服务器
pnpm run editor:dev
其它构建目标
pnpm run editor:build # = sdk:build + editor build,产出静态站点
pnpm run editor:preview # 预览生产构建
pnpm run editor:tsc # 编辑器类型检查
pnpm run docs:dev # 本地文档站
pnpm run examples:dev # 示例工程
验证:editor:dev 启动后进入编辑器界面,拖入一个 glTF 模型能渲染出阴影即环境就绪;pnpm run editor:build 成功产出 packages/editor/dist 说明 SDK 与编辑器链路完整。
npm 包现状(重要)
npm 上的 astral3d@1.0.0 是 SDK 构建产物(dist/astral3d.es.js + dist/types/index.d.ts),但发布包的 dependencies 保留了 "three": "catalog:" 这类 pnpm workspace 协议字段,用 npm/yarn 直接安装会失败:
npm install astral3d
# npm error code EUNSUPPORTEDPROTOCOL
# npm error Unsupported URL Type "catalog:": catalog:
结论:集成以源码 monorepo 为准(把 packages/sdk 纳入工作区,或 pnpm run sdk:build 后引用产物),不要假设可以 npm i astral3d 直接接入。
核心 API
SDK 类型声明(packages/sdk 产物 dist/types/lib/index.d.ts)导出的主要成员:
| 导出 | 说明 |
|---|---|
App |
全局场景管理静态类:scene / sceneHelpers / camera / viewportCamera / viewportShading / selected / locked / geometries / materials / textures / scripts / helpers / metadata,并挂 Config Storage Project Selector History Resource CSM 模块 |
Viewer |
渲染视口,继承 THREE.EventDispatcher,持有 renderer camera scene sceneHelpers raycaster grid box selectionBox sceneBox3 css2DRenderer css3DRenderer timer pathtracer 与 modules |
Preview |
不带编辑器 UI 的轻量预览容器 |
Loader |
模型 / 纹理加载单例(GLTF、DRACO、KTX2、RGBE、TGA、EXR、MTL、ObjectLoader、IFC) |
Package |
场景打包与解包(ZIP 分片上传 / 按 URL 还原场景) |
DxfViewer / DxfParser |
DXF 图纸解析与预览 |
Plugin(类型) |
插件契约:name / version / icon / install() / uninstall() / run() |
Script Hooks Utils Timeline Particle Commands |
脚本运行时、组合式钩子、工具、时间轴、粒子、命令 |
objects geometries tools points BasicObject3D Particles |
场景对象、几何、工具、点云与内建资产 |
Viewer 与能力模块
import { Viewer } from '@astral3d/engine';
const viewer = new Viewer({ container }); // options 类型为 IViewerSetting
// viewer.modules(类型 ViewerModules)是能力入口:
// plugin: PluginManager viewHelper: Helper
// cameraManage: CameraManage controls: CameraControls
// transformControls?: TransformControls
// effect: Effect weather: Weather
// registerSignal: Signals shaderMaterialManager: ShaderMaterialManager
// particleSystem: ParticleSystem dragControl: Drag tilesManage: TilesManage
viewer.initModules();
viewer.initEvent();
viewer.loadEnv(true); // 载入默认环境贴图与背景
viewer.computedSceneBox3(); // 计算整体包围盒,供聚焦使用
viewer.updateAspectRatio(); // 容器尺寸变化时调用
enableEdit 与 enableScript 是可读写属性,分别控制编辑态与脚本运行;渲染引擎可通过 createEngine() / engineCreated(renderer) 替换。
事件(ViewerEventMap)
Viewer 是 THREE.EventDispatcher 子类,用 addEventListener 按事件名订阅:
viewer.addEventListener('loaded', () => console.log('scene ready'));
viewer.addEventListener('onPick', ({ intersect, object }) => {
console.log('clicked', object.name, intersect.point);
});
viewer.addEventListener('afterAnimation', ({ delta, toBeRender }) => {
if (Math.random() < 0.5) toBeRender(false); // 无需重绘时跳帧降载
});
可用事件名:loaded、beforeAnimation、afterAnimation、beforeRender、afterRender、beforeDestroy、afterDestroy、onPick、onDoubleClick、onKeyDown、onKeyUp、onPointerDown、onPointerUp、onPointerMove、onTouchStart、onTouchEnd、onSceneBackgroundChange、onSceneEnvironmentChange。
模型加载
import { Loader } from '@astral3d/engine';
// Loader 是单例;glTF 走带 DRACO / KTX2 的 loader
const gltfLoader = await Loader.createGLTFLoader();
Loader.dracoLoader.setDecoderPath('/draco/');
await Loader.loadFile(file, undefined, null, true); // 第四个参数 addToScene
await Loader.loadFiles(files, filesMap); // 批量加载(含 MTL 关联材质)
await Loader.handleJSON(sceneJson, true); // 编辑器导出的 JSON 场景
await Loader.handleZIP(zipContents, true); // 场景包
Loader.disposeGLTFLoaderEffects(gltfLoader); // 用完释放
发布产物中可见的格式 loader:GLTF/GLB(+ DRACO、KTX2)、OBJ(+ MTL)、FBX、3MF、AMF、IFC(web-ifc + IFCWorker)、KMZ、PCD、PLY、STL、VTK、SVGLoader,另有 GLTF/OBJ/PLY/STL 导出器与 DXF 解析器。没有 STEP loader:STEP 需先在桌面端(FreeCAD/OCCT)转成 glTF 或 IFC 再入库。
场景分包(Package)
大场景以 ZIP 分片交付,首包保存场景基本信息、图纸信息与基础配置:
import { Package } from '@astral3d/engine';
const pack = new Package(viewer);
// 打包:业务侧提供 zip 上传函数
const result = await pack.pack({
name: 'factory',
layer: 1,
zipUploadFun: async (zip) => (await fetch('/api/upload', { method: 'POST', body: zip })).json(),
onProgress: (p) => console.log(`${p}%`),
onComplete: ({ totalSize, totalZipNumber }) => console.log(totalSize, totalZipNumber)
});
// 解包:从首包开始按 URL 还原(回调式,不返回 Promise)
pack.unpack({
url: '/scenes/factory.zip',
onSceneLoad: (sceneJson, configJson) => { /* 交由 App / Loader 组装 */ },
onProgress: (p) => {},
onComplete: () => {}
});
pack.dispose(); // 不再需要时释放
插件系统
插件契约是 Plugin 接口(version 为 number),由 viewer.modules.plugin(PluginManager)管理:
import type { Plugin } from '@astral3d/engine';
const myPlugin: Plugin = {
name: 'MyPlugin',
version: 1,
icon: 'link',
install(config) { /* 注册信号、工具栏、自定义材质 */ },
uninstall() { /* 还原副作用 */ },
run() { /* 启用交互 */ }
};
viewer.modules.plugin.use(myPlugin, { /* config */ });
await viewer.modules.plugin.loadAsync('/plugins/extra.js', true); // 远程加载并自动注册
const p = viewer.modules.plugin.getPlugin<Plugin>('MyPlugin');
脚本运行时
场景对象可挂脚本,支持按 UUID 热更新:
viewer.installScripts(); // 组装全部脚本
viewer.installScripts(object.uuid, 'rotate'); // 仅组装指定对象、指定名称的脚本
viewer.uninstallScriptsByUuid(object.uuid); // 卸载该对象脚本(热更新前调用)
viewer.unInstallScripts(); // 全部卸载
典型工作流
两条主线:输入 glTF/IFC/DXF 与场景配置 → 产出 可在自有页面嵌入的 3D 场景。
工作流一:编辑器搭场景,自有页面轻量展示
- 打开 https://editor.astraljs.com/,或本地
pnpm run sdk:build && pnpm run editor:dev - 新建场景 → 导入模型(glTF 优先;BIM 用 IFC,图纸用 DXF)→ 布光、材质、动画与脚本
- 导出场景包(ZIP 分片,含场景 JSON 与资源),上传到静态资源服务或业务后端
- 业务页面用 SDK 创建
Viewer,通过Package.unpack({ url })还原场景(或用Loader.handleZIP) viewer.addEventListener('onPick', ...)做设备选中,选中对象在App.selected- 容器 resize 调
viewer.updateAspectRatio();离开页面前unInstallScripts()并清理监听
工作流二:源码二次开发(新增插件与自定义材质)
- 克隆仓库 →
pnpm install→pnpm run sdk:dev/editor:dev建立热更闭环 - 在
packages/sdk内扩展能力;SDK 改动后重新pnpm run sdk:build - 以
Plugin暴露功能:install()注册信号(viewer.modules.registerSignal)与 UI,run()绑定交互 - 自定义着色器走
viewer.modules.shaderMaterialManager pnpm run editor:tsc与pnpm run editor:build全绿后再提交
最佳实践
- 先 sdk:build 再 editor:dev:编辑器依赖
@astral3d/engine产物,跳过会在编辑器包里报模块解析失败 - 不要 npm 装
astral3d:发布包保留catalog:协议依赖,集成走源码工作区 - glTF + DRACO + KTX2 是体积与首屏主力组合;
Loader.disposeGLTFLoaderEffects()用完释放 - 大场景靠分包:
Package的 ZIP 分片 +loadOfflineScene(),不要让单个场景 JSON 膨胀 - 事件名以
ViewerEventMap为准:viewer.on('pick')之类的写法不存在 - 每帧逻辑放
beforeRender/afterAnimation:后者提供toBeRender(need)可主动跳帧 - 移动端降载:关闭实时阴影与 pathtracer、降低渲染分辨率,天气与粒子按需启用
- 脚本热更新成对调用:
uninstallScriptsByUuid(uuid)后installScripts(uuid),避免重复装配
常见问题
| 问题 | 解决 |
|---|---|
npm i astral3d 报 EUNSUPPORTEDPROTOCOL: catalog: |
发布包保留 pnpm catalog: 依赖;改用源码 monorepo 或引用 sdk:build 产物 |
编辑器启动报找不到 @astral3d/engine |
未先构建 SDK;执行 pnpm run sdk:build |
| 安装依赖提示 Node 版本不满足 | 根 package.json 要求 Node ≥ 23.0.0,用 nvm 切换后重装 |
| 用 npm/yarn 装依赖失败 | 仓库是 pnpm workspace(packageManager: pnpm@10.8.1),必须用 pnpm |
| STEP 文件打不开 | SDK 无 STEP loader,先用 FreeCAD/OCCT 转 glTF 或 IFC |
| IFC/RVT 打开失败或内存暴涨 | 上游先减面与拆分,浏览器侧按楼层/子树加载 |
| 大场景首屏很慢 | 用 Package 分包 + DRACO/KTX2,检查 onProgress 卡在哪一类资源 |
| 页面切走后再进来画面异常 | 卸载时 unInstallScripts() 并移除事件监听,避免残留 WebGL 上下文 |
AI 使用建议
- 区分两条路径:「用编辑器产出场景」与「用 SDK 嵌入自有工程」,前者不需要写渲染代码。
- 优先场景包而非手工搭树:以编辑器导出的 ZIP/JSON 为基础,再用 API 注入实时数据与交互。
- API 以类型声明为准:
Viewer/App/Loader/Package成员可从dist/types/**.d.ts核对;不要臆造viewer.scene.findById()、viewer.camera.flyTo()、MqttBridge这类不存在的方法。 - 数据接入属业务侧:MQTT/WebSocket 由上层实现,SDK 只负责把数据写回对象属性与材质;断线重连与节流自行处理。
相关技能
- chili3d — 浏览器内参数化 CAD(OCCT.js + WASM):../chili3d/SKILL.md
- occt — 底层几何内核(STEP/IGES/BREP),STEP 转换的上游:../occt/SKILL.md
- lightcad — C#/.NET 桌面 CAD 与 BIM 平台(工程侧对照):../lightcad/SKILL.md
参考资源
- 仓库:https://github.com/mlt131220/Astral3D | Gitee:https://gitee.com/mlt131220/Astral3D
- 在线编辑器:https://editor.astraljs.com/ | 文档中心:http://editor-doc.astraljs.com/
- 后端实现参考:https://github.com/yx8663/astral-service
- 中文教程(12 章):https://znlgis.github.io/cad/Astral3D/
- Three.js:https://threejs.org/docs/ | camera-controls:https://github.com/yomotsu/camera-controls