React-Three-Fiber 完全入门指南：零基础用 React 写出交互式 3D 场景

【免费下载链接】react-three-fiber🇨🇭 A React renderer for Three.js项目地址: https://gitcode.com/GitHub_Trending/re/react-three-fiber

React-Three-Fiber（R3F）是 Three.js 的React 渲染器，让你直接用 JSX 声明式地搭建 3D 场景。读完这篇，你会独立完成安装配置、渲染出第一个会转的立方体，并掌握 useFrame 动画、指针交互和模型加载这几个最常用的核心用法。

它解决什么问题

写原生 Three.js 时，你要手动new THREE.Scene()、new THREE.PerspectiveCamera()、new THREE.WebGLRenderer()，自己搭requestAnimationFrame渲染循环，再手动管理对象的生命周期。代码一多，"谁在管这个 mesh？什么时候销毁的？"就成了难题。

R3F 把这一切换成了你熟悉的 React 写法：场景是组件，属性是 props，状态用useState管，动画用useFrame订阅。一个能响应鼠标、带自带动画的 3D 对象，就是一个普通函数组件。

而且它不是 Three.js 的"阉割版"——Three.js 的所有 API 在这里都能用，<mesh />会被动态转换成new THREE.Mesh()，官方升级了什么功能你这边立即就能用。

最小体验：从安装到第一个旋转立方体

跟着敲完下面这几步，就能看到效果。Vite 开箱即用：

# 创建项目 npm create vite my-app # 选择 react 框架后，进入项目 # 安装核心依赖 cd my-app npm install three @react-three/fiber # 启动开发服务器 npm run dev

⚠️版本必须配对：R3F 和 react-dom 一样要匹配 React 主版本。@react-three/fiber@8配 React 18，@react-three/fiber@9配 React 19。装错版本会直接报错。

把入口文件改成这样，保存即渲染：

import { useRef } from 'react' import { Canvas, useFrame } from '@react-three/fiber' function Box(props) { const meshRef = useRef() useFrame((state, delta) => (meshRef.current.rotation.x += delta)) return ( <mesh {...props} ref={meshRef}> <boxGeometry args={[1, 1, 1]} /> <meshStandardMaterial color="hotpink" /> </mesh> ) } export default function App() { return ( <Canvas> <ambientLight intensity={Math.PI / 2} /> <spotLight position={[10, 10, 10]} angle={0.15} penumbra={1} decay={0} intensity={Math.PI} /> <Box position={[-1.2, 0, 0]} /> <Box position={[1.2, 0, 0]} /> </Canvas> ) }

页面上会出现两个匀速旋转的粉色立方体。这就是 R3F 的核心循环：写 JSX → 浏览器里跑起来 → 改 props 看变化。

核心能力拆解

1. 用 JSX 声明 3D 对象

概念：Three.js 导出的每个类都变成了可用的 JSX 元素，<sphereGeometry />、<pointLight />都是原生支持的。

<mesh position={[0, 1, 0]}> <sphereGeometry args={[1, 32, 32]} /> <meshStandardMaterial color="orange" /> </mesh>

它意味着什么：搭建场景和写 DOM 一样自然，嵌套关系就是场景图结构，组件可以直接复用、传 props。

2. 用 useFrame 订阅渲染循环

概念：useFrame让你的组件加入每帧执行的渲染循环，回调里能拿到场景state和上一帧的时间差delta（单位秒）。

function SpinningCube() { const meshRef = useRef() useFrame((state, delta) => { meshRef.current.rotation.x += delta meshRef.current.rotation.y += delta * 0.5 }) return ( <mesh ref={meshRef}> <boxGeometry args={[1, 1, 1]} /> <meshStandardMaterial color="hotpink" /> </mesh> ) }

它意味着什么：动画不需要setInterval，也不经过 React 重渲染，直接改对象属性，性能开销接近零。

3. 指针事件与 React 状态联动

概念：mesh 上可以直接挂onClick、onPointerOver等事件，事件对象里带着 Three.js 的射线检测数据（命中点、距离等）。

