React-Three-Fiber 完全入门指南零基础用 React 写出交互式 3D 场景【免费下载链接】react-three-fiber A React renderer for Three.js项目地址: https://gitcode.com/GitHub_Trending/re/react-three-fiberReact-Three-FiberR3F是 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/fiber8配 React 18react-three/fiber9配 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 colorhotpink / /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 colororange / /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 colorhotpink / /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 frameloopdemand✅ 注意像相机控制器这类直接改对象属性的操作React 感知不到。需要用useThree拿到的invalidate()手动请求一帧drei 的控制器已经帮你做了。invalidate()只是打个标记多次调用也只渲染一次。新手最容易踩的一个坑在 useFrame 里 setState。做法效果❌useFrame(() setX(x 0.1))每帧触发 React 重渲染白白走调度器帧率明显下降✅useFrame(() (ref.current.rotation.x delta))直接改对象属性零重渲染且用delta保证不同刷新率下速度一致记住两条快更新走 ref 直接赋值别走状态速度计算乘以delta否则 144Hz 的显示器上你的动画会快一倍。更多实战技巧可以看 性能坑点文档。生态与扩展react-three/drei预制组件集合OrbitControls、Text、Points 等本身就是一个子生态react-three/gltfjsx把 GLTF 模型转成 JSX 组件方便复用场景图react-three/postprocessing后期处理效果泛光、景深等react-three/cannon / react-three/rapierCannon 和 Rapier 物理引擎集成react-three/xrVR/AR 控制器与事件支持react-three/test-renderer在 Node 环境下对 3D 场景做单元测试leva几行代码给场景加 GUI 调试面板zustand / jotai / valtio官方推荐的三种状态管理方案react-spring弹簧物理动画库自带帧循环动画在 React 之外执行完整 API 见 Canvas 文档 和 Hooks 文档。快速问答装不上/报错先检查什么大概率是 React 版本没配对fiber 8 配 React 18fiber 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
