汽车3D配置器 THreeJS 开源项目

「15-汽车3D配置器 THreeJS」汽车3D配置器 THreeJS 开源项目

/~e77c3ZsbvP~:/

链接：https://pan.quark.cn/s/3057d7265895

面向 Web 的实时 3D 汽车工作室。

React 19 · Three.js · Vite · MIT 许可证 · 在线工作室

作者：Enes Kaymaz · X（Twitter）

./docs/mustang-studio.png

FormDrive Mustang 工作室，所有可动面板处于开启状态

项目概述

FormDrive 是一个开源的、基于组件的汽车配置器，围绕真实的 PBR 车辆资产构建。它将克制的玻璃拟态界面与实时 Three.js 场景、车辆专属可动部件、材质配置、影棚灯光以及确定性相机视角结合在一起。

本应用不是"单文件 3D Demo"，而是作为面向生产的 React Three Fiber 架构的参考实现。

车辆阵容

车辆	年份	独立控制部件	外观控制
Ford Mustang GT	2005	左右车门、左右车窗、引擎盖、后备厢	车漆、光泽、轮毂
Tesla Model 3	2018	四门、四窗、前备厢、后备厢	车漆、光泽、轮毂
K15 Concept Coupé	2021	左右车门、左右车窗、引擎盖、后掀背	车漆、光泽、轮毂

所有可动部件都使用车型专属的枢轴与定义。复合网格（如 Mustang 的分层左车窗）会被当作单个物理部件进行动画与遮罩处理。

核心特性

• 基于 WebGPU​ 的实时 PBR 渲染，自动回退到 WebGL

• React 19 + React Three Fiber​ 组件化架构

• 三套独立配置的整车资产

• 每款车型的车门 / 玻璃 / 引擎盖 / 后备厢运动定义

• 5 种车漆质感 + 3 种轮毂方案

• Dusk（黄昏）、Gallery（展厅）、Noir（暗调）三种灯光环境

• 投影式头灯与自发光尾灯

• 影棚 / 正面 / 侧面 / 细节动画相机

• 鼠标 / 触摸轨道控制，预设可中断

• PNG 影棚截图导出

• 响应式英文界面，键盘焦点态可见

• 电影级首次访问加载器：真实资源字节进度 + 缓存感知跳过

• 针对每辆车、每个可动部件的自动化浏览器校验

• 分段式车辆加载：切换车辆时当前车保持可见

加载架构

FormDrive 首屏只下载 Mustang 模型。选择其他车时，在隔离的后台线程加载，当前车保持挂载并可交互。仅当目标 GLB 成功解析后才提交切换，下载失败绝不会让工作室白屏。已打开过的模型留在内存 glTF 缓存里，再次切换秒回，但不会在后台渲染。

首次成功加载时，开场序列报告真实传输的模型字节数，从 0 到 100 可见推进后再揭幕工作室。之后访问会写入一个持久化就绪标记，跳过开场序列直接进工作室。

模型	加载阶段	文件大小
Mustang GT	首屏场景	7.31 MiB
Model 3	选中时加载	21.62 MiB
K15 Concept	选中时加载	11.23 MiB

该策略针对"三车小目录"做了优化。若扩展到大型目录，应加有界 LRU 缓存与显式 Three.js 资源销毁。

技术栈

层	技术
应用	React 19、React DOM
3D 组合	React Three Fiber、Drei
渲染器	Three.js WebGPU（WebGL 回退）
状态	Zustand
构建	Vite 7
资产	GLB/glTF、PBR 材质
校验	Chrome DevTools Protocol 脚本

快速开始

环境要求

• Node.js 22 或以上

• npm 10 或以上

• 较新的 Chromium 系浏览器 / Safari / Firefox

安装与运行

git clone https://github.com/nesdesignco/FormDrive.git
cd FormDrive
npm install
npm run dev -- --port 12314

生产构建

npm run build
npm run preview

产物输出到 dist/。生成产物、本地浏览器截图、编辑器状态均不进版本控制。

部署

每次推送到 main 由内置 GitHub Pages 工作流构建发布：在线工作室

生产环境 Vercel 部署：https://form-drive.vercel.app

Vercel 可用 Vite 预设直接导入仓库，构建命令 npm run build，输出目录 dist，Node.js 锁 22.x。

目录结构

FormDrive/
├── docs/                       # 仓库媒体资源
├── public/models/              # 车辆二进制、预览图与署名文件
├── scripts/                    # 浏览器与场景校验脚本
├── src/
│   ├── components/scene/       # 渲染器、模型、相机、灯光
│   ├── components/ui/          # 玻璃拟态界面组件
│   ├── config/                 # 车辆与工作室定义
│   ├── state/                  # Zustand 工作室状态
│   ├── App.jsx
│   └── style.css
├── tokens.css                  # 设计变量与玻璃材质系统
├── vite.config.js
└── package.js

自动化校验

FormDrive 自带确定性校验脚本，覆盖场景状态、UI 布局、可动部件完整性。

先起服务（端口 12314），再用远程调试端口 12319 开 Chrome：

open -na "Google Chrome" --args \
  --remote-debugging-port=12319 \
  --user-data-dir=/tmp/formdrive-chrome

跑完整车辆套件：

node scripts/verify-studio.mjs mustang 1536 900 --summary
node scripts/verify-studio.mjs tesla 1536 900 --summary
node scripts/verify-studio.mjs concept 1536 900 --summary
node scripts/verify-single-vehicle.mjs

校验项包括：

• 每种车漆 / 轮毂 / 影棚选项

• 每个车门、车窗、引擎盖、后备厢控制

• 复合车窗网格可见性

• 一键全关行为

• 相机预设与回到自由轨道

• 头灯锚点、投影光束、灯光开关

• 地面接触与"同时只渲染一辆车"

• 冷启动模型请求与分段式不白屏切换

• 收藏标签、预览资源、菜单碰撞

• 配置面板运动与安全滚动

• 桌面 / 笔记本 / 平板 / 手机视口下的响应式几何

• WebGPU 渲染器激活与控制台报错

• 模型署名

模型署名

应用源码为 MIT 许可证。车辆二进制及其预览渲染图不按 MIT 再授权，各自沿用原始许可证。

资产	创作者 / 来源	许可证
2005 Ford Mustang GT	Ricy / Sketchfab	CC BY 4.0
Tesla 2018 Model 3	Ameer Studio / Sketchfab	CC BY 4.0
Car Concept	随模型分发的署名文件	CC BY 4.0

FormDrive 是独立的技术与设计研究项目，与 Ford Motor Company、Tesla, Inc. 及各车型原作者无隶属、无背书、无赞助关系。

贡献

欢迎 Bug 报告与聚焦的改进。开 PR 前先读 CONTRIBUTING.md。凡涉及车辆网格、材质匹配、可动部件枢轴的改动，必须附上三款车的校验结果。

安全

请按 SECURITY.md 报告安全问题，不要在公开 Issue 里披露敏感漏洞细节。

许可证

应用源码基于 MIT License 开放。

第三方车辆资产受其同目录署名文件约束。