Three.js 简介与安装

// WebGL 原生代码（简化版）
const canvas = document.getElementById('canvas')
const gl = canvas.getContext('webgl')

// 编写顶点着色器
const vertexShaderSource = `
  attribute vec4 a_position;
  void main() {
    gl_Position = a_position;
  }
`

// 编写片元着色器
const fragmentShaderSource = `
  precision mediump float;
  void main() {
    gl_FragColor = vec4(1, 0, 0.5, 1);
  }
`

// 创建着色器程序...（需要几十行代码）

// Three.js 代码
const scene = new THREE.Scene()
const camera = new THREE.PerspectiveCamera(75, width / height)
const renderer = new THREE.WebGLRenderer()
renderer.render(scene, camera)

Scene（场景）
  ├── Object3D（3D 对象）
  │   ├── Mesh（网格）= Geometry + Material
  │   ├── Light（光源）
  │   ├── Camera（相机）
  │   └── Group（组）
  └── ...

const scene = new THREE.Scene()
scene.background = new THREE.Color(0xffffff) // 设置背景色

const camera = new THREE.PerspectiveCamera(
  75, // fov: 视野角度（Field of View），0-180度
  window.innerWidth / window.innerHeight, // aspect: 宽高比
  0.1, // near: 近裁剪面，距离相机多近开始渲染
  1000 // far: 远裁剪面，距离相机多远停止渲染
)
camera.position.set(0, 0, 5) // 设置相机位置

// 参数说明：
// - fov: 值越大，视野越广（类似广角镜头）；值越小，视野越窄（类似长焦镜头）
// - aspect: 必须与画布宽高比一致，否则图像会变形
// - near/far: 不在此范围内的对象不会被渲染，合理设置可优化性能

const aspect = window.innerWidth / window.innerHeight
const frustumSize = 5 // 视锥体大小

const camera = new THREE.OrthographicCamera(
  frustumSize * aspect / -2,  // left
  frustumSize * aspect / 2,   // right
  frustumSize / 2,            // top
  frustumSize / -2,           // bottom
  0.1,                        // near
  1000                        // far
)

const renderer = new THREE.WebGLRenderer({
  // 基础配置
  canvas: undefined,           // 指定 canvas 元素，默认自动创建
  context: undefined,          // 指定 WebGL 上下文
  alpha: false,               // 是否支持透明背景
  premultipliedAlpha: true,   // 是否预乘 alpha 值
  antialias: false,           // 是否开启抗锯齿
  stencil: true,              // 是否使用模板缓冲区
  
  // 性能配置
  powerPreference: 'default', // GPU 电源管理: 'default' | 'high-performance' | 'low-power'
  precision: 'highp',         // 着色器精度: 'highp' | 'mediump' | 'lowp'
  
  // 高级配置
  logarithmicDepthBuffer: false, // 对数深度缓冲区（大场景优化）
  preserveDrawingBuffer: false,  // 保留绘图缓冲区（截图需要）
  
  // 后处理相关
  depth: true,                // 深度缓冲区
  failIfMajorPerformanceCaveat: false // 性能警告检测
})

// 常用配置方法
renderer.setSize(width, height)                    // 设置渲染尺寸
renderer.setPixelRatio(window.devicePixelRatio)   // 设置像素比（高清屏适配）
renderer.setClearColor(0x000000, 1)               // 设置背景色
renderer.setClearAlpha(0)                         // 设置背景透明度
renderer.setScissor(x, y, width, height)          // 设置裁剪区域
renderer.setViewport(x, y, width, height)         // 设置视口

// 阴影配置
renderer.shadowMap.enabled = true                 // 开启阴影
renderer.shadowMap.type = THREE.PCFSoftShadowMap // 阴影类型

// 色彩管理
renderer.outputColorSpace = THREE.SRGBColorSpace  // 输出色彩空间
renderer.toneMapping = THREE.ACESFilmicToneMapping // 色调映射
renderer.toneMappingExposure = 1.0                // 曝光度

document.body.appendChild(renderer.domElement)

