简介：这是一套基于 Vue3 构建的轻量级 Three.js 3D 场景编辑器前端实现，面向 Web 3D 开发初学者与中级前端工程师，解决快速搭建、可视化编辑及导出标准 3D 场景的技术门槛问题。资源包共230个文件，含102个核心 JS 模块（涵盖场景管理、模型加载、UI 交互逻辑）、95张 JPG 材质贴图、20个 CSS 样式文件（含 Element Plus 与自定义组件样式），以及 Wasm 加速模块和基础 HTML 入口，整体压缩后仅12.1MB，开箱即用。目前已有2974人学习下载，适合希望深入理解 three.js 场景序列化、Vue3 组合式 API 与 3D 编辑器架构的开发者。下载后可直接启动本地服务运行，支持 ZIP 场景导入/导出，并兼容 scene-view 解析器渲染；代码结构清晰，含完整构建配置（Vite）、组件化 threeView 封装及多层级样式隔离设计，便于二次开发与教学演示。
1. Three.js 3D 场景编辑器（Vue3 版本）：不是玩具，是能导出 glTF、实时拖拽、支持材质/灯光/相机自由配置的生产级前端 3D 工具链
你有没有试过在 Vue 项目里嵌一个可交互的 3D 场景，结果发现：加个球体要抄 50 行 Three.js 原生代码，改个材质得手动 new MeshStandardMaterial 再 setValues，想让设计师调灯光？不好意思，得改 JS 变量再热更新——这根本不是编辑器，是调试器。而这个 Vue3 + Three.js 3D 场景编辑器，就是为解决这类“前端做 3D 但不配用编辑器”的现实翻车现场而生的。它不是一个 demo 页面，而是一套完整封装的、带 UI 面板、支持图层树管理、属性实时绑定、场景序列化/反序列化、最终可导出标准 glTF 2.0 文件的工程化组件库。适合需要快速集成 3D 内容配置能力的中后台系统（比如数字孪生看板、产品可视化配置台、AR 内容预览平台），也适合教学场景下让学生绕过底层 API 烦琐，专注空间逻辑与交互设计。它不替代 Three.js，而是把 Three.js 的 80% 重复劳动封装进响应式系统里——Vue3 的 setup 语法糖 + reactive + computed 是它的骨架，Three.js 的 Scene / Object3D / Material 是它的肌肉，而 glTF 导出能力，是它能真正落地的最后一块拼图。
2. 核心架构解析：为什么选 Vue3 而非 React 或纯 Three.js？三个不可妥协的技术动因
2.1 响应式驱动 3D 对象状态：从“手动同步”到“自动映射”
Three.js 本身是命令式 API：修改 position.x 后，必须显式调用 renderer.render() 才能生效；而 Vue3 的 reactive 对象一旦被 proxy 包裹，任何属性变更都会触发依赖收集。本编辑器的关键设计，是将每个 Object3D 实例（如 Mesh、Light、Camera）的可编辑属性（position、rotation、scale、intensity、color、roughness 等）全部映射为 reactive ref 或 reactive 对象字段：
// packages/editor/src/composables/useObject3D.ts export function useObject3D(object: Object3D) { const props = reactive({ name: object.name, visible: object.visible, position: { x: object.position.x, y: object.position.y, z: object.position.z }, rotation: { x: object.rotation.x, y: object.rotation.y, z: object.rotation.z }, scale: { x: object.scale.x, y: object.scale.y, z: object.scale.z } }); // 双向同步：UI 修改 → Three.js 实例更新 watch(() => props.position, (val) => { object.position.set(val.x, val.y, val.z); }, { deep: true }); watch(() => props.rotation, (val) => { object.rotation.set(val.x, val.y, val.z); }, { deep: true }); // 反向同步：Three.js 外部修改（如动画、物理引擎）→ UI 面板刷新（需手动触发） // 这里采用“脏检查+节流”策略，避免高频渲染卡顿 let lastSyncTime = 0; const syncFromObject = () => { const now = Date.now(); if (now - lastSyncTime > 16) { // ≈60fps props.position.x = object.position.x; props.position.y = object.position.y; props.position.z = object.position.z; lastSyncTime = now; } }; return { props, syncFromObject }; }提示：
syncFromObject不是自动的，这是刻意设计。因为 Three.js 内部大量使用set()方法直接修改向量/矩阵，不会触发 Vue 的 setter。若强行 patchVector3.prototype.set，会污染全局原型且影响性能。所以采用主动节流同步，既保 UI 准确性，又避掉 99% 的帧率抖动。
2.2 图层树（Layer Tree）与对象生命周期管理：为什么不能只靠 scene.children？
scene.children是一个扁平数组，无法表达父子层级、隐藏/锁定状态、分组折叠等编辑器必需语义。本编辑器引入独立的LayerNode类，作为 UI 图层树的数据源：
// types/layer.ts export interface LayerNode { id: string; name: string; type: 'mesh' | 'light' | 'camera' | 'group' | 'empty'; children: LayerNode[]; parent?: LayerNode; visible: boolean; locked: boolean; expanded: boolean; object3d: Object3D; // 持有真实 Three.js 实例引用 }所有添加/删除/移动操作，都通过LayerManager统一调度：
// packages/editor/src/composables/useLayerManager.ts export function useLayerManager(scene: Scene) { const root = reactive<LayerNode>({ id: 'root', name: 'Scene', type: 'group', children: [], visible: true, locked: false, expanded: true, object3d: scene }); const addNode = (node: LayerNode, parent: LayerNode = root) => { node.parent = parent; parent.children.push(node); // 自动 attach 到 Three.js 父级 if (parent.object3d && node.object3d) { parent.object3d.add(node.object3d); } }; const removeNode = (node: LayerNode) => { const index = node.parent?.children.indexOf(node); if (index !== undefined && index > -1) { node.parent?.children.splice(index, 1); // detach from Three.js node.object3d.parent?.remove(node.object3d); } }; return { root, addNode, removeNode }; }这种设计让“拖拽排序”、“右键分组”、“批量显示/隐藏”等操作变成纯粹的数据操作，UI 层只需v-for渲染root.children，无需关心 Three.js 的 addChild/removeChild 时序。
2.3 材质系统解耦：为什么不用MeshStandardMaterial硬编码？
编辑器支持 5 类材质：MeshBasicMaterial（无光照）、MeshStandardMaterial（PBR）、MeshPhongMaterial（传统高光）、MeshToonMaterial（卡通渲染）、PointsMaterial（粒子）。但若在 UI 中为每种材质写一套表单项，维护成本爆炸。解决方案是：定义材质 Schema，并动态生成表单：
// assets/material-schemas.json { "MeshStandardMaterial": { "properties": { "color": { "type": "color", "default": "#ffffff" }, "metalness": { "type": "number", "min": 0, "max": 1, "step": 0.01, "default": 0.5 }, "roughness": { "type": "number", "min": 0, "max": 1, "step": 0.01, "default": 0.5 }, "emissive": { "type": "color", "default": "#000000" }, "transparent": { "type": "boolean", "default": false }, "opacity": { "type": "number", "min": 0, "max": 1, "step": 0.01, "default": 1 } } } }UI 层根据当前选中对象的material.constructor.name动态加载对应 schema，再用通用<PropertyEditor :schema="currentSchema" v-model="materialProps" />渲染。这样新增一种材质，只需补一行 JSON，无需改任何 Vue 模板或 TS 逻辑。
3. 快速上手：三步集成到你的 Vue3 项目（含完整 CLI 初始化脚本）
3.1 安装与依赖对齐：Three.js 版本锁死是刚需
本编辑器严格适配 Three.js v0.152.2（2023 Q2 LTS 版），不兼容 v0.160+ 的WebGLRenderer.outputColorSpace等新 API。务必确认你的项目未升级至新版：
# 检查当前版本 npm list three # 若高于 0.152.2，强制降级（关键！否则材质渲染全黑） npm install three@0.152.2 # 安装编辑器核心包（注意：非 npm 发布，需本地 link 或 git submodule） git clone https://github.com/xxx/threejs-vue3-editor.git cd threejs-vue3-editor npm install npm run build # 在你的主项目中 link（开发期） cd /path/to/your/vue3-app npm link ../threejs-vue3-editor/packages/editor注意：不要
npm install直接从 GitHub 安装。该仓库未发布至 npm registry，且含packages/多包结构，需先build生成dist/，再link。否则import { Editor } from 'threejs-vue3-editor'会报 module not found。
3.2 最小可用示例：12 行代码启动可编辑场景
在你的src/views/EditorView.vue中：
<template> <div class="editor-container"> <!-- 编辑器主视口 --> <EditorCanvas :scene="scene" :camera="camera" @select="onSelect" /> <!-- 属性面板（自动根据选中对象渲染） --> <PropertyPanel :object="selectedObject" @update="onUpdateProperty" /> </div> </template> <script setup lang="ts"> import { ref, onMounted } from 'vue' import * as THREE from 'three' import { EditorCanvas, PropertyPanel } from 'threejs-vue3-editor' // 1. 创建基础 Three.js 实例 const scene = new THREE.Scene() scene.background = new THREE.Color(0xf0f0f0) const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000) camera.position.set(0, 5, 10) const renderer = new THREE.WebGLRenderer({ antialias: true }) renderer.setSize(window.innerWidth, window.innerHeight) // 2. 添加默认光源和网格 const ambientLight = new THREE.AmbientLight(0xffffff, 0.5) scene.add(ambientLight) const directionalLight = new THREE.DirectionalLight(0xffffff, 1) directionalLight.position.set(5, 10, 7) scene.add(directionalLight) const geometry = new THREE.BoxGeometry(2, 2, 2) const material = new THREE.MeshStandardMaterial({ color: 0x4a9eff }) const mesh = new THREE.Mesh(geometry, material) scene.add(mesh) // 3. 暴露给模板 const selectedObject = ref<THREE.Object3D | null>(mesh) const onSelect = (obj: THREE.Object3D) => { selectedObject.value = obj } const onUpdateProperty = (key: string, value: any) => { if (selectedObject.value) { // 支持嵌套路径如 'position.x' const keys = key.split('.') let target: any = selectedObject.value for (let i = 0; i < keys.length - 1; i++) { target = target[keys[i]] } target[keys[keys.length - 1]] = value } } </script>逻辑说明：
EditorCanvas封装了OrbitControls、resize监听、requestAnimationFrame循环；PropertyPanel接收Object3D实例后，自动解析其类型并渲染对应属性控件。onUpdateProperty是唯一需要你写的胶水函数——它把 UI 输入映射回 Three.js 实例，比原生 Three.js 开发少写 70% 的 boilerplate。
3.3 导出 glTF：一行调用，生成符合 Khronos 官方验证器的二进制文件
编辑器内置GLTFExporter（基于 three.js/examples/jsm/exporters/GLTFExporter ），但做了关键增强：支持dracoCompression、自动烘焙纹理、处理MeshStandardMaterial的 PBR 参数映射：
// 在你的按钮 click 回调中 import { GLTFExporter } from 'threejs-vue3-editor' const exporter = new GLTFExporter() exporter.parse( scene, (gltf) => { // gltf 是 ArrayBuffer，可直接下载 const blob = new Blob([gltf], { type: 'model/gltf-binary' }) const url = URL.createObjectURL(blob) const a = document.createElement('a') a.href = url a.download = 'scene.glb' a.click() URL.revokeObjectURL(url) }, (error) => { console.error('glTF export failed:', error) }, { // 导出选项 binary: true, trs: true, // 是否导出 position/rotation/scale（推荐 true） onlyVisible: true, // 只导出 visible=true 的对象 includeCustomExtensions: true, // 包含自定义扩展（如 KHR_materials_clearcoat） dracoCompression: { // 启用 Draco 压缩（减小 60% 体积） encoderPath: '/draco/', // 需提前部署 draco_encoder.js 到 public/ encodeMethod: 'MESH' } } )参数说明：
binary: true输出.glb（单文件，含二进制 buffer）；onlyVisible: true避免导出被隐藏的调试辅助对象；dracoCompression需额外引入 Draco 3D 库，压缩后模型体积通常降至原始 30~40%，但会增加 100ms 编码耗时——是否开启，取决于你的交付场景（内部预览关，生产交付开）。
4. 避坑指南：五个血泪经验换来的常见问题与排查方案
4.1 现象：场景一片漆黑，控制台无报错，但MeshStandardMaterial完全不显示
原因：Three.js v0.152.2 要求WebGLRenderer必须启用physicallyCorrectLights: true，否则 PBR 材质计算错误。而编辑器默认未设此 flag。
解决：在创建WebGLRenderer后立即设置：
const renderer = new THREE.WebGLRenderer({ antialias: true }) renderer.physicallyCorrectLights = true // ← 关键！漏掉就全黑 renderer.outputColorSpace = THREE.SRGBColorSpace // v0.152.2 兼容写法4.2 现象：拖拽物体时卡顿严重，FPS 低于 10
原因：Vue3 的watch默认深度监听position/rotation/scale对象，每次鼠标移动触发数十次 setter，引发大量Object3D.updateMatrixWorld()计算。
解决：禁用深度监听，改用watchEffect手动控制同步粒度：
// ❌ 错误：deep watch 触发过于频繁 watch(() => props.position, () => { /* ... */ }, { deep: true }) // ✅ 正确：只在 mouseup 后批量同步 let isDragging = false const startDrag = () => { isDragging = true } const endDrag = () => { isDragging = false // 此时才同步一次 object.position.copy(props.position) object.rotation.copy(props.rotation) }编辑器 UI 层已内置该优化，但若你自行封装拖拽逻辑，务必遵循此模式。
4.3 现象：导入 glTF 模型后，材质颜色异常（偏灰/过曝）
原因：glTF 模型自带pbrMetallicRoughness参数，但编辑器默认材质创建时未正确映射baseColorFactor和baseColorTexture。
解决：使用GLTFLoader加载后，遍历scene.traverse，对每个Mesh的material手动标准化：
loader.load('model.gltf', (gltf) => { gltf.scene.traverse((obj) => { if (obj.isMesh && obj.material) { const mat = obj.material as THREE.MeshStandardMaterial // 强制启用 sRGB 纹理 if (mat.map) mat.map.colorSpace = THREE.SRGBColorSpace // 修复金属度/粗糙度范围（glTF 是 0-1，Three.js 也是 0-1，但某些 loader 会错读） mat.metalness = Math.max(0, Math.min(1, mat.metalness)) mat.roughness = Math.max(0, Math.min(1, mat.roughness)) } }) })4.4 现象：点击“导出 glTF”后，浏览器卡死 10 秒以上
原因：场景含高模网格（顶点数 > 50 万）或未压缩纹理（4K PNG），GLTFExporter的序列化过程是 CPU 密集型同步操作。
解决：启用 Web Worker 异步导出（编辑器已内置WorkerGLTFExporter）：
// 替换原 exporter import { WorkerGLTFExporter } from 'threejs-vue3-editor' const workerExporter = new WorkerGLTFExporter() workerExporter.parse(scene, (gltf) => { // 成功回调（在主线程执行） }, (error) => { // 错误回调 })注意：
WorkerGLTFExporter会自动将scene序列化后发送至 Worker，避免主线程阻塞。但需确保scene中无函数引用（如自定义 shader），否则序列化失败。
4.5 现象：Vue Devtools 中看不到EditorCanvas的响应式数据，调试困难
原因：EditorCanvas使用setup()返回ref和computed，但未显式暴露expose，导致 Devtools 无法索引子组件内部状态。
解决：在EditorCanvas.vue的setup中添加：
<script setup> // ... defineExpose({ scene, camera, renderer, controls, isReady: computed(() => !!renderer) }) </script>之后在 Devtools 的 Components 面板中，点击EditorCanvas即可查看所有暴露的响应式属性，极大提升调试效率。
5. 进阶技巧：用自定义着色器（ShaderMaterial）突破编辑器材质限制
编辑器默认材质虽覆盖主流需求，但遇到特殊效果（如边缘光、溶解过渡、UV 动画）时，ShaderMaterial是唯一出路。难点在于：如何让 ShaderMaterial 的 uniform 变量也能被 UI 面板实时编辑？答案是——复用现有 PropertyPanel，只需提供 uniform Schema。
5.1 编写可编辑的 ShaderMaterial
以“溶解效果”为例，顶点着色器需u_dissolveProgress控制溶解阈值，片元着色器需u_dissolveMap采样噪声纹理：
// src/shaders/DissolveShader.ts export const DissolveShader = { uniforms: { u_time: { value: 0 }, u_dissolveProgress: { value: 0.5 }, // ← 关键：这个要暴露给 UI u_dissolveMap: { value: null }, u_baseColor: { value: new THREE.Color(0xffffff) } }, vertexShader: ` varying vec2 vUv; void main() { vUv = uv; gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0); } `, fragmentShader: ` uniform float u_dissolveProgress; uniform sampler2D u_dissolveMap; uniform vec3 u_baseColor; varying vec2 vUv; void main() { float noise = texture2D(u_dissolveMap, vUv).r; if (noise < u_dissolveProgress) discard; gl_FragColor = vec4(u_baseColor, 1.0); } ` } // 创建材质实例 const material = new THREE.ShaderMaterial({ ...DissolveShader, transparent: true, side: THREE.DoubleSide })5.2 为 ShaderMaterial 动态生成 UI Schema
编辑器 PropertyPanel 支持传入customUniforms，格式与材质 Schema 一致：
<!-- 在 PropertyPanel 调用处 --> <PropertyPanel :object="selectedObject" :custom-uniforms="{ u_dissolveProgress: { type: 'number', min: 0, max: 1, step: 0.01, default: 0.5 }, u_baseColor: { type: 'color', default: '#ffffff' } }" />PropertyPanel 内部会自动识别u_开头的 uniform，并将其注入material.uniforms，同时建立双向绑定。你拖动滑块时，material.uniforms.u_dissolveProgress.value实时更新，无需任何额外代码。
5.3 加载纹理并绑定到 uniform（含错误兜底）
u_dissolveMap是sampler2D，需THREE.Texture实例。编辑器提供useTextureLoader组合式函数，自动处理加载状态与错误：
<script setup> import { useTextureLoader } from 'threejs-vue3-editor' const { texture, loading, error } = useTextureLoader('/textures/noise.png') // 绑定到材质 watch(texture, (tex) => { if (tex && selectedObject.value?.material instanceof THREE.ShaderMaterial) { selectedObject.value.material.uniforms.u_dissolveMap.value = tex } }) </script> <template> <div v-if="loading">Loading noise texture...</div> <div v-else-if="error">Texture load failed: {{ error }}</div> <div v-else>Texture ready!</div> </template>这套机制让 ShaderMaterial 从“黑匣子”变成“可配置模块”：美术同学调整
u_dissolveProgress滑块就能预览溶解进度，程序同学只需维护DissolveShader.ts里的 GLSL 逻辑，分工清晰，零耦合。
从那以后我每次接入新 Shader 效果，都强制走一遍uniforms→Schema→UI 绑定三步流程，哪怕只有 1 个 uniform 也要写 Schema。因为跳过这一步，后期维护时谁还记得u_dissolveProgress对应哪个滑块？希望帮到你。
本文还有配套的精品资源，点击获取
