Vue 3 + Three.js 实战：打造交互式3D立方体的完整指南

在当今前端开发领域，3D可视化已经成为提升用户体验的重要技术手段。本文将带你深入探索如何利用Vue 3的Composition API与Three.js最新版本，从零开始构建一个具备完整交互功能的3D立方体。不同于基础教程，我们将重点解决实际开发中的两大痛点：响应式布局和用户交互控制，让你掌握真正可落地的3D开发技巧。

1. 环境准备与项目初始化

1.1 创建Vue 3项目

首先确保你的开发环境已安装Node.js（建议版本16+）和npm/yarn。打开终端，执行以下命令创建Vue 3项目：

npm init vue@latest vue3-threejs-demo
cd vue3-threejs-demo
npm install

选择默认配置或根据需求自定义，我们推荐添加TypeScript支持以获得更好的开发体验。

1.2 安装Three.js及相关依赖

Three.js是构建3D场景的核心库，同时我们需要安装轨道控制器以实现交互功能：

npm install three @types/three
npm install three-orbitcontrols-ts --save-dev

注意：Three.js的类型定义包(@types/three)对于TypeScript项目是必需的，即使使用JavaScript也能提供更好的代码提示。

2. 基础场景搭建

2.1 初始化3D场景

在Vue 3的Composition API中，我们使用 setup() 函数来组织Three.js代码。创建一个新的组件 ThreeScene.vue ：

<template>
  <div ref="container" class="three-container"></div>
</template>

<script lang="ts">
import { ref, onMounted, onUnmounted } from 'vue'
import * as THREE from 'three'
import { OrbitControls } from 'three-orbitcontrols-ts'

export default {
  name: 'ThreeScene',
  setup() {
    const container = ref<HTMLElement | null>(null)
    
    // 场景元素将在onMounted中初始化
    let scene: THREE.Scene
    let camera: THREE.PerspectiveCamera
    let renderer: THREE.WebGLRenderer
    let cube: THREE.Mesh
    let controls: OrbitControls
    let animationId: number

    return {
      container
    }
  }
}
</script>

<style scoped>
.three-container {
  width: 100%;
  height: 100vh;
}
</style>

2.2 核心场景组件实现

在 setup() 函数中添加初始化逻辑：

const initScene = () => {
  // 1. 创建场景
  scene = new THREE.Scene()
  scene.background = new THREE.Color(0xf0f0f0)

  // 2. 创建相机
  camera = new THREE.PerspectiveCamera(
    75,
    window.innerWidth / window.innerHeight,
    0.1,
    1000
  )
  camera.position.z = 10

  // 3. 创建渲染器
  renderer = new THREE.WebGLRenderer({ antialias: true })
  renderer.setSize(window.innerWidth, window.innerHeight)
  container.value?.appendChild(renderer.domElement)

  // 4. 添加立方体
  const geometry = new THREE.BoxGeometry(2, 2, 2)
  const material = new THREE.MeshPhongMaterial({ 
    color: 0x00ff00,
    specular: 0x111111,
    shininess: 30
  })
  cube = new THREE.Mesh(geometry, material)
  scene.add(cube)

  // 5. 添加光源
  const ambientLight = new THREE.AmbientLight(0x404040)
  scene.add(ambientLight)
  
  const directionalLight = new THREE.DirectionalLight(0xffffff, 0.5)
  directionalLight.position.set(1, 1, 1)
  scene.add(directionalLight)

  // 6. 添加轨道控制器
  controls = new OrbitControls(camera, renderer.domElement)
  controls.enableDamping = true
  controls.dampingFactor = 0.05
  controls.autoRotate = true
  controls.autoRotateSpeed = 2

  // 7. 开始动画循环
  animate()
}

const animate = () => {
  animationId = requestAnimationFrame(animate)
  controls.update()
  cube.rotation.x += 0.01
  cube.rotation.y += 0.01
  renderer.render(scene, camera)
}

3. 响应式处理与性能优化

3.1 窗口大小自适应

3D场景需要动态响应窗口尺寸变化，我们添加resize事件监听：

const handleResize = () => {
  camera.aspect = window.innerWidth / window.innerHeight
  camera.updateProjectionMatrix()
  renderer.setSize(window.innerWidth, window.innerHeight)
}

onMounted(() => {
  initScene()
  window.addEventListener('resize', handleResize)
})

onUnmounted(() => {
  window.removeEventListener('resize', handleResize)
  cancelAnimationFrame(animationId)
  container.value?.removeChild(renderer.domElement)
})

3.2 性能优化技巧

1. 按需渲染 ：对于静态场景，可以只在发生变化时渲染
2. 资源清理 ：组件卸载时务必移除DOM元素和事件监听
3. 内存管理 ：复杂场景应定期检查内存使用情况

const cleanup = () => {
  // 释放几何体和材质
  cube.geometry.dispose()
  if (Array.isArray(cube.material)) {
    cube.material.forEach(m => m.dispose())
  } else {
    cube.material.dispose()
  }
  
  // 其他资源清理...
}

