Skip to main content
← Back

React Three Fiber 入门：用声明式写法构建 3D 场景

2026-04-01#react#threejs#3d

什么是 React Three Fiber

React Three Fiber（简称 R3F）是 Three.js 的 React 渲染器。简单来说，它让你可以用 JSX 的方式描述 3D 场景，就像写 HTML 元素一样自然。

import { Canvas } from '@react-three/fiber'
 
export default function Scene() {
  return (
    <Canvas>
      <ambientLight intensity={0.5} />
      <mesh>
        <boxGeometry args={[1, 1, 1]} />
        <meshStandardMaterial color="orange" />
      </mesh>
    </Canvas>
  )
}

上面这段代码会渲染一个橙色的立方体。

核心概念

Canvas

Canvas 是 R3F 的根组件，内部创建了一个 Three.js 的 WebGLRenderer、Scene 和 Camera。它自动处理画布的尺寸和像素比，你不需要手动管理这些。

mesh

Three.js 里的 Mesh = Geometry + Material，在 R3F 里写成：

<mesh>
  <boxGeometry args={[1, 1, 1]} />
  <meshStandardMaterial color="#ff6030" />
</mesh>

args 对应构造函数参数，等价于 new THREE.BoxGeometry(1, 1, 1)。

useFrame

R3F 提供的 hook，在每帧执行，用于动画：

import { useFrame, useRef } from '@react-three/fiber'
import { Mesh } from 'three'
 
function RotatingBox() {
  const ref = useRef<Mesh>(null)
 
  useFrame((state, delta) => {
    if (ref.current) {
      ref.current.rotation.y += delta
    }
  })
 
  return (
    <mesh ref={ref}>
      <boxGeometry />
      <meshStandardMaterial color="hotpink" />
    </mesh>
  )
}

为什么选 R3F

特性原生 Three.jsReact Three Fiber
代码风格命令式声明式
React 生态❌✅
状态管理手动React state / Zustand
性能✅✅ 基本一致
学习曲线较陡React 背景更友好

如果你已经熟悉 React，R3F 的学习曲线会平缓很多。

下一步