简介ShadowEditor是一款基于WebGL的在线3D模型编辑器面向Web前端、三维可视化开发者和游戏建模人员支持在浏览器中直接创建、编辑与预览3D模型可导入OBJ、FBX、GLTF等常见格式调整几何形状、纹理、光照、动画及骨骼动画并内置数据后台实现项目保存、版本回溯与团队协作。资源包为RAR格式共7173个文件大小约347.62MB核心文件以JavaScript、TypeScript源码为主另有glsl着色器、HTML页面、JSON配置、PNG贴图以及DLL运行库等覆盖编辑器前端、资源管理和后台服务多个模块目录结构较清晰。编辑器内置的数据后台是其亮点可让用户直接在编辑器内管理项目、按版本回溯并为多人协作提供便利同时基于WebGL实现跨平台可在Windows、macOS、iOS、Android等设备运行。对于希望掌握Three.js/WebGL技术栈或搭建自有模型编辑平台的开发者这套源码提供了完整的前端交互、场景组织和数据存储参考可在此基础上扩展自定义工具面板、接入业务数据或部署私有化服务也适合作为三维可视化项目的基础框架。已有283人学习下载值得深入研究与二次开发。1. ShadowEditor 带数据后台WebGL 模型编辑器为什么必须把存盘交给后端在浏览器里拖模型、改材质任何一个用过 Three.js 的团队都能做到。真正把「3D 演示页」和「模型编辑器」分开的是刷新页面之后你的工作还在不在。ShadowEditor 带数据后台解决的就是这件事编辑器管 WebGL 渲染交互数据后台管场景与资产的持久化。没有后台时场景、模型、贴图全挂在浏览器缓存上换台机器就归零有了后台场景变成数据库里的文档模型变成文件服务里的资产一次保存就是一次完整的状态归档编辑结果能跨会话恢复。这层差别决定了它适合做数字孪生和 BIM 管理系统的编辑器底座。这篇文章写给正在搭 Web 三维可视化平台的工程师先讲清楚数据后台该存什么再给本地最小部署命令然后落到保存与上传的实操避坑最后是怎么把它嵌进自己的业务系统。每一步都配上可直接执行的命令和参数说明。2. 数据后台的定位场景树、资产库与持久化的边界理解这类带数据后台的编辑器先别急着点界面要把系统拆成两层看前端负责 Three.js 渲染、拾取、拖拽和属性面板的响应数据后台负责把「一次完整的编辑状态」变成可以跨会话、跨设备恢复的数据。前端是手后台是仓库。后面遇到的大部分坑都出在这两层交界的地方。2.1 为什么浏览器存储撑不起一个 WebGL 模型编辑器先做个排除法为什么不把场景直接存在浏览器里LocalStorage 的配额通常只有 5MB 左右一个稍微精细点的 GLB 模型就吃掉大半IndexedDB 的配额看着大但它是整站共享的什么时候被清理由浏览器说了算。用一行代码就能看到你当前站点的真实额度// 在编辑器页面的控制台执行查看 IndexedDB 的总体占用与配额 if (navigator.storage?.estimate) { const { usage, quota } await navigator.storage.estimate(); console.log(已用 ${(usage / 1024 / 1024).toFixed(1)} MB / 配额 ${(quota / 1024 / 1024).toFixed(1)} MB); }这段代码利用的是 Storage API 的 estimate 方法返回的是整个 origin 的占用与配额不是某一个库的。实际项目里会看到两个结果一是配额对「存一个几十 MB 的场景工程」来说根本不够二是用户一旦在无痕模式或清理缓存这些数据说没就没。Unity 发布 WebGL 时频繁出现的「使用 IDBFS 写入失败」本质是一回事浏览器没有真正的文件系统所谓的写入只是往 IndexedDB 里塞二进制配额满、私密模式、存储被清理都会让写操作失败。浏览器的存储只适合做缓存和草稿不能当唯一事实源。2.2 编辑器要持久化的不是模型文件而是「场景」很多第一次接数据后台的人会问直接把模型文件存起来不就行了问题在于用户在编辑器里改的、保存的不是模型文件本身而是「场景」——一个包含对象层级、变换、材质参数、灯光、相机、动画和脚本引用的状态树。它是模型的上层组织方式。一个简化版的场景文档长这样{ sceneName: 车间布局_v3, scene: { children: [ { uuid: a1b2c3, type: Mesh, name: 底座, position: [0, 0, 0], rotation: [0, 0, 0], scale: [1, 1, 1], geometry: { type: BoxGeometry, params: { width: 10, height: 2, depth: 4 } }, material: { type: MeshStandardMaterial, params: { color: #cccccc } } } ] }, camera: { type: PerspectiveCamera, fov: 60 } }可以看到保存的是「怎么描述这个对象」而不是模型二进制本身几何体用类型加参数重建材质用类型加颜色、贴图引用重建场景树用 children 递归描述。这就是为什么这类编辑器都会给每个对象类型实现两个方法toJSON 负责把对象压成可序列化结构fromJSON 负责在加载时重建。你自己向编辑器里加自定义组件时漏掉这两个方法保存后字段就会悄悄消失。2.3 资产与场景分开存存储边界一张表说清场景文档里只放引用不放二进制。这是「带数据后台」和「把 JSON 塞进数据库」之间最关键的一条界线。一个典型项目的存储分布数据类型存放位置说明场景 JSONMongoDB 文档含层级、变换、材质、相机、灯光、脚本引用模型文件GLB/glTF服务端上传目录或对象存储二进制不进数据库场景里存资源 ID 或 URL纹理、HDRI、音频同上材质和背景引用脚本代码数据库文本字段按版本留存、可审计缩略图、截图文件服务列表页展示用体积小但访问频繁撤销/重做栈前端内存不落库刷新即清空这样拆有两个好处。一是场景文档保持轻量一次保存就是一个文档替换而不是把几十 MB 的二进制重新拷一遍二是资产可以被多个场景共享同一个模型在不同项目里复用只需要维护一份资源记录上传目录里也只有一个副本。2.4 为什么常见方案选 MongoDB场景本身就是一棵 JSON 树选数据库时关系型数据库不是不行但会把事情做拧。场景天然是一棵嵌套的 JSON 树用 MySQL 存要么拆成 node 表、edge 表再拼装要么塞进 TEXT 字段当黑盒前者查询和重建成本高后者其实和 NoSQL 没有区别。MongoDB 的优势在于文档模型和场景结构一一对应保存就是整文档替换加载就是一次按 ID 查询。我一般会为场景集合加两个字段version 用于乐观锁updateTime 用于排序和列表展示。需要克制的是「一个文档装所有」。单个场景文档控制在 1~2MB 以内是比较舒服的区间超出后全量替换的开销会明显上升。常见做法是场景文档只存场景树大字段比如内嵌数据、批量标注点拆到单独集合里用场景 ID 关联。这样「保存」这个动作始终是轻量的后面聊并发控制时也会依赖这个前提。3. 本地部署 ShadowEditor最小命令把数据后台跑起来把这类项目跑起来第一步不是装前端依赖而是先把数据链路理顺数据库在哪个端口服务端从哪个配置读连接串上传文件写到哪个目录。这三件事确定后启动只是两条命令的事。部署中常见的失败九成是 MongoDB 没起来或者配置里的连接串对不上而不是代码本身的问题。3.1 先确认环境再谈启动动手前先花两分钟把环境确认掉能省掉后面一半排错时间。我一般会按顺序检查 Node.js、MongoDB 和浏览器的 WebGL 支持node -v # 要求 LTS 版本老项目对版本敏感 npm -v mongod --version # MongoDB 服务端是否在 PATH 里最后一条尤其容易忽略只装了 MongoDB Compass 客户端、没装 servermongod 是不存在的。浏览器端打开编辑器页面后在控制台执行WebGL2RenderingContext ! undefined如果返回 false说明当前环境不支持 WebGL2场景渲染会退到兼容模式甚至白屏。这四项确认完再往下走。3.2 按顺序启动数据库 → 服务端 → 浏览器3.2.1 启动 MongoDB数据库建议单独指定数据目录不要用系统默认路径方便后面验证和备份mkdir -p /data/shadoweditor/db mongod --dbpath /data/shadoweditor/db \ --bind_ip 127.0.0.1 \ --port 27017 \ --logpath /data/shadoweditor/mongod.log参数含义--dbpath 指定数据文件目录--bind_ip 把监听地址限制为本地避免把 27017 暴露到内网甚至公网--port 指定端口--logpath 把日志写到文件而不是终端。看到日志里有waiting for connections说明数据库已就绪如果端口被占用通常是本机已有一个实例在跑关掉旧的或者换端口并在服务端配置里对应修改。3.2.2 配置服务端连接这类项目的服务端配置一般集中在一个 config 文件里常见字段是端口、数据库连接串、上传目录和静态资源目录。典型形态// server 配置示例字段名以你拉到的版本为准 module.exports { port: process.env.PORT || 3000, db: { url: mongodb://127.0.0.1:27017/shadoweditor }, uploadDir: /data/shadoweditor/uploads, // 模型、纹理等资产落盘目录 staticRoot: public // 浏览器端静态文件目录 };两个提醒。一是 uploadDir 用绝对路径很多人在项目根目录建相对路径换启动目录后文件就找不到二是数据库名在连接串里指定比如上面的 shadoweditor所有场景和资源集合都会建在这个库下面方便后面直接用 mongosh 查看。3.2.3 安装依赖并启动在源码根目录安装依赖、启动服务npm install npm start启动日志里应能看到监听端口和数据库连接成功的信息。看到ECONNREFUSED先去查 MongoDB 是否在监听看到Cannot find module多半是 Node 版本和项目要求不匹配把本地 Node 切到 LTS 版本后删掉 node_modules 重装。服务端起来后同一个端口通常也托管了编辑器页面浏览器直接访问http://127.0.0.1:3000即可打开登录界面。3.3 建一个场景验证数据真的落库界面能打开只是第一步真正要验证的是「数据后台」在工作。做法很简单新建场景拖一个立方体进去改一下颜色或位置点保存然后回数据库看有没有这条记录mongosh --quiet shadoweditor --eval db.scenes.find({}, {_id:0, name:1, updateTime:1}).sort({updateTime:-1}).limit(10)这里的场景集合名以项目实际为准常见的是 scenes。如果查询结果为空检查保存时服务端日志有没有报错、页面请求返回什么状态码如果看到记录但字段为空通常是前端序列化返回的数据结构和后端预期不一致版本升级时最容易出这种问题。完整的验证清单如下验证项预期结果失败时看什么保存场景scenes 集合出现新文档服务端日志、POST 请求状态码上传 GLB 模型上传目录出现文件与缩略图文件大小、存储目录权限刷新页面重新打开场景树、材质、脚本都在控制台 404资源 URL 是否完整重启 MongoDB 再打开数据不丢dbpath 是否指向临时目录判断数据后台是否真的可靠标准只有一条关掉页面甚至重启数据库再打开场景它还是刚才的样子。做到这一步本地链路就算真正通了。4. ShadowEditor 实操与避坑保存、资产上传和数据一致性跑通之后进入高频操作保存场景、上传模型、多标签页协作时的数据一致性。这一章的内容是从实际使用里挑出来的三个最容易被忽略的点每一个都对应一类线上问题。4.1 保存按钮背后的序列化链路界面上的「保存」看起来是把场景写进数据库实际是一条完整链路编辑器先把场景树、相机、灯光、选中状态压成一个 JSON再由接口发给服务端服务端替换数据库里的对应文档。注意接口路径和字段名以你拉到的 ShadowEditor 版本为准不同小版本差异不小下面的代码演示的是这一类系统的通用形态。前端这一侧常见做法是封装一个保存函数// 编辑器内的保存序列化 提交到数据后台 async function saveScene() { const sceneData editor.toJSON(); // 把场景树与编辑器状态序列化 const resp await fetch(/api/scenes/save, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ id: currentSceneId, name: currentSceneName, version: currentVersion, data: sceneData }) }); const result await resp.json(); currentVersion result.version; // 把服务端返回的新版本号记下来 }这里的要点是 version 字段它不参与场景内容但决定了保存能不能成功。编辑器每次打开场景时拿到一个版本号保存时把版本号带回给服务端服务端校验通过才写入。另一个实际经验是自动保存我一般会做「关键操作后 500ms 防抖 每 30 秒一次兜底」但不会在每次拖动物体时都触发保存否则场景文档大时序列化的卡顿会直接毁掉编辑体验。4.2 模型上传的正确姿势与两个常见失败模型资产上传格式上优先选 GLB它是二进制单文件一个文件包含几何、材质和纹理。glTF 的 .gltf 格式是文本加外部 .bin 和贴图的组合上传时只传主文件、漏了外部资源加载时就 404这是最典型的失败。上传逻辑常见是这样// 上传模型资源服务端返回资源 ID 和访问 URL const form new FormData(); form.append(file, file); // file 来自文件选择框 const resp await fetch(/api/assets/upload, { method: POST, body: form }); const asset await resp.json(); // 场景里只存 asset 的 id 和 url不存文件本体 sceneItem.setAttribute(src, asset.url);两个高频坑。一是文件名带中文、空格或特殊字符URL 编码在各浏览器里表现不一致后端存储时用随机 ID 重命名原始文件名单独存一个字段用于展示二是 OBJ/MTL 这种带外部材质引用的格式MTL 里的贴图路径相对 MTL 文件的位置上传时必须保持目录结构否则材质贴图全部丢失。判断上传是否成功看服务端返回的资源记录和文件大小而不是只看界面上的预览。4.3 数据一致性的三个坑覆盖、并发与浏览器缓存坑现象处理方式IDBFS/IndexedDB 写入失败私密模式或配额满时保存失败服务端为唯一事实源浏览器端只做草稿缓存多标签页覆盖后保存的旧数据覆盖新数据版本号乐观锁容器尺寸变化canvas 拉伸、拾取偏移监听 resize更新相机 aspect 与 renderer 尺寸第一个坑是浏览器缓存被当成持久化。Unity 发布 WebGL 时「使用 IDBFS 写入失败」的报错常年有人问原因就是 IndexedDB 在私密模式或配额满时写入失败游戏里的存档随之丢失。编辑器同理如果只把场景存在浏览器用户清缓存就等于丢工程。数据后台的价值恰恰是把唯一事实源放到服务端浏览器里的 IndexedDB 只做最近工程的草稿缓存。第二个坑是无脑覆盖。两个标签页打开同一个场景A 改完保存B 再保存B 的旧版本把 A 的新内容冲掉了。服务端加乐观锁保存时用版本号做条件更新是这类系统最便宜的可靠解法// 服务端保存接口版本号不匹配则拒绝写入 const result await db.scenes.updateOne( { _id: sceneId, version: req.body.version }, { $set: { data: req.body.data, version: req.body.version 1, updateTime: new Date() } } ); if (result.matchedCount 0) { // 说明库里的版本号已经比提交的高直接返回冲突 return res.status(409).json({ error: 场景已在其他标签页被修改请刷新后重试 }); }用 updateOne 的条件过滤代替「先查再改」是为了消除检查与写入之间的时间差matchedCount 为 0 就说明版本对不上。第三个坑和 WebGL 模板相关把编辑器嵌进管理系统页面时容器尺寸变化后 canvas 没有跟着调整画面拉伸、拾取位置偏移。这和 Unity 打包 WebGL 时要写对 HTML 模板里的自适应脚本是同一个问题编辑器里要监听容器 resize同步相机 aspect 和 renderer 尺寸。5. 嵌入业务系统数据后台的隔离、验证与导入导出到这一步本地能跑、编辑能用接下来的问题通常是「怎么把它放进我们的平台」。三个动作最常用给场景加归属做多租户隔离、用脚本验证持久化没被异步操作破坏、用导入导出做工程迁移。做完这三件事这套编辑器才真正算是业务系统的一部分。5.1 给场景加 owner先隔离再开放多人共用一套数据后台时第一步是在场景文档上补归属字段。保存接口写入时带上当前用户查询接口只返回自己名下的场景// 列表查询只返回当前用户可见的场景 db.scenes.find({ owner: userId, deleted: { $ne: true } }) .sort({ updateTime: -1 }) .limit(100);数据量上来后给查询条件建索引否则列表页会越来越慢db.scenes.createIndex({ owner: 1, updateTime: -1 }); db.assets.createIndex({ md5: 1 }, { unique: true }); // 重复资产去重接口层做幂等第二个索引常用于资产去重上传前先算文件 MD5命中就直接复用已有资源记录能省下不少存储和带宽。5.2 用脚本验证持久化的可靠性多人协作的系统里最怕的是「看似保存成功实际上某个字段在异步流程里被吞了」。持久化验证建议脚本化每次发布前跑一遍构造场景、保存、模拟重启、重新加载、对比对象树。// 验证流程加载备份的场景 JSON对比节点数与关键属性 const scene JSON.parse(fs.readFileSync(scene_backup.json, utf8)); const children scene.scene?.children ?? []; console.log(节点数: ${children.length}); const base children.find(n n.name 底座); console.assert(base.material.params.color #cc0000, 材质颜色未还原);断言失败就说明序列化或加载链路有字段丢失不用等业务方在界面上发现。把这段脚本接进 CI每次改动编辑器源码后自动跑一遍比手动点界面可靠得多。5.3 一个用得上导入导出技巧UUID 重映射场景要跨环境迁移时直接合并两个场景 JSON 会出事两棵场景树里可能有相同的 uuid加载后对象的引用会串。导入前给所有对象重新生成 uuid同时维护新旧映射表const { randomUUID } require(crypto); function remap(node, map) { const old node.uuid; node.uuid map.get(old) || randomUUID(); map.set(old, node.uuid); (node.children || []).forEach(child remap(child, map)); return node; }脚本遍历场景树每个节点的 uuid 换成新值旧值记录在映射表里材质、骨骼、动画里凡是按 uuid 引用的字段都要用这张表同步替换。导入完成后再用 5.2 的验证脚本跑一遍确认节点数和引用关系没有断再交给业务方。我之前在一个接 Cesium 高程瓦片的数字孪生项目里就是这么处理场景合并的几十个模型拼进同一张场景图一次到位没有回头改。本文还有配套的精品资源点击获取
