3DCellForge 架构深度剖析React Three.js React Three Fiber 构建 AI 3D 工作室【免费下载链接】3DCellForgeAI-powered interactive 3D model generation, inspection, and presentation studio.项目地址: https://gitcode.com/gh_mirrors/3d/3DCellForge3DCellForge 是一个 AI 驱动的交互式 3D 模型工作室AI 3D Studio它把一张普通图片或本地 GLB 文件变成可在浏览器中旋转、缩放、检视和演示的精致 3D 场景。整套系统基于React Three.js React Three Fiber技术栈搭建前端用 React 组织界面与状态用 Three.js / R3F 渲染 3D 场景后端用 Node.js 对接多家图生 3D 云服务商Tripo、Fal、Hyper3D Rodin、Hunyuan3D并内置 IndexedDB 本地模型库与一键演示模式。这篇文章带你从架构视角拆解它的分层设计、数据流与工程实践即使你是前端新手也能看懂。️ 项目全景一张图看懂 AI 3D 工作室先看整体效果——上传一张细胞参考图几分钟后就能得到一个可以在浏览器里 360° 检视的 3D 模型它的核心能力可以归纳为四条主线能力说明关键模块交互式 3D 查看器拖拽旋转、滚轮缩放、局部隔离、GLB 导出src/viewer/CellViewer.jsx三栏工作台左模型库 / 中 WebGL 舞台 / 右生成工具src/components/图生 3D 生成多 Provider 云端生成 本地 GLB 导入server.mjs、server/providers/演示与持久化Demo 演示模式、模型质量评分、IndexedDB 存储src/lib/motionProfiles.js、src/lib/modelStore.js技术栈一览来自 package.jsonReact 19 Vite 8UI 与开发构建Three.js 0.184 react-three/fiber react-three/drei声明式 3D 场景postprocessing react-three/postprocessing后期特效framer-motion界面动效Node.js原生 http轻量 API 后端零框架依赖️ 整体架构前后端分离 Provider 适配器下图是 Playwright 视觉回归测试中的工作区截图可以清楚看到三栏布局左侧是 MODEL LIBRARY 模型库与 GENERATION QUEUE 生成队列中间是 3D 舞台无头截图时为占位色块右侧是 ASSET SOURCE 资源源选择器与 COMPARE MODELS 对比面板整个仓库只有两个顶层入口前端 SPAsrc/和Node 后端server.mjs职责划分非常干净前端分层src/分层路径职责配置层src/config/appConfig.js存储键、轮询间隔、API 基址等常量领域层src/domain/模型目录、偏好设置归一化、持久化逻辑工具层src/lib/IndexedDB 存取、图片管线、质量评分、数学工具、GLB 导出服务层src/services/modelApi.js与后端通信的唯一出口组件层src/components/工作台 UI 组件查看器src/viewer/CellViewer.jsxR3F 3D 场景后端server.mjs server/providers/后端只有约 180 行主文件用原生node:http实现了几个关键路由POST /api/3d/generate按provider字段分发到对应适配器GET /api/3d/status/:taskId轮询生成进度POST /api/3d/local-model导入本地 GLB 并缓存GET /api/3d/health、GET /api/3d/logs健康检查与诊断日志四个 Provider 适配器fal.mjs、tripo.mjs、rodin.mjs、hunyuan.mjs都遵循同一套「创建任务 → 查询状态」接口新增一个服务商只需实现这两个函数——这是典型的适配器模式也让前端的 Auto 模式可以按Hyper3D → Tripo → Fal → Hunyuan → JS Depth的顺序自动降级重试见 getProviderPlan。一个值得学习的安全细节API Key 只放在服务端 .env.local永远不会进入前端打包产物普通用户无需任何密钥也能通过预置演示模型体验完整流程。 3D 渲染核心React Three Fiber 场景怎么搭3D 部分集中在 1300 多行的 src/viewer/CellViewer.jsx 中。R3F 的精髓在于「用组件写场景」Canvas由 R3F 接管 WebGL 渲染循环drei 工具包OrbitControls实现拖拽旋转与缩放useGLTF异步加载 GLB 模型ContactShadows提供柔和的接地阴影useFrame逐帧钩子在渲染循环内更新相机与物体驱动演示动画postprocessing叠加后期特效让截图更接近摄影棚质感除了渲染这个文件还承担了演示运镜进入 Demo 模式后相机会根据模型元数据选择一种运动档案——汽车走道路推进、飞机走掠过飞行、舰船走海上巡航、生物标本走环形检视、产品走展台转台。这些档案定义在 src/lib/motionProfiles.js 中每种档案包含时长与相机轨迹全部基于smoothPingPong的正弦插值函数计算无物理引擎参与轻量且稳定。另外还有一个实用模块 src/lib/modelQuality.js对生成的 GLB 计算模型质量分文件体积、三角面数、贴图数、演示就绪度录制前先看一眼分数低分通常意味着源图或生成结果还不够上镜。 AI 图生 3D从一张参考图到 GLB 模型左边的渲染图就是典型的输入素材——上传到 Tripo 的细胞参考图一条完整的生成数据流是这样的前端在 src/lib/imagePipeline.js 中对图片做压缩、缩略图与预览通过 src/services/modelApi.js 的create3dGeneration把图片 POST 给后端后端适配器调用云端 APITripo 走 STS 对象存储 任务接口Fal 走官方队列Rodin 走 multipart 任务接口前端按固定间隔轮询状态拿到 GLB 地址后端把 GLB缓存到本地.generated-models/目录后续访问走本地副本不重复消耗服务商的临时 URL这种「云端生成 本地缓存」的策略让演示近乎零成本仓库里还预置了两个缓存模型public/generated-models/离线也能跑通全部流程。没有云服务预算时还可以选择JS Depth纯浏览器端的图像浮雕 分层 PNG 兜底或直接导入本地.glb/.gltf。 数据持久化IndexedDB 优先localStorage 兜底生成的模型记录不会因刷新页面而丢失。src/lib/modelStore.js 把模型元数据写入 IndexedDB库名model-studio-3d-assets不可用时自动降级到 localStorage 的精简方案设置、UI 状态、笔记、生成历史等小型数据则由 src/lib/storage.js 管理。资产库抽屉的回归截图如下可以看到缩略图、Provider 状态与操作按钮的产品化程度✅ 工程质量单测 视觉回归双保险项目用零依赖的node --test跑单元/集成测试test/覆盖资产元数据、质量评分、运动档案等服务端工具函数再用Playwright 做布局与截图回归test/visual/workbench.visual.spec.mjs校验工作台、资产库抽屉和 Demo 模式三大界面npm run test # 单元测试 npm run test:visual # 视觉回归测试 快速上手git clone https://gitcode.com/gh_mirrors/3d/3DCellForge cd 3DCellForge npm install npm run dev # 启动前端 npm run dev:api # 启动本地 Node 后端可选启用图生 3D 需要如需启用真实图生 3D参照 README.md 的 Optional Image-to-3D Backend 一节配置.env.local即可。总结这套架构值得借鉴的 4 点分层克制前端六层各司其职后端只有一个入口文件 适配器目录新人半天就能读通全链路适配器模式 Auto 降级多服务商共存互不干扰失败自动切换密钥服务端化.env.local 本地缓存安全与成本双赢持久化兜底策略IndexedDB 为主、localStorage 兜底任何浏览器环境下体验一致3DCellForge 证明了一件事React Three.js R3F 这套组合足以撑起一个功能完整的 AI 3D 工作室——而它的分层架构正是你可以直接复用的模板。【免费下载链接】3DCellForgeAI-powered interactive 3D model generation, inspection, and presentation studio.项目地址: https://gitcode.com/gh_mirrors/3d/3DCellForge创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考