Vue3 + Three.js 实战入门：从零搭建可交互3D场景（含模型加载与性能优化）

本文面向有Vue基础但Three.js零基础的前端开发者，完整演示如何在Vue3项目中集成Three.js创建交互式3D场景。内容涵盖：Vite环境初始化、Three.js核心三要素（场景/相机/渲染器）配置、光照与基础几何体创建、轨道控制器实现交互、glTF模型加载、动画循环与响应式适配。文章提供可运行的完整代码示例，并包含5个关键性能优化技巧和常见错误排查指南，帮助开发者快速上手3D可视化开发。

一、前言：为什么选择Vue3 + Three.js？

1.1 技术选型背景

随着WebGL技术的成熟和浏览器性能的提升，3D可视化在前端领域的应用越来越广泛。Three.js作为最流行的WebGL框架，提供了简洁的API和丰富的功能，而Vue3的响应式系统和组件化架构，使得复杂3D应用的开发变得更加高效。

技术栈优势：

Three.js：封装了WebGL底层细节，提供直观的3D编程接口
Vue3：组合式API更适合复杂状态管理，TypeScript支持完善
Vite：极速的开发服务器和构建工具，提升开发体验

1.2 学习目标与预期成果

通过本文学习，你将能够：

在Vue3项目中正确集成Three.js
创建包含几何体、光照、交互的完整3D场景
加载并显示glTF格式的3D模型
实现基本的性能优化和错误处理
获得一个可复用的3D场景组件模板

1.3 前置知识要求

熟悉Vue3基础语法和组件开发
了解JavaScript/TypeScript基础
对3D概念（坐标系、几何体、材质）有基本了解

本节你学会了什么：理解了Vue3 + Three.js技术栈的优势和学习目标。

二、环境搭建与项目初始化

2.1 创建Vite + Vue3项目

打开终端，执行以下命令创建项目：

bash 复制代码

npm create vite@latest vue3-threejs-demo -- --template vue
cd vue3-threejs-demo
npm install

选择Vue模板，TypeScript可选（本文使用JavaScript保持简洁）。

2.2 安装Three.js及相关依赖

安装核心依赖：

bash 复制代码

npm install three
npm install @types/three --save-dev  # TypeScript用户需要

安装轨道控制器（非Three.js核心包，需单独安装）：

bash 复制代码

npm install three-orbitcontrols-ts  # 或使用其他兼容包

2.3 项目目录结构设计

创建合理的目录结构：

复制代码

src/
├── components/
│   └── ThreeScene.vue      # 3D场景主组件
├── utils/
│   └── threeUtils.js       # Three.js工具函数
├── assets/
│   ├── models/             # 3D模型文件
│   └── textures/           # 纹理贴图
├── App.vue                 # 主应用组件
└── main.js                 # 应用入口

本节你学会了什么：完成了项目环境搭建和依赖安装。

三、Three.js核心概念快速入门

3.1 场景(Scene)：3D世界的容器

场景是所有3D对象的容器，类似于HTML中的``标签。所有要显示的物体、光源、相机都需要添加到场景中。

3.2 相机(Camera)：观察3D世界的视角

相机决定了我们从哪个角度观察3D场景。最常用的是透视相机(PerspectiveCamera)，模拟人眼视角，有近大远小的效果。

3.3 渲染器(Renderer)：将3D场景绘制到2D屏幕

渲染器负责将3D场景渲染到HTML Canvas元素上。WebGLRenderer使用WebGL API进行硬件加速渲染。

本节你学会了什么：掌握了Three.js三大核心概念：场景、相机、渲染器。

四、创建第一个3D场景

4.1 初始化Three.js三要素

在ThreeScene.vue组件中，我们首先初始化Three.js的核心对象：

javascript 复制代码

import * as THREE from 'three';

// 创建场景
const scene = new THREE.Scene();
scene.background = new THREE.Color(0x87CEEB); // 天空蓝背景

// 创建透视相机
const camera = new THREE.PerspectiveCamera(
  75, // 视野角度(FOV)
  window.innerWidth / window.innerHeight, // 宽高比
  0.1, // 近裁剪面
  1000 // 远裁剪面
);
camera.position.set(0, 2, 5); // 设置相机位置

// 创建WebGL渲染器
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(window.innerWidth, window.innerHeight);
renderer.setPixelRatio(window.devicePixelRatio); // 适配高清屏

4.2 添加基础几何体（立方体）

创建并添加一个彩色立方体到场景：

javascript 复制代码

// 创建立方体几何体
const geometry = new THREE.BoxGeometry(1, 1, 1);

// 创建基础材质（绿色）
const material = new THREE.MeshBasicMaterial({ color: 0x00ff00 });

// 创建网格(Mesh)：几何体 + 材质
const cube = new THREE.Mesh(geometry, material);

// 添加到场景
scene.add(cube);

4.3 设置光照（环境光+点光源）

为了让物体有立体感，我们需要添加光照：

javascript 复制代码

// 添加环境光（整体亮度）
const ambientLight = new THREE.AmbientLight(0xffffff, 0.5);
scene.add(ambientLight);

// 添加点光源（产生阴影和明暗效果）
const pointLight = new THREE.PointLight(0xffffff, 1);
pointLight.position.set(5, 5, 5);
scene.add(pointLight);

// 使用标准材质以响应光照
const standardMaterial = new THREE.MeshStandardMaterial({ color: 0x00ff00 });
cube.material = standardMaterial;

4.4 实现动画循环

创建动画循环，让立方体旋转：

javascript 复制代码

function animate() {
  requestAnimationFrame(animate);
  
  // 立方体旋转动画
  cube.rotation.x += 0.01;
  cube.rotation.y += 0.01;
  
  // 渲染场景
  renderer.render(scene, camera);
}

animate();

本节你学会了什么：创建了包含几何体、光照和动画的完整3D场景。

五、交互功能实现

5.1 集成轨道控制器(OrbitControls)

轨道控制器允许用户通过鼠标拖拽、滚轮缩放来交互：

javascript 复制代码

import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls';

// 创建轨道控制器
const controls = new OrbitControls(camera, renderer.domElement);

// 配置控制器参数
controls.enableDamping = true; // 启用阻尼效果，更平滑
controls.dampingFactor = 0.05;
controls.screenSpacePanning = false;
controls.maxPolarAngle = Math.PI; // 垂直旋转角度限制
controls.minDistance = 1;
controls.maxDistance = 50;

// 在动画循环中更新控制器
function animate() {
  requestAnimationFrame(animate);
  controls.update(); // 必须在渲染前调用
  renderer.render(scene, camera);
}

5.2 鼠标拖拽、缩放、旋转功能

控制器默认提供：

左键拖拽：旋转视角
右键拖拽：平移场景
滚轮：缩放视角

5.3 窗口自适应与响应式处理

监听窗口大小变化，更新相机和渲染器：

javascript 复制代码

function onWindowResize() {
  // 更新相机宽高比
  camera.aspect = window.innerWidth / window.innerHeight;
  camera.updateProjectionMatrix();
  
  // 更新渲染器尺寸
  renderer.setSize(window.innerWidth, window.innerHeight);
}

window.addEventListener('resize', onWindowResize);

// 组件销毁时移除监听
onUnmounted(() => {
  window.removeEventListener('resize', onWindowResize);
});

本节你学会了什么：实现了完整的鼠标交互和响应式适配。