React Three Fiber：用 React 写 3D 场景

react-three-fiber 是 Three.js 的 React 渲染器，拿到了 3 万+ Star。

react-three-fiber 把 Three.js 的 API 映射为 JSX 组件。<mesh> 对应 new THREE.Mesh()，<boxGeometry> 对应 new THREE.BoxGeometry()。所有 Three.js 的导出都能在 JSX 中直接使用。

它本身是 React 的渲染器，和 react-dom、react-native 同级。3D 场景可以参与 React 的调度系统，在大规模场景下性能优于原生 Three.js。Three.js 支持的功能在 react-three-fiber 中全部可用，没有例外。

安装一行命令：

npm install three @types/three @react-three/fiber

核心用法：

import { Canvas, useFrame } from '@react-three/fiber'
import { useRef, useState } from 'react'

function Box(props) {
  const ref = useRef()
  const [hovered, hover] = useState(false)
  const [clicked, click] = useState(false)
  useFrame((state, delta) => (ref.current.rotation.x += delta))
  return (
    <mesh
      {...props}
      ref={ref}
      scale={clicked ? 1.5 : 1}
      onClick={() => click(!clicked)}
      onPointerOver={() => hover(true)}
      onPointerOut={() => hover(false)}>
      <boxGeometry args={[1, 1, 1]} />
      <meshStandardMaterial color={hovered ? 'hotpink' : 'orange'} />
    </mesh>
  )
}

<Canvas>
  <ambientLight intensity={Math.PI / 2} />
  <Box position={[-1.2, 0, 0]} />
  <Box position={[1.2, 0, 0]} />
</Canvas>

这段代码创建了两个可交互的立方体。hover 变色、点击放大、每帧旋转，全部通过 React 状态驱动。组件可以自由组合和复用，和写普通 React 组件没有区别。

版本方面需要注意：@react-three/fiber@8 对应 React 18，@react-three/fiber@9 对应 React 19。版本必须匹配，和 react-dom 一样的规则。

它还支持 TypeScript 和 React Native。TypeScript 用户只需额外安装 @types/three，JSX 元素和 hooks 都有完整的类型定义。React Native 端通过 @react-three/fiber/native 导入，配合 Expo 使用。

生态方面，围绕 react-three-fiber 已经形成了完整的工具链：

• @react-three/drei：实用组件集合，覆盖相机控制、环境光、文字渲染等常见需求
• @react-three/postprocessing：后处理效果
• @react-three/rapier 和 @react-three/cannon：物理引擎
• @react-three/xr：VR/AR 支持
• @react-three/gltfjsx：把 GLTF 模型转为 JSX 组件
• leva：快速搭建调试面板
• zustand / jotai / valtio：状态管理，均为 pmndrs 团队出品

Vercel、Basement、Studio Freight 等设计团队都在使用它构建 3D 网页项目。从产品展示页到数据可视化，再到在线 3D 编辑器，react-three-fiber 覆盖的场景比较广。

Three.js 本身更新频繁，但 react-three-fiber 不会因此落后。它把 Three.js 的 API 用 JSX 表达，Three.js 新增或修改的功能会立即可用，不需要等库本身更新适配。

文档和示例在 docs.pmnd.rs 可以找到，建议先了解 Three.js 基础再上手。

的功能会立即可用，不需要等库本身更新适配。

文档和示例在 docs.pmnd.rs 可以找到，建议先了解 Three.js 基础再上手。