基于Three.js与React构建3D家居编辑器：从架构到工程实践

在实际 3D 应用开发领域，从零开始构建一个功能完备的 3D 家居编辑器，涉及从底层渲染、交互逻辑到上层业务架构的完整知识栈。这不仅是前端图形学能力的体现，更是对工程化思维和复杂状态管理的深度考验。本文将以一个开源的大型 3D 家居编辑器项目为蓝本，深入剖析其核心实现机制，并提供一个从环境搭建、核心模块开发到性能优化的完整实践指南。无论你是希望深入学习 WebGL/Three.js 的前端开发者，还是对 3D 交互应用架构感兴趣的全栈工程师，都能通过本文理解如何“手搓”这样一个系统，并掌握其中可复用的设计模式与工程实践。

1. 理解 3D 家居编辑器的核心架构与挑战

在动手之前，必须厘清一个 3D 家居编辑器与普通 3D 展示页面的本质区别。它不是一个简单的模型查看器，而是一个复杂的创作工具，其核心挑战在于如何高效、稳定地管理动态的 3D 场景、用户交互以及数据状态。

1.1 核心功能模块拆解

一个典型的 3D 家居编辑器通常包含以下核心模块：

1. 场景渲染引擎：负责加载、渲染 3D 模型（家具、墙壁、地板等），并处理光照、阴影、后期效果。Three.js 是目前 Web 端最主流的选择。
2. 交互系统：这是编辑器的“手”和“眼”。包括：
   • 相机控制：实现平移、旋转、缩放，让用户能从任意角度观察场景。
   • 物体拾取：通过射线检测（Raycasting）判断用户点击或拖拽了哪个物体。
   • 变换工具：提供移动、旋转、缩放物体的可视化控件（如 Three.js 的 TransformControls）。
   • 网格绘制与编辑：用于绘制房间户型、墙面，可能涉及顶点、面的编辑。
3. 资产管理系统：管理所有可用的 3D 模型资产（家具、装饰品）。包括模型的加载、缓存、分类、元数据（尺寸、价格、品类）管理。
4. 场景状态管理：这是编辑器的大脑。需要维护当前场景中所有物体的层级关系、空间变换（位置、旋转、缩放）、材质属性等。任何交互操作最终都是对这颗场景状态树的修改。
5. 撤销/重做（Undo/Redo）：对于编辑类工具至关重要。需要记录每一次状态变更，并能回退或重做。
6. 数据持久化与导出：将编辑好的场景序列化为特定格式（如 JSON、GLTF）保存到服务器或本地，并能重新加载。

1.2 技术选型与依赖规划

基于上述模块，我们可以规划一个以 Three.js 为核心的技术栈：

• 3D 渲染引擎：Three.js (r15x+)。这是基石。
• 交互工具：Three.js 内置的OrbitControls（相机控制）、TransformControls（物体变换）。对于更复杂的交互（如墙面绘制），可能需要自定义。
• 状态管理：对于复杂应用，推荐使用专门的状态管理库。虽然可以用 Three.js 的Scene对象本身作为数据源，但为了更好的可预测性和时间旅行调试（实现撤销/重做），引入如Zustand、Redux或MobX是更工程化的选择。
• UI 框架：React 或 Vue 等，用于构建编辑器侧边栏、工具栏、资产库等 2D UI 界面。它们通过状态管理与 3D 画布通信。
• 构建工具：Vite 或 Webpack，用于模块化开发和打包。
• 类型系统：TypeScript。在 3D 开发中，明确的类型定义能极大减少因坐标、矩阵、对象类型错误导致的 Bug。

2. 搭建开发环境与项目骨架

我们从一个干净的 TypeScript + React + Three.js 项目开始。确保你的 Node.js 版本在 16 以上。

2.1 初始化项目并安装核心依赖

使用 Vite 快速创建一个 React + TypeScript 项目，并安装 Three.js 及相关生态库。