function InteractiveBox(props) { const [hovered, setHovered] = useState(false) const [clicked, setClicked] = useState(false) return ( <mesh {...props} scale={clicked ? 1.5 : 1} onClick={() => setClicked(!clicked)} onPointerOver={() => setHovered(true)} onPointerOut={() => setHovered(false)}> <boxGeometry args={[1, 1, 1]} /> <meshStandardMaterial color={hovered ? 'hotpink' : 'orange'} /> </mesh> ) }

它意味着什么：3D 场景和 React 状态完全打通，"悬停变色、点击放大"这类交互就是几行事件回调的事。

4. 用 useLoader 加载模型与纹理

概念：useLoader基于 React Suspense，传入任意 Three.js 加载器即可异步加载资源，加载完成前组件自动挂起。

import { Suspense, useState } from 'react' import { Canvas, useLoader } from '@react-three/fiber' import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js' function Model() { const { nodes } = useLoader(GLTFLoader, '/model.glb') return <primitive object={nodes.cube} /> } export default function App() { return ( <Canvas> <Suspense fallback={null}> <Model /> </Suspense> </Canvas> ) }

它意味着什么：加载资源自动按 URL 缓存，全场景共享；错误交给父级 ErrorBoundary 处理，省掉一堆手动状态管理。

5. 用 useThree 拿场景状态

概念：useThree暴露整个场景状态——渲染器gl、scene、camera、画布尺寸size、当前frameloop模式等，还支持按需选取。

function Stats() { const camera = useThree((state) => state.camera) const size = useThree((state) => state.size) return console.log(size.width, size.height, camera) }

它意味着什么：状态是响应式的，浏览器窗口一变尺寸，依赖它的组件自动更新；用选取器还能避免无关的重复渲染。

进阶与常见坑

场景里如果有大量静止物体，<Canvas>默认的always模式会每帧都渲染，白白耗电。改成按需渲染，只在变化时画帧：

<Canvas frameloop="demand">

✅ 注意：像相机控制器这类直接改对象属性的操作，React 感知不到。需要用useThree拿到的invalidate()手动请求一帧（drei 的控制器已经帮你做了）。invalidate()只是打个标记，多次调用也只渲染一次。

新手最容易踩的一个坑：在 useFrame 里 setState。

记住两条：快更新走 ref 直接赋值，别走状态；速度计算乘以delta，否则 144Hz 的显示器上你的动画会快一倍。更多实战技巧可以看 性能坑点文档。

生态与扩展

• @react-three/drei：预制组件集合（OrbitControls、Text、Points 等），本身就是一个子生态
• @react-three/gltfjsx：把 GLTF 模型转成 JSX 组件，方便复用场景图
• @react-three/postprocessing：后期处理效果（泛光、景深等）
• @react-three/cannon / @react-three/rapier：Cannon 和 Rapier 物理引擎集成
• @react-three/xr：VR/AR 控制器与事件支持
• @react-three/test-renderer：在 Node 环境下对 3D 场景做单元测试
• leva：几行代码给场景加 GUI 调试面板
• zustand / jotai / valtio：官方推荐的三种状态管理方案
• react-spring：弹簧物理动画库，自带帧循环，动画在 React 之外执行

完整 API 见 Canvas 文档 和 Hooks 文档。

快速问答

装不上/报错，先检查什么？大概率是 React 版本没配对：fiber 8 配 React 18，fiber 9 配 React 19。用npm ls react看一眼主版本。

它比原生 Three.js 慢吗？不会。官方明确说明没有额外开销，组件渲染在 React 之外进行，靠 React 的调度能力在大规模场景下反而更优。

Hook 能在 Canvas 外面用吗？不行。useFrame、useThree这些 Hook 依赖 Canvas 提供的上下文，必须写在<Canvas>内部的组件里，否则直接崩溃。

收尾

• 一条npm install three @react-three/fiber起步，JSX 写的场景即刻渲染
• useFrame管动画、事件回调管交互、useLoader管资源，三件套覆盖日常需求
• 快更新直接改 ref 属性、速度乘以delta，是最核心的性能纪律
• drei、postprocessing、物理引擎等生态包按需叠加，能力上探到 Three.js 上限

仓库里 example/ 目录还有一堆可运行的演示场景，改改参数跑起来看看效果——写 3D 最好的学习方式，就是先把立方体转起来。

【免费下载链接】react-three-fiber🇨🇭 A React renderer for Three.js项目地址: https://gitcode.com/GitHub_Trending/re/react-three-fiber