4. 高级交互功能实现

4.1 鼠标悬停效果

为立方体添加鼠标悬停高亮效果，首先需要实现射线检测：

const raycaster = new THREE.Raycaster()
const mouse = new THREE.Vector2()
const hoverColor = new THREE.Color(0xff0000)
const originalColor = new THREE.Color(0x00ff00)

const onMouseMove = (event: MouseEvent) => {
  // 将鼠标坐标归一化为设备坐标 (-1到+1)
  mouse.x = (event.clientX / window.innerWidth) * 2 - 1
  mouse.y = -(event.clientY / window.innerHeight) * 2 + 1
  
  // 更新射线
  raycaster.setFromCamera(mouse, camera)
  
  // 计算与立方体的交点
  const intersects = raycaster.intersectObject(cube)
  
  if (intersects.length > 0) {
    (cube.material as THREE.MeshPhongMaterial).color = hoverColor
  } else {
    (cube.material as THREE.MeshPhongMaterial).color = originalColor
  }
}

// 在onMounted中添加事件监听
window.addEventListener('mousemove', onMouseMove, false)

4.2 点击交互与动画

添加点击事件实现立方体弹跳动画：

const onClick = (event: MouseEvent) => {
  mouse.x = (event.clientX / window.innerWidth) * 2 - 1
  mouse.y = -(event.clientY / window.innerHeight) * 2 + 1
  
  raycaster.setFromCamera(mouse, camera)
  const intersects = raycaster.intersectObject(cube)
  
  if (intersects.length > 0) {
    // 使用GSAP实现平滑动画
    const timeline = gsap.timeline()
    timeline.to(cube.position, {
      y: 2,
      duration: 0.3,
      ease: "power1.out"
    }).to(cube.position, {
      y: 0,
      duration: 0.5,
      ease: "bounce.out"
    })
  }
}

// 需要先安装GSAP: npm install gsap

5. 项目结构与最佳实践

5.1 组件化架构建议

对于大型3D项目，推荐采用以下结构：

src/
  components/
    ThreeScene/
      index.vue       # 主场景组件
      controls/       # 交互控制组件
      objects/        # 3D对象组件
      utils/          # Three.js工具函数
  composables/
    useThree.js       # Three.js逻辑复用

5.2 Vue 3与Three.js集成模式

1. Composition API ：将Three.js逻辑封装为可组合函数
2. Provide/Inject ：在组件树中共享渲染器和场景
3. Suspense ：异步加载大型3D模型

// 示例：可复用的Three.js逻辑
export function useThree(container: Ref<HTMLElement | null>) {
  const scene = new THREE.Scene()
  // ...其他初始化代码
  
  return {
    scene,
    camera,
    renderer,
    animate,
    cleanup
  }
}

6. 调试与常见问题解决

6.1 性能分析工具

1. Three.js Stats ：显示帧率、内存等指标
2. Chrome DevTools Performance ：分析渲染性能
3. Three.js Inspector ：浏览器扩展，可视化调试场景

import Stats from 'three/examples/jsm/libs/stats.module'

const stats = Stats()
document.body.appendChild(stats.dom)

// 在animate函数中更新
const animate = () => {
  stats.update()
  // ...其他动画逻辑
}

6.2 常见问题解决方案

问题现象	可能原因	解决方案
场景全黑	缺少光源	添加AmbientLight和DirectionalLight
模型闪烁	深度冲突	调整相机near/far参数或物体位置
交互延迟	高DPI设备	设置renderer.setPixelRatio(window.devicePixelRatio)
内存泄漏	未清理资源	实现完整的cleanup函数

7. 项目扩展方向

7.1 加载复杂3D模型

使用GLTFLoader加载外部模型：

import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader'

const loader = new GLTFLoader()
loader.load(
  'model.glb',
  (gltf) => {
    scene.add(gltf.scene)
  },
  undefined,
  (error) => {
    console.error('加载模型失败:', error)
  }
)

7.2 添加后期处理效果

实现抗锯齿、景深等高级效果：

import { EffectComposer } from 'three/examples/jsm/postprocessing/EffectComposer'
import { RenderPass } from 'three/examples/jsm/postprocessing/RenderPass'
import { UnrealBloomPass } from 'three/examples/jsm/postprocessing/UnrealBloomPass'

const composer = new EffectComposer(renderer)
composer.addPass(new RenderPass(scene, camera))

const bloomPass = new UnrealBloomPass(
  new THREE.Vector2(window.innerWidth, window.innerHeight),
  1.5, 0.4, 0.85
)
composer.addPass(bloomPass)

// 修改animate函数使用composer渲染
const animate = () => {
  composer.render()
}

在实现这个3D立方体项目时，我发现最关键的挑战在于合理管理Three.js的生命周期与Vue组件的生命周期同步。特别是在使用Composition API时，将Three.js的初始化、更新和清理逻辑与组件的挂载和卸载完美对应，才能确保应用的内存使用效率和性能稳定。