# 使用 npm create 初始化项目 npm create vite@latest my-3d-home-editor -- --template react-ts cd my-3d-home-editor # 安装核心依赖 npm install three @types/three # 安装 Three.js 官方控制器和加载器 npm install @react-three/fiber @react-three/drei # @react-three/fiber 是 React 的 Three.js 渲染器，极大简化了 Three.js 在 React 中的使用 # @react-three/drei 提供了大量有用的组件和工具函数 # 安装状态管理库（以 Zustand 为例，轻量且易用） npm install zustand # 安装 UI 组件库（以 Ant Design 为例，可选） npm install antd

2.2 项目目录结构设计

一个清晰的结构是管理复杂 3D 应用的关键。建议采用功能模块划分的方式：

src/ ├── assets/ # 静态资源，如模型文件、贴图 ├── components/ # React 组件 │ ├── EditorCanvas/ # 3D 画布主组件 │ ├── UI/ # 侧边栏、工具栏等 2D UI 组件 │ └── Common/ # 通用组件 ├── core/ # 核心业务逻辑 │ ├── engine/ # 渲染引擎封装、场景管理 │ ├── interaction/ # 交互逻辑：拾取、变换、绘制 │ ├── assets/ # 资产加载与管理类 │ └── history/ # 撤销/重做管理器 ├── stores/ # 状态管理（Zustand stores） ├── types/ # TypeScript 类型定义 ├── utils/ # 工具函数 └── App.tsx # 应用入口

2.3 创建基础的 3D 画布组件

在src/components/EditorCanvas/index.tsx中，我们使用@react-three/fiber创建画布。

