本页目录

React 的 Three.js 渲染器(react-three-fiber)

react-three-fiber · pmndrs/react-three-fiber

react-three-fiber 是 pmndrs 组织下的开源项目,仓库描述为“A React renderer for Three.js”,即面向 Three.js 的 React 渲染器。项目主要使用 TypeScript,仓库话题涵盖 3D、动画、fiber、React、渲染器与 Three.js。适合关注 React 与...

其他 Three.js JavaScript 游戏状态管理 渲染技术 中级
★ Stars 33,775 Forks 2,112 License MIT 更新 2026-11-16

国内开发环境适配

Windows
未知
Linux
未知
macOS
未知
引擎 / 框架:Three.js 暂无中文教程标记 未标记站长实测
依赖通过 npm 安装(three、@types/three、@react-three/fiber),国内可能需要配置 npm 镜像源;文档站点与 CodeSandbox 演示的访问速度待核验。

中文项目介绍

react-three-fiber(包名 @react-three/fiber,简称 R3F)是 pmndrs 社区维护的一个 React 渲染器,作用对象是 Three.js。它的定位与 react-dom、react-native 属于同一层级:把 Three.js 的场景描述交给 React 的组件模型来组织。

README 用一句话概括:用可复用、自包含的组件以声明式方式构建场景,这些组件能响应状态、天然可交互,并且可以参与 React 生态。安装方式为:

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

需要特别注意的是版本配对规则(README 中以醒目的警告标出):three-fiber 是 React 渲染器,必须与 React 的主版本配套使用——@react-three/fiber@8 对应 react@18,@react-three/fiber@9 对应 react@19。

核心功能

有没有限制?

没有。Three.js 里能跑的东西在这里都能跑,没有例外。

比原生 Three.js 慢吗?

不会。没有额外开销,组件在 React 之外渲染;由于 React 的调度能力,在大规模场景下表现更好。

能跟上 Three.js 的功能更新吗?

能。它只是把 Three.js 表达为 JSX,`<mesh />` 会动态转成 `new THREE.Mesh()`。Three.js 版本新增、删除或修改特性时,无需等待本库跟进即可使用。

技术架构分析

技术要点

  • 渲染器思路:R3F 并不重新实现图形能力,而是把 JSX 元素映射为 Three.js 的对象实例,因此对 Three.js 的对象、几何体、材质、灯光体系保持直接对应。
  • 渲染循环接入:useFrame((state, delta) => ...) 将组件挂到每帧回调中,适合做旋转、动画等逐帧更新。
  • 事件系统:onClick、onPointerOver、onPointerOut 等指针事件可直接写在 mesh 上,配合 useState 即可实现悬停变色、点击缩放等交互。
  • 状态与生态联动:组件可参与 React 生态,README 的生态清单中列举了多种状态管理方案(zustand、jotai、valtio)与动画方案(react-spring、framer-motion-3d)。
  • 跨端:除浏览器端外,README 展示了 React Native 示例;若使用 useLoader 或 Drei 的 useGLTF、useTexture 等抽象,可能需要在 metro.config.js 中配置 sourceExts 与 assetExts(如 glb、png、jpg)。示例基于 react 18 与 expo-cli,也可以用模板或 react-native CLI 创建裸项目。

补充说明

它长什么样

README 给出的示例是一个带自身状态、响应用户输入、并接入渲染循环的可复用组件 Box:

  • 通过 useRef 拿到真实的 THREE.Mesh 对象引用;
  • 用 useState 保存 hovered / clicked 两种交互状态;
  • 通过 useFrame 订阅渲染循环,每帧按 delta 递增旋转角度;
  • 返回的 <mesh>、<boxGeometry>、<meshStandardMaterial> 都是 Three.js 元素在 JSX 中的表达,并直接绑定 onClick、onPointerOver、onPointerOut 等事件。

挂载时用 createRoot(document.getElementById('root')) 渲染 <Canvas>,内部再放 <ambientLight>、<spotLight>、<pointLight> 以及两个 Box。README 同时提供了 TypeScript 版本(组件参数类型写作 ThreeElements['mesh'],useRef<THREE.Mesh>(null!))和 React Native 版本(从 @react-three/fiber/native 导入 Canvas 与 useFrame)。

文档、教程与示例

官方文档站点为 docs.pmnd.rs,README 指向其中包含教程与示例的板块。源码仓库内也提供了可在线运行的演示(CodeSandbox 链接,含 JS 与 TS 两个版本)。

README 推荐的学习材料包括:

  • Three.js 官方文档与 examples;
  • Discover Three.js,尤其是其中的 Tips and Tricks 章节;
  • Bruno Simon 的 Three.js Journey 课程,README 称其「可说是最好的学习资源」,并已包含完整的 R3F 章节。

上手前的准备

README 明确提醒:在动手之前,应当同时熟悉 React 与 Three.js。若对 React 不确定,先读 React 官方文档,特别是 Hooks 部分;对 Three.js,建议按以下顺序推进:

  1. 先建立对 Three.js 的基本认识(场景、相机、网格、几何体、材质),并保持官方手册常开;
  2. 理解场景概念后,fork 上面的演示动手改;
  3. 对照 Three.js 文档查阅你在 JSX 中看到的元素(mesh、ambientLight 等)——所有 Three.js 导出在 three-fiber 中都是原生可用的;
  4. 尝试修改数值,并翻阅 API 文档理解各个设置与 Hook 的作用。

生态一览

README 强调 three-fiber 周边有相当丰富的库、辅助工具与抽象层,并逐一列出,例如:

  • @react-three/drei:实用辅助集合,README 称其「本身就是一个生态」;
  • @react-three/gltfjsx:把 GLTF 转成 JSX 组件;
  • @react-three/postprocessing:后处理特效;
  • @react-three/uikit:为 three-fiber 提供 WebGL 渲染的 UI 组件;
  • @react-three/test-renderer:用于 node 环境下的单元测试;
  • @react-three/offscreen:离屏 / worker 画布;
  • @react-three/flex:flexbox 布局;
  • @react-three/xr:VR/AR 控制器与事件;
  • @react-three/csg:构造实体几何;
  • @react-three/rapier、@react-three/cannon、@react-three/p2:分别基于 Rapier、Cannon 的 3D 物理与基于 P2 的 2D 物理;
  • @react-three/a11y:场景可访问性;@react-three/gpu-pathtracer:路径追踪;
  • 以及 create-r3f-app next(Next.js 起始模板)、lamina(分层着色器材质)、leva(快速搭建 GUI 控件)、maath(数学辅助)、miniplex(ECS)、composer-suite、triplex(可视化编辑器)等。

这些清单可作为按需选型的索引,具体用法需查阅各子项目文档。

开源许可证与版权说明

许可证标识:MIT。源码、资源与依赖许可可能不同,请以官方仓库为准。本站仅做索引,不托管源码。

相似项目