const geometry = new THREE.BoxGeometry(1, 1, 1)
const material = new THREE.MeshStandardMaterial({ color: 0x00ff00 })
const mesh = new THREE.Mesh(geometry, material)
scene.add(mesh)

const light = new THREE.DirectionalLight(0xffffff, 1)
light.position.set(5, 5, 5)
scene.add(light)

初始化阶段：
1. 创建场景
2. 创建相机
3. 创建渲染器
4. 创建几何体和材质
5. 创建网格并添加到场景
6. 创建光源

渲染循环：
1. 更新场景中的对象（位置、旋转等）
2. 渲染器调用 render() 方法
3. 将 3D 场景投影到 2D 画布
4. 显示在屏幕上

// 创建不同几何体示例
const box = new THREE.BoxGeometry(1, 1, 1)
const sphere = new THREE.SphereGeometry(0.5, 32, 32)
const cylinder = new THREE.CylinderGeometry(0.5, 0.5, 2, 32)

// 材质创建示例
const basicMaterial = new THREE.MeshBasicMaterial({ color: 0x00ff00 })
const standardMaterial = new THREE.MeshStandardMaterial({
  color: 0x00ff00,
  metalness: 0.5,    // 金属度 (0-1)
  roughness: 0.5     // 粗糙度 (0-1)
})

// 光源创建示例
const ambientLight = new THREE.AmbientLight(0x404040, 0.5)
const directionalLight = new THREE.DirectionalLight(0xffffff, 1)
directionalLight.position.set(5, 5, 5)
directionalLight.castShadow = true // 开启阴影

// 加载模型示例
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader'

const loader = new GLTFLoader()
loader.load(
  'model.glb',
  (gltf) => {
    scene.add(gltf.scene)
  },
  (progress) => {
    console.log('Loading:', (progress.loaded / progress.total * 100) + '%')
  },
  (error) => {
    console.error('Error:', error)
  }
)

// OrbitControls 使用示例
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls'

const controls = new OrbitControls(camera, renderer.domElement)
controls.enableDamping = true      // 开启阻尼效果
controls.dampingFactor = 0.05      // 阻尼系数
controls.minDistance = 1           // 最小缩放距离
controls.maxDistance = 100         // 最大缩放距离
controls.maxPolarAngle = Math.PI / 2  // 限制垂直旋转角度

npm install three

// 方式一：全局导入
import * as THREE from 'three'

const scene = new THREE.Scene()
const camera = new THREE.PerspectiveCamera(75, width / height)
const renderer = new THREE.WebGLRenderer()

// 方式二：按需导入（推荐）
import { Scene, PerspectiveCamera, WebGLRenderer } from 'three'

const scene = new Scene()
const camera = new PerspectiveCamera(75, width / height)
const renderer = new WebGLRenderer()

// 导入 OrbitControls 控制器
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls'

// 导入 GLTFLoader 加载器
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader'

// 导入后处理效果
import { EffectComposer } from 'three/examples/jsm/postprocessing/EffectComposer'

import * as THREE from 'three'

const scene: THREE.Scene = new THREE.Scene()
const camera: THREE.PerspectiveCamera = new THREE.PerspectiveCamera(
  75,
  width / height
)

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>Three.js CDN</title>
  <style>
    body { margin: 0; }
    canvas { display: block; }
  </style>
</head>
<body>
  <script type="module">
    import * as THREE from 'https://cdn.jsdelivr.net/npm/three@0.186.0/build/three.module.js'

    const scene = new THREE.Scene()
    const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight)
    const renderer = new THREE.WebGLRenderer()

    renderer.setSize(window.innerWidth, window.innerHeight)
    document.body.appendChild(renderer.domElement)

    // ...其他代码
  </script>
</body>
</html>

<!-- 指定版本号 -->
<script type="module">
  import * as THREE from 'https://cdn.jsdelivr.net/npm/three@0.186.0/build/three.module.js'
</script>

<!-- 或者使用 unpkg -->
<script type="module">
  import * as THREE from 'https://unpkg.com/three@0.186.0/build/three.module.js'
</script>

