用React+Three.js 做 3D Web版搭建三维交互场景：模型的可视化摆放与轻量交互 - 指南

导语：在网页里自由摆放 3D 模型

• 本项目当前聚焦“纯三维摆放与交互”的能力，不涉及摄像头与图像识别，后续会增加此功能。
• 适合高效做原型、演示布局、测试交互与材质效果。

快速上手

• 安装依赖：pnpm install
• 启动开发：pnpm dev 后访问本地服务首页，进入 WebAR 演示页即可体验
• 调试建议：先用桌面浏览器进入“模拟模式”，再用支持 WebXR 的手机浏览器体验“真实 AR”， 后续有设备后增加 ！

项目截图

技术栈一览（选择理由）

• React + TypeScript + Vite：现代前端组合，开发体验与类型安全兼顾；Vite 启动与热更非常快。
• Three.js：浏览器端主流 3D 引擎，生态丰富，适合快速搭建 3D 场景与材质光照。
• Tailwind + React Router：迅速构建 UI 与页面导航。
• 当前版本不涉及摄像头与图像识别。

架构总览（文字版）

• UI 层：页面上的“启动/停止、添加模型、网格编辑、标记检测”等操作与状态显示。
• 会话管理：统一控制 AR 会话的生命周期，把底层事件转换成“开始/结束/帧更新”等上层语义。
• 核心引擎：负责 Three.js 场景、相机、渲染循环、性能监控，以及与“标记检测/模型加载”的协作。
• 交互系统：把触摸、鼠标、键盘、语音、游戏手柄输入，转成“点击、拖拽、缩放、旋转、滑动、双击”等动作事件。
• 当前版本专注 3D 场景与交互，不包含摄像头/图像/二维码等识别能力。
• 模型加载：GLTF/GLB 首选，内置缓存与失败兜底（彩色立方体），还支持快速几何与文字模型。

事件流示意（简化）

• 用户点击“启动” → 会话管理创建并启动会话 → 引擎开始渲染循环 → 性能指标同步更新
• 用户在画布交互 → 交互框架把输入转成动作事件 → 选中对象并附着变换控制器 → 执行移动/旋转/缩放

（当前版本无“标记检测/摄像头”分支）

生命周期（分步）

• 初始化：创建会话管理与引擎、渲染器、场景基础光照；准备交互体系
• 会话启动：检查 WebXR 支持；支持则启用真实 AR；不支持则进入“模拟模式”（虚拟平面与帧数据）
• 渲染循环：统计 FPS、帧时、绘制调用、三角形数；按帧驱动 UI 与可视化
• 交互控制：对象选中、拖拽、缩放、旋转、命令执行（含中文自然语言）
• 停止与清理：停止会话/检测、释放资源（模型、纹理、监听器），回到初始状态

核心模块深入

引擎

• 维护场景、相机与渲染器；在“模拟模式”下提供虚拟平面与帧资料，确保桌面也能体验
• 统一事件出口：会话、模型加载、标记检测、帧更新、性能信息

会话管理

• 献出“启动/停止/重置”等入口，屏蔽底层差异（WebXR 与模拟模式）
• 把引擎事件规范化为上层语义，页面无需关心底层实现

交互系统

• 手势：支撑点击/双击、拖拽、缩放（捏合/滚轮）、旋转（右键/双指上滑）、滑动识别
• 键盘：Q/E/W/S 快速旋转；F 翻转（世界/视图/局部三种模式）
• 语音：中文识别管道，示例指令“旋转 30 度”“放大 10%”
• 游戏手柄：基础按钮与摇杆轮询，映射为移动/旋转等事件

（本版不包含标记识别与摄像头功能）

模型加载

• GLTF/GLB 首选；失败时自动生成彩色立方体占位，保证“场景可见”与可继续调试
• 快速构造：一键生成常用几何体与文字贴图平面，用于占位与标签

进阶操作

• 网格编辑：打开网格后进入编辑模式，附着变换控制器进行移动/旋转/缩放；适合场景对齐与参考
• 吸附步长：为位移/旋转/缩放设置步长，提升精度与一致性；适合对齐标记或构建规范化布景
• 自然语言命令：支持中文指令解析，建议明确单位（度/百分比/米）；避免含混表达

性能优化清单

• 减负：尽量减少高细分几何与复杂着色；阴影与发光效果按需使用
• 资源：控制纹理尺寸与数量；模型复用与缓存；及时释放不再可见的对象
• 事件：对滚轮/拖拽等高频事件做节流或去抖；避免频繁状态更新导致重绘抖动
• 监控：关注 FPS、帧时、绘制调用、三角形数；当 FPS 明显下降时，优先检查“场景复杂度”与“纹理大小”

（本版不涉及摄像头/麦克风权限- 有点问题，后续优化）

场景案例

• 教育：在课本封面上叠加 3D 动画，点击触发解说
• 营销：在产品包装上浮现模型与热点，引导互动与转化
• 导览：展馆中以二维码或图像标记触发导览模型，支持多标记切换

FAQ 扩展

• 如何导入 GLB 模型：通过工具栏“预设模型”或“本地导入”入口；导入后可用变换控制器编辑位置/旋转/缩放。
• 吸附步长如何设置：在工具栏中打开“吸附”并调整位移/旋转/缩放的步长数值，便于精确对齐。
• 无法选中物体怎么办：确保未点击到网格线或描边；可切换编辑模式或点击物体的主体区域重试。

术语小词典

• 射线投射：从相机到场景发射“射线”来命中对象的技术
• GLTF/GLB：Web 场景常用的 3D 模型格式
• 帧时（Frame Time）：渲染一帧所需时间，影响流畅度