import React, { useRef } from 'react'; import { Canvas } from '@react-three/fiber'; import { OrbitControls, Grid, Stats } from '@react-three/drei'; import * as THREE from 'three'; const EditorCanvas: React.FC = () => { const canvasRef = useRef<HTMLCanvasElement>(null); return ( <div style={{ width: '100vw', height: '100vh' }}> <Canvas ref={canvasRef} camera={{ position: [10, 10, 10], fov: 50 }} shadows // 启用阴影 onCreated={({ gl, scene }) => { // 场景初始化设置 scene.background = new THREE.Color(0xf0f0f0); gl.shadowMap.enabled = true; gl.shadowMap.type = THREE.PCFSoftShadowMap; }} > {/* 环境光 */} <ambientLight intensity={0.5} /> {/* 平行光，用于产生阴影 */} <directionalLight position={[10, 10, 5]} intensity={1} castShadow shadow-mapSize-width={2048} shadow-mapSize-height={2048} /> {/* 辅助网格地面 */} <Grid args={[100, 100]} cellColor="#cccccc" sectionColor="#888888" /> {/* 相机控制器 */} <OrbitControls makeDefault enableDamping dampingFactor={0.05} /> {/* 性能监控面板（开发时使用） */} <Stats /> {/* 后续我们的家具模型、房间等将在这里添加 */} </Canvas> </div> ); }; export default EditorCanvas;

在App.tsx中引入这个画布，你现在应该能看到一个灰色的 3D 空间，可以用鼠标拖拽旋转、滚轮缩放。

3. 实现核心编辑功能：资产放置与变换

这是编辑器的核心交互。我们需要实现：从资产库拖拽一个家具模型到画布中，并可以用工具移动、旋转、缩放它。

3.1 定义场景状态与资产类型

首先，在src/types/scene.ts中定义数据类型。

// 场景中一个物体的基本属性 export interface SceneObject { id: string; // 唯一标识 type: 'furniture' | 'wall' | 'floor' | 'light'; assetId: string; // 对应资产库中的ID name: string; position: [number, number, number]; // [x, y, z] rotation: [number, number, number]; // [x, y, z] 弧度制 scale: [number, number, number]; // 其他自定义属性，如材质颜色、是否可碰撞等 userData?: Record<string, any>; } // 资产库中的一项 export interface AssetItem { id: string; name: string; category: string; // 如 ‘沙发’， ‘桌子’ thumbnailUrl: string; modelUrl: string; // GLTF/GLB 文件路径 dimensions: { width: number; height: number; depth: number }; // 模型原始尺寸 }

然后，在src/stores/useSceneStore.ts中创建 Zustand Store 来管理全局场景状态。

import create from 'zustand'; import { SceneObject } from '../types/scene'; interface SceneState { // 场景中的物体列表 objects: Record<string, SceneObject>; // 用 Map 或 Record 存储， key 为 id // 当前选中的物体ID selectedObjectId: string | null; // 操作历史（简化版，用于撤销重做） history: { past: SceneObject[][]; future: SceneObject[][]; }; // Actions addObject: (obj: Omit<SceneObject, 'id'>) => void; updateObject: (id: string, updates: Partial<SceneObject>) => void; removeObject: (id: string) => void; setSelectedObjectId: (id: string | null) => void; // 撤销/重做相关 Action undo: () => void; redo: () => void; // 保存当前状态到历史记录 snapshot: () => void; } const useSceneStore = create<SceneState>((set, get) => ({ objects: {}, selectedObjectId: null, history: { past: [], future: [] }, addObject: (objData) => { const newId = `obj_${Date.now()}`; const newObj: SceneObject = { ...objData, id: newId }; set((state) => ({ objects: { ...state.objects, [newId]: newObj }, })); get().snapshot(); // 添加操作后保存快照 }, updateObject: (id, updates) => { set((state) => { const oldObj = state.objects[id]; if (!oldObj) return state; return { objects: { ...state.objects, [id]: { ...oldObj, ...updates }, }, }; }); // 注意：频繁的更新（如拖拽）不应每次都 snapshot，否则历史记录会爆炸。 // 通常会在拖拽结束后 snapshot。 }, removeObject: (id) => { set((state) => { const newObjects = { ...state.objects }; delete newObjects[id]; return { objects: newObjects }; }); get().snapshot(); }, setSelectedObjectId: (id) => set({ selectedObjectId: id }), undo: () => { set((state) => { const past = state.history.past; if (past.length === 0) return state; const previous = past[past.length - 1]; const newPast = past.slice(0, -1); // 将当前状态存入 future const currentObjectsArray = Object.values(state.objects); return { objects: arrayToObject(previous), history: { past: newPast, future: [currentObjectsArray, ...state.history.future], }, }; }); }, redo: () => { // 与 undo 逻辑对称，略 }, snapshot: () => { set((state) => { const currentObjectsArray = Object.values(state.objects); // 只保留最近 N 条历史，避免内存泄漏 const newPast = [...state.history.past, currentObjectsArray].slice(-50); return { history: { past: newPast, future: [], // 新的操作会清空重做栈 }, }; }); }, })); // 辅助函数 function arrayToObject(arr: SceneObject[]): Record<string, SceneObject> { return arr.reduce((acc, obj) => ({ ...acc, [obj.id]: obj }), {}); } export default useSceneStore;

3.2 实现资产加载与模型组件

创建一个通用的模型加载组件src/components/EditorCanvas/Model.tsx。

import React, { useRef, useEffect } from 'react'; import { useLoader } from '@react-three/fiber'; import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader'; import * as THREE from 'three'; import { SceneObject } from '../../types/scene'; interface ModelProps { data: SceneObject; isSelected: boolean; onClick: (event: any) => void; } const Model: React.FC<ModelProps> = ({ data, isSelected, onClick }) => { const groupRef = useRef<THREE.Group>(null); // 假设我们有一个映射表，将 assetId 映射到实际的模型文件路径 // 这里简化处理，直接拼接路径 const modelPath = `/assets/models/${data.assetId}.glb`; // 加载 GLTF 模型 const gltf = useLoader(GLTFLoader, modelPath); // 当数据更新时，同步 Three.js 对象的位置、旋转、缩放 useEffect(() => { if (groupRef.current) { groupRef.current.position.set(...data.position); groupRef.current.rotation.set(...data.rotation); groupRef.current.scale.set(...data.scale); } }, [data.position, data.rotation, data.scale]); // 克隆场景以避免多个实例引用同一份几何数据 const clonedScene = React.useMemo(() => gltf.scene.clone(), [gltf.scene]); return ( <group ref={groupRef} onClick={onClick}> <primitive object={clonedScene} /> {/* 选中高亮效果：用一个半透明的盒子包裹 */} {isSelected && ( <mesh> <boxGeometry args={[1.1, 1.1, 1.1]} /> {/* 根据模型尺寸动态计算更好 */} <meshBasicMaterial color="orange" transparent opacity={0.3} wireframe /> </mesh> )} </group> ); }; export default Model;

在EditorCanvas组件中，遍历 Store 中的 objects 并渲染它们。

// 在 EditorCanvas 组件内部 import useSceneStore from '../../stores/useSceneStore'; import Model from './Model'; const EditorCanvas: React.FC = () => { const { objects, selectedObjectId, setSelectedObjectId } = useSceneStore(); const handleObjectClick = (event: any, objectId: string) => { event.stopPropagation(); // 阻止事件冒泡到画布 setSelectedObjectId(objectId); }; return ( <Canvas ...> {/* ... 灯光、网格等 ... */} {/* 渲染所有场景物体 */} {Object.values(objects).map((obj) => ( <Model key={obj.id} data={obj} isSelected={selectedObjectId === obj.id} onClick={(e) => handleObjectClick(e, obj.id)} /> ))} {/* 地面 */} <mesh rotation={[-Math.PI / 2, 0, 0]} receiveShadow> <planeGeometry args={[100, 100]} /> <shadowMaterial opacity={0.3} /> </mesh> </Canvas> ); };

3.3 集成变换工具与拖拽更新

我们需要在选中物体时，显示 Three.js 的TransformControls，并监听其变换事件来更新 Store。

首先，安装并引入TransformControls。注意，@react-three/drei提供了封装好的TransformControls组件。

// 在 EditorCanvas 组件中新增 import { TransformControls } from '@react-three/drei'; import { useThree } from '@react-three/fiber'; const EditorCanvas: React.FC = () => { const { objects, selectedObjectId, updateObject, setSelectedObjectId } = useSceneStore(); const { camera, gl } = useThree(); // 获取相机和 WebGL 渲染器 const selectedObject = selectedObjectId ? objects[selectedObjectId] : null; const handleTransformChange = () => { if (!selectedObjectId || !transformControlsRef.current) return; const controls = transformControlsRef.current; const object = controls.object; // 被控制的 3D 对象 if (object) { // 从 Three.js 对象中获取最新的变换数据 const position: [number, number, number] = [object.position.x, object.position.y, object.position.z]; const rotation: [number, number, number] = [object.rotation.x, object.rotation.y, object.rotation.z]; const scale: [number, number, number] = [object.scale.x, object.scale.y, object.scale.z]; // 更新 Store updateObject(selectedObjectId, { position, rotation, scale }); } }; const handleTransformEnd = () => { // 变换结束后，保存一次快照，用于撤销 useSceneStore.getState().snapshot(); }; const transformControlsRef = useRef<any>(null); // TransformControls 的引用 return ( <Canvas ...> {/* ... 其他组件 ... */} {/* 渲染选中的物体 */} {selectedObject && ( <TransformControls ref={transformControlsRef} object={/* 这里需要获取到选中物体对应的 Three.js 对象，实现略复杂，需要建立映射 */} mode="translate" // 初始模式：移动。可切换为 'rotate' 或 'scale' onObjectChange={handleTransformChange} onMouseUp={handleTransformEnd} // 鼠标松开时结束 /> )} {/* 点击画布空白处取消选中 */} <mesh onClick={() => setSelectedObjectId(null)} visible={false}> <planeGeometry args={[100, 100]} /> <meshBasicMaterial transparent opacity={0} /> </mesh> </Canvas> ); };

这里有一个关键问题：TransformControls需要一个 Three.js 对象作为object属性。我们需要建立一个从SceneObject.id到实际 Three.js 对象（THREE.Group或THREE.Mesh）的映射。这通常通过 React 的ref和 Context 来实现，是一个工程难点。一种简化方案是，在Model组件内部，如果它被选中，则将自己（groupRef.current）通过 Context 或回调函数传递给父组件。

3.4 构建资产库 UI 与拖拽放置

创建一个侧边栏组件src/components/UI/AssetPanel.tsx来展示资产库。

import React from 'react'; import { Card, Row, Col } from 'antd'; import { useDrag } from 'react-dnd'; // 需要安装 react-dnd import { AssetItem } from '../../types/scene'; // 模拟资产数据 const mockAssets: AssetItem[] = [ { id: 'chair_01', name: '现代椅子', category: '椅子', thumbnailUrl: '/thumb/chair.jpg', modelUrl: '/models/chair.glb', dimensions: { width: 0.5, height: 1, depth: 0.5 } }, { id: 'table_01', name: '木质餐桌', category: '桌子', thumbnailUrl: '/thumb/table.jpg', modelUrl: '/models/table.glb', dimensions: { width: 1.2, height: 0.8, depth: 0.8 } }, // ... 更多资产 ]; const AssetPanel: React.FC = () => { return ( <div style={{ width: 300, padding: '16px', background: '#fff', height: '100vh', overflowY: 'auto' }}> <h3>资产库</h3> <Row gutter={[16, 16]}> {mockAssets.map((asset) => ( <Col span={12} key={asset.id}> <AssetCard asset={asset} /> </Col> ))} </Row> </div> ); }; // 可拖拽的资产卡片 const AssetCard: React.FC<{ asset: AssetItem }> = ({ asset }) => { const [{ isDragging }, dragRef] = useDrag({ type: 'ASSET', item: { asset }, collect: (monitor) => ({ isDragging: monitor.isDragging(), }), }); return ( <div ref={dragRef as any} style={{ opacity: isDragging ? 0.5 : 1 }}> <Card hoverable cover={<img alt={asset.name} src={asset.thumbnailUrl} />} size="small"> <Card.Meta title={asset.name} description={asset.category} /> </Card> </div> ); }; export default AssetPanel;

在画布组件中，我们需要监听放置事件，计算 3D 空间中的放置位置，并调用addObject。

// 在 EditorCanvas 组件中 import { useThree } from '@react-three/fiber'; import { useDrop } from 'react-dnd'; import * as THREE from 'three'; const EditorCanvas: React.FC = () => { const { scene, camera, raycaster, mouse, gl } = useThree(); const addObject = useSceneStore((state) => state.addObject); const [, dropRef] = useDrop({ accept: 'ASSET', drop: (item: { asset: AssetItem }, monitor) => { // 获取鼠标在画布上的位置 const clientOffset = monitor.getClientOffset(); if (!clientOffset) return; // 将屏幕坐标转换为 NDC 坐标 (-1 to 1) const rect = gl.domElement.getBoundingClientRect(); const x = ((clientOffset.x - rect.left) / rect.width) * 2 - 1; const y = -((clientOffset.y - rect.top) / rect.height) * 2 + 1; // 使用射线投射，计算与地平面的交点 raycaster.setFromCamera(new THREE.Vector2(x, y), camera); const groundPlane = new THREE.Plane(new THREE.Vector3(0, 1, 0), 0); // Y=0 的平面 const intersectionPoint = new THREE.Vector3(); raycaster.ray.intersectPlane(groundPlane, intersectionPoint); // 创建新的场景对象 const newObject: Omit<SceneObject, 'id'> = { type: 'furniture', assetId: item.asset.id, name: item.asset.name, position: [intersectionPoint.x, 0, intersectionPoint.z], // 放在地面上 rotation: [0, 0, 0], scale: [1, 1, 1], }; addObject(newObject); }, }); // 将 drop 绑定到画布 useEffect(() => { dropRef(gl.domElement); }, [gl.domElement, dropRef]); return ( // ... Canvas 内容 ); };

至此，我们已经实现了从资产库拖拽模型到 3D 场景，并可以通过变换工具对其进行移动、旋转和缩放的基本编辑器功能。状态管理确保了所有操作可追溯，为撤销重做打下了基础。

4. 高级功能实现与性能优化

基础功能跑通后，一个可用的编辑器还需要更多高级功能和优化。

4.1 实现撤销与重做

我们在 Store 中已经定义了undo,redo,snapshot的骨架。关键点在于何时创建快照（snapshot）。不应在每次updateObject（如拖拽中）都创建，否则历史记录会瞬间膨胀。最佳实践是：

• 离散操作后快照：添加物体、删除物体、粘贴、应用材质等。
• 连续操作结束时快照：物体变换（移动、旋转、缩放）结束、绘制墙体结束。

我们需要修改handleTransformEnd和addObject等 Action，确保它们调用snapshot。然后，在 UI 上添加撤销/重做按钮，并绑定键盘快捷键（Ctrl+Z, Ctrl+Y）。

// 在 UI 组件中 import useSceneStore from '../stores/useSceneStore'; import { Button } from 'antd'; const Toolbar: React.FC = () => { const { undo, redo, history } = useSceneStore(); return ( <div> <Button onClick={undo} disabled={history.past.length === 0}>撤销 (Ctrl+Z)</Button> <Button onClick={redo} disabled={history.future.length === 0}>重做 (Ctrl+Y)</Button> </div> ); }; // 在 App.tsx 或画布组件中监听全局键盘事件 useEffect(() => { const handleKeyDown = (e: KeyboardEvent) => { if (e.ctrlKey || e.metaKey) { if (e.key === 'z') { e.preventDefault(); useSceneStore.getState().undo(); } else if (e.key === 'y') { e.preventDefault(); useSceneStore.getState().redo(); } } }; window.addEventListener('keydown', handleKeyDown); return () => window.removeEventListener('keydown', handleKeyDown); }, []);

4.2 模型加载优化与缓存

频繁加载同一模型会导致网络请求重复和内存浪费。我们需要一个资产加载器来管理缓存。

// src/core/assets/AssetManager.ts import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader'; import * as THREE from 'three'; class AssetManager { private gltfLoader: GLTFLoader; private cache: Map<string, THREE.Group> = new Map(); constructor() { this.gltfLoader = new GLTFLoader(); } async loadGLTF(url: string): Promise<THREE.Group> { if (this.cache.has(url)) { // 返回缓存的模型的克隆 return this.cloneModel(this.cache.get(url)!); } return new Promise((resolve, reject) => { this.gltfLoader.load( url, (gltf) => { const model = gltf.scene; // 遍历模型，优化材质和几何体 model.traverse((child) => { if (child instanceof THREE.Mesh) { child.castShadow = true; child.receiveShadow = true; // 合并几何体、压缩纹理等优化可以在这里进行 } }); this.cache.set(url, model); resolve(this.cloneModel(model)); }, undefined, reject ); }); } private cloneModel(model: THREE.Group): THREE.Group { // 深度克隆，避免多个实例共享同一份几何和材质引用 return model.clone(true); } dispose() { this.cache.forEach((model) => { model.traverse((child) => { if (child instanceof THREE.Mesh) { child.geometry?.dispose(); if (Array.isArray(child.material)) { child.material.forEach(m => m.dispose()); } else { child.material?.dispose(); } } }); }); this.cache.clear(); } } export const assetManager = new AssetManager();

在Model组件中，使用这个AssetManager来加载模型。

4.3 性能监控与渲染优化

随着场景中物体增多，性能会成为瓶颈。以下是一些关键优化点：

1. 几何体合并（Geometry Merging）：对于大量相同的静态小物体（如地板瓷砖、书籍），可以合并其几何体以减少 Draw Call。使用THREE.BufferGeometryUtils.mergeBufferGeometries。
2. 细节层次（LOD）：为复杂模型创建多个细节程度的版本，根据物体与相机的距离切换。@react-three/drei提供了<LOD>组件。
3. 视锥体剔除（Frustum Culling）：Three.js 默认开启。确保物体的frustumCulled属性为true。
4. 实例化渲染（InstancedMesh）：对于大量完全相同的物体（如一片森林中的树），使用THREE.InstancedMesh可以极大提升性能。
5. 使用 Stats.js 监控：我们在画布中已经添加了<Stats />组件，可以实时查看帧率（FPS）、渲染时间。

// 在 EditorCanvas 中启用性能监控 import { Stats } from '@react-three/drei'; // ... <Stats />

4.4 场景导出与导入

编辑完成后，需要将场景数据保存。我们只需要将useSceneStore.getState().objects序列化为 JSON。

// src/utils/sceneExport.ts import { SceneObject } from '../types/scene'; export function exportSceneToJSON(objects: Record<string, SceneObject>): string { const exportData = { version: '1.0', objects: Object.values(objects).map(obj => ({ ...obj, // 确保位置等数组被正确序列化 position: obj.position, rotation: obj.rotation, scale: obj.scale, })), }; return JSON.stringify(exportData, null, 2); } export function importSceneFromJSON(jsonString: string): Omit<SceneObject, 'id'>[] { const data = JSON.parse(jsonString); // 这里可以添加版本校验和数据迁移逻辑 return data.objects; }

在 UI 中添加导出/导入按钮，调用上述函数并与文件系统或后端 API 交互。

5. 常见问题排查与最佳实践

在开发过程中，你一定会遇到各种问题。以下是一些典型问题及其排查路径。

5.1 模型加载失败或显示异常

5.2 交互响应迟钝或卡顿

5.3 状态管理与数据流混乱

5.4 生产环境部署注意事项

1. 模型压缩：使用glTF-Pipeline或gltfpack对 GLB 文件进行压缩和优化，减少加载体积。
2. CDN 加速：将模型等静态资源部署到 CDN，提升加载速度。
3. 代码分包：使用构建工具（如 Vite）的代码分割功能，将 Three.js 等较大库单独打包，异步加载。
4. 错误边界：在 React 组件树顶层添加错误边界（Error Boundary），防止 3D 渲染错误导致整个应用崩溃。
5. 内存泄漏：在组件卸载时，务必清理 Three.js 的几何体、材质和纹理。@react-three/fiber会自动处理大部分，但自定义的loaders和managers需要手动dispose。
6. 浏览器兼容性：明确告知用户需要支持 WebGL 2.0 的现代浏览器。可以在入口处进行能力检测。

构建一个大型 3D 家居编辑器是一个系统工程，本文涵盖了从项目初始化、核心交互实现到性能优化的主要路径。真正的挑战在于细节的打磨：更精准的碰撞检测、更复杂的墙体绘制与编辑、更真实的材质与光照、以及与后端的数据同步。建议在核心链路跑通后，针对特定功能模块进行深入研究和迭代。开源项目的价值在于提供了完整的、可参考的实现，理解其架构设计比复制代码更为重要。下一步，你可以尝试为编辑器添加房间户型绘制、材质替换、光照编辑等高级功能，逐步将其完善为一个真正可用的产品原型。