<script type="importmap">
{
  "imports": {
    "three": "https://cdn.jsdelivr.net/npm/three@0.186.0/build/three.module.js",
    "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.186.0/examples/jsm/"
  }
}
</script>

<script type="module">
  import * as THREE from 'three'
  import { OrbitControls } from 'three/addons/controls/OrbitControls.js'
  import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js'

  const controls = new OrbitControls(camera, renderer.domElement)
  const loader = new GLTFLoader()
</script>

<script type="module">
  import * as THREE from './path/to/three.module.js'
</script>

# 使用最新稳定版
npm install three

# 使用特定版本
npm install three@0.186.0

# 使用最新开发版
npm install three@latest

# 锁定版本号
npm install three@0.186.0

# 或在 package.json 中锁定
{
  "dependencies": {
    "three": "0.186.0"
  }
}

// 检测 WebGL 支持
function isWebGLAvailable() {
  try {
    const canvas = document.createElement('canvas')
    return !!(
      window.WebGLRenderingContext &&
      (canvas.getContext('webgl') || canvas.getContext('experimental-webgl'))
    )
  } catch (e) {
    return false
  }
}

if (!isWebGLAvailable()) {
  alert('您的浏览器不支持 WebGL，请升级浏览器')
}

{
  "devDependencies": {
    "vite": "^6.0.0", // 构建工具
    "typescript": "^5.0.0", // TypeScript 支持
    "@types/three": "^0.186.0" // Three.js 类型定义
  }
}

{
  "dependencies": {
    // 物理引擎
    "cannon-es": "^0.20.0",
    "ammo.js": "^0.0.10",
    
    // 动画库
    "gsap": "^3.12.0",
    
    // 工具库
    "lodash": "^4.17.21"
  }
}

// ❌ 不推荐：全局导入
import * as THREE from 'three'

// ✅ 推荐：按需导入
import { Scene, PerspectiveCamera, WebGLRenderer } from 'three'

{
  "dependencies": {
    "three": "0.186.0" // 锁定具体版本
  }
}

// vite.config.js
export default {
  optimizeDeps: {
    include: ['three']
  }
}

// ✅ 推荐：按需导入插件
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls'

// ❌ 不推荐：全量导入
import 'three/examples/js/controls/OrbitControls'

// 释放几何体
geometry.dispose()

// 释放材质
material.dispose()

// 释放纹理
texture.dispose()

// 释放渲染器
renderer.dispose()

// 从场景移除对象
scene.remove(mesh)

// 限制像素比，避免高清屏性能问题
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2))

// 使用 requestAnimationFrame 控制渲染循环
function animate() {
  requestAnimationFrame(animate)
  renderer.render(scene, camera)
}

// 合并几何体减少 draw calls
const mergedGeometry = BufferGeometryUtils.mergeGeometries(geometries)

// 使用 InstancedMesh 渲染大量相同对象
const instancedMesh = new THREE.InstancedMesh(geometry, material, count)

// 按需渲染（非动画场景）
let needsUpdate = true
function render() {
  if (needsUpdate) {
    renderer.render(scene, camera)
    needsUpdate = false
  }
}

const mesh = new THREE.Mesh(geometry, material)

// 常用属性
mesh.position.set(0, 0, 0)      // 位置
mesh.rotation.set(0, 0, 0)      // 旋转
mesh.scale.set(1, 1, 1)         // 缩放
mesh.visible = true             // 可见性
mesh.castShadow = true          // 投射阴影
mesh.receiveShadow = true       // 接收阴影

const texture = new THREE.TextureLoader().load('texture.jpg')

// 常用属性
texture.wrapS = THREE.RepeatWrapping    // 水平重复
texture.wrapT = THREE.RepeatWrapping    // 垂直重复
texture.repeat.set(2, 2)                 // 重复次数
texture.offset.set(0.5, 0.5)             // 偏移
texture.rotation = Math.PI / 4           // 旋转
texture.center.set(0.5, 0.5)             // 旋转中心
texture.colorSpace = THREE.SRGBColorSpace  // 颜色空间（r152+，旧版 texture.encoding/sRGBEncoding 已移除）

