---

name: threejs-skills description: "使用 Three.js 创建 3D 场景、交互体验和视觉效果。当用户请求 3D 图形、WebGL 体验、3D 可视化、动画或交互式 3D 元素时使用。" risk: safe source: "https://github.com/CloudAI-X/threejs-skills" date_added: "2026-02-27"

Three.js 技能

系统化地使用 Three.js 最佳实践创建高质量 3D 场景和交互体验。

何时使用

• 请求 3D 可视化或图形（"创建 3D 模型"、"以 3D 展示"）
• 需要交互式 3D 体验（"旋转立方体"、"可探索场景"）
• 需要 WebGL 或基于 canvas 的渲染
• 要求动画、粒子或视觉效果
• 提到 Three.js、WebGL 或 3D 渲染
• 想在 3D 空间中可视化数据

核心设置模式

1. 基本 Three.js 导入

使用 ES 模块 import maps（Three.js r183+）：

<script type="importmap">
{
  "imports": {
    "three": "https://cdn.jsdelivr.net/npm/three@0.183.0/build/three.module.js",
    "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.183.0/examples/jsm/"
  }
}
</script>
<script type="module">
import * as THREE from "three";
import { OrbitControls } from "three/addons/controls/OrbitControls.js";
</script>

生产环境使用 npm/vite/webpack：

import * as THREE from "three";
import { OrbitControls } from "three/addons/controls/OrbitControls.js";

2. 场景初始化

每个 Three.js 作品需要这些核心组件：

// 场景 - 包含所有 3D 对象
const scene = new THREE.Scene();

// 相机 - 定义观察视角
const camera = new THREE.PerspectiveCamera(
  75, // 视场角
  window.innerWidth / window.innerHeight, // 宽高比
  0.1, // 近裁剪面
  1000, // 远裁剪面
);
camera.position.z = 5;

// 渲染器 - 绘制场景
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);

3. 动画循环

使用 renderer.setAnimationLoop()（推荐）或 requestAnimationFrame：

// 推荐：setAnimationLoop（处理 WebXR 兼容性）
renderer.setAnimationLoop(() => {
  mesh.rotation.x += 0.01;
  mesh.rotation.y += 0.01;
  renderer.render(scene, camera);
});

系统化开发流程

1. 定义场景

首先确定：

• 需要渲染什么对象
• 相机位置和视场角
• 所需的灯光设置
• 交互模型（静态、旋转、用户控制）

2. 构建几何体

选择合适的几何体类型：

基本形状：

• BoxGeometry - 立方体、长方体
• SphereGeometry - 球体、行星
• CylinderGeometry - 圆柱体、管道
• PlaneGeometry - 平面、地面
• TorusGeometry - 环面、圆环

new THREE.CapsuleGeometry(0.5, 1, 4, 8); // 半径, 长度, 端盖段数, 径向段数

3. 应用材质

根据视觉需求选择材质：

• MeshBasicMaterial - 无光照，纯色（不需要灯光）
• MeshStandardMaterial - 基于物理，逼真（需要灯光）
• MeshPhongMaterial - 带高光反射的光亮表面
• MeshLambertMaterial - 哑光表面，漫反射

const material = new THREE.MeshStandardMaterial({
  color: 0x00ff00,
  metalness: 0.5,
  roughness: 0.5,
});

4. 添加灯光

如果使用有光照材质（Standard、Phong、Lambert），添加灯光：

// 环境光 - 整体照明
const ambientLight = new THREE.AmbientLight(0xffffff, 0.5);
scene.add(ambientLight);

// 平行光 - 类似阳光
const directionalLight = new THREE.DirectionalLight(0xffffff, 0.8);
directionalLight.position.set(5, 5, 5);
scene.add(directionalLight);

使用 MeshBasicMaterial 时跳过灯光——它设计上就是无光照的。

5. 处理响应式

始终添加窗口大小调整处理：

window.addEventListener("resize", () => {
  camera.aspect = window.innerWidth / window.innerHeight;
  camera.updateProjectionMatrix();
  renderer.setSize(window.innerWidth, window.innerHeight);
});

常见模式

旋转对象

renderer.setAnimationLoop(() => {
  mesh.rotation.x += 0.01;
  mesh.rotation.y += 0.01;
  renderer.render(scene, camera);
});

OrbitControls 轨道控制

import { OrbitControls } from "three/addons/controls/OrbitControls.js";

const controls = new OrbitControls(camera, renderer.domElement);
controls.enableDamping = true;