// 纹理过滤
texture.minFilter = THREE.LinearMipmapLinearFilter  // 缩小过滤
texture.magFilter = THREE.LinearFilter              // 放大过滤

// 1. 检查相机位置
console.log(camera.position)

// 2. 确保对象在视锥体内
const box = new THREE.Box3().setFromObject(mesh)
console.log(box) // 查看包围盒

// 3. 检查材质是否需要光照
// MeshStandardMaterial 和 MeshPhongMaterial 需要光源
const material = new THREE.MeshBasicMaterial({ color: 0x00ff00 }) // 不受光照影响

// 4. 确保调用了 render()
renderer.render(scene, camera)

// 5. 检查渲染器尺寸
console.log(renderer.getSize(new THREE.Vector2()))

// 1. 减少几何体面数
const geometry = new THREE.SphereGeometry(1, 16, 16) // 较少分段

// 2. 合并几何体
import * as BufferGeometryUtils from 'three/examples/jsm/utils/BufferGeometryUtils.js'
const mergedGeometry = BufferGeometryUtils.mergeGeometries([geo1, geo2])

// 3. 使用 InstancedMesh
const instancedMesh = new THREE.InstancedMesh(geometry, material, 1000)

// 4. 限制像素比
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2))

// 5. 关闭抗锯齿（移动端）
const renderer = new THREE.WebGLRenderer({ antialias: false })

// 6. 使用 LOD（细节层次）
const lod = new THREE.LOD()
lod.addLevel(highPolyMesh, 10)
lod.addLevel(mediumPolyMesh, 20)
lod.addLevel(lowPolyMesh, 30)

// 7. 视锥体剔除（默认开启）
// 确保对象的 frustumCulled 属性为 true
mesh.frustumCulled = true

// 监听窗口大小变化
window.addEventListener('resize', () => {
  const width = window.innerWidth
  const height = window.innerHeight
  
  // 更新相机宽高比
  camera.aspect = width / height
  camera.updateProjectionMatrix()
  
  // 更新渲染器尺寸
  renderer.setSize(width, height)
})

// 使用 ResizeObserver 监听容器大小变化（推荐）
const container = document.getElementById('container')
const resizeObserver = new ResizeObserver((entries) => {
  const { width, height } = entries[0].contentRect
  camera.aspect = width / height
  camera.updateProjectionMatrix()
  renderer.setSize(width, height)
})
resizeObserver.observe(container)

// 方式1：直接修改属性
function animate() {
  requestAnimationFrame(animate)
  mesh.rotation.y += 0.01
  renderer.render(scene, camera)
}

// 方式2：使用三角函数
const clock = new THREE.Clock()
function animate() {
  requestAnimationFrame(animate)
  const time = clock.getElapsedTime()
  mesh.position.y = Math.sin(time) * 2
  renderer.render(scene, camera)
}

// 方式3：使用 GSAP 动画库
import gsap from 'gsap'
gsap.to(mesh.position, {
  duration: 2,
  x: 5,
  y: 3,
  ease: 'power2.inOut'
})

// 方式4：使用 Three.js 动画系统
import { AnimationMixer } from 'three'
const mixer = new AnimationMixer(model)
const action = mixer.clipAction(animationClip)
action.play()

function animate() {
  requestAnimationFrame(animate)
  mixer.update(deltaTime)
  renderer.render(scene, camera)
}

import { Raycaster, Vector2 } from 'three'

const raycaster = new Raycaster()
const mouse = new Vector2()

window.addEventListener('click', (event) => {
  // 计算鼠标归一化坐标
  mouse.x = (event.clientX / window.innerWidth) * 2 - 1
  mouse.y = -(event.clientY / window.innerHeight) * 2 + 1
  
  // 设置射线
  raycaster.setFromCamera(mouse, camera)
  
  // 检测相交对象
  const intersects = raycaster.intersectObjects(scene.children)
  
  if (intersects.length > 0) {
    const selected = intersects[0].object
    console.log('选中对象:', selected)
    
    // 高亮显示
    selected.material.emissive.setHex(0xff0000)
  }
})