资源推荐
R3frecommend

R3F（react-three-fiber）正在成为前端进入 Web3D 世界最重要的技术入口。

从渲染、模型加载、后期效果、物理引擎，到 UI、XR、布局、性能与工程化，它已经不只是一个库，而是一套完整的 3D 应用框架生态。

本文想带你把 R3F 这一整套家伙什儿真正摸清楚：fiber、drei、gltfjsx、postprocessing、rapier、uikit……这些名字可能你见过，但它们到底解决什么问题、什么时候该用、该怎么选，很多人其实并不清楚。

这篇文章帮你把这 14 个核心仓库串成一条能看懂、用得上的路线，少踩坑、少走弯路。

适合想把 React 技术栈延伸到三维场景的前端工程师阅读与收藏。

@react-three/fiber

R3F 是三维开发的 React 入口。它把 Three.js 的底层渲染逻辑包装成 JSX 组件，让开发者用 React 的方式构建 3D 场景。你不再手写 scene、camera、renderer，不再管理渲染循环，而是用组件组合场景、用 useFrame 控制帧更新、用 props 管理状态。
对于前端可视化来说，这种结构非常关键：3D 不再是一个独立系统，而是 React 应用的延伸。状态管理、路由、Suspense、工程化工具，都能与 3D 协同。
R3F 不会自动优化性能。几何数量、材质复杂度、纹理管理和 DrawCall 仍然决定帧率。但它让大型三维项目更容易组织、更容易拆分、更容易维护。
如果你准备做数字孪生、数据可视化、模型查看器或沉浸式界面，它是最稳妥的起点。

用法示例

import { Canvas, useFrame } from '@react-three/fiber';
import { useRef } from 'react';
 
function Box() {
  const ref = useRef();
  useFrame(() => ref.current.rotation.y += 0.01);
  return (
    <mesh ref={ref}>
      <boxGeometry args={[1,1,1]} />
      <meshStandardMaterial color="orange" />
    </mesh>
  );
}
 
export default function App() {
  return (
    <Canvas>
      <ambientLight intensity={0.5} />
      <Box />
    </Canvas>
  );
}

@react-three/drei

Drei 是 R3F 最重要的辅助组件库。它封装了 3D 常用功能：模型加载、控制器、文字、反射面、环境光照、浮动动画、摄像机工具等。许多在 Three.js 中需要几十行才能写好的能力，这里几乎都是“一行组件”就能完成。

它的核心价值是让你少写 70% 的基础代码，让复杂场景更快成型。对于可视化开发者，这意味着可以把精力放在数据、交互、结构，而不是重复造轮子。

但 Drei 封装很深，性能敏感项目需要理解它底层做了什么。比如 Environment HDR 资源偏大、Text 内存占用高、某些 Controls 会在低端设备上带来额外开销。

适合绝大多数 3D Web 应用，尤其是希望快速构建 Demo、可视化界面、产品级场景的团队。

用法示例

import { Canvas } from '@react-three/fiber';
import { OrbitControls, Text, Environment } from '@react-three/drei';
 
function Scene() {
  return (
    <>
      <Text fontSize={0.5} position={[0,1.5,0]}>Hello 3D</Text>
      <mesh>
        <sphereGeometry args={[1,32,32]} />
        <meshStandardMaterial color="hotpink" />
      </mesh>
      <OrbitControls />
      <Environment preset="sunset" />
    </>
  );
}
 
export default function App() {
  return <Canvas><Scene /></Canvas>;
}

@react-three/gltfjsx

gltfjsx 是将 GLTF/GLB 模型转成 JSX 组件的工具。

模型里的几何、材质、动画、层级结构都会转成 React 组件结构，让你能像写普通 JSX 一样操控模型。

它的价值在于让模型“有结构”。不再是通过 loader 拿到一坨 scene，而是能精确控制每个部件。可视化项目里常见的“绑定交互”“改变材质”“控制动画”都更可控。
对于团队协作，gltfjsx 还能自动生成 types，帮助开发者理解模型节点；当设计师频繁更新模型时，也能快速重新生成组件结构。

缺点是模型更新需要重新转换一次；复杂模型生成代码较长，但仍比手写清晰许多。适用于涉及大量 GLTF 模型的前端可视化项目。

用法示例

npx gltfjsx model.glb
import Model from './Model';
 
export default function Scene() {
  return <Model scale={1.5} />;
}

@react-three/postprocessing

后期处理（Bloom、DOF、SSR、色调映射）是 WebGL 视觉提升的重要环节。这个库将复杂的 post-processing 管线封装成易用组件，使开发者能用 JSX 组合电影级特效。
它的优势是：效果强、配置简单、组合灵活。在可视化项目中，常用于制造高光、景深、反射、水面、暗角、轮廓增强等效果。
但后期处理非常吃性能。移动端和低端设备可能无法承受高采样的效果链。必须谨慎使用，不建议“堆特效”。
适合展览级效果、产品展示、品牌视觉项目，以及对 GPU 性能要求较高的可视化场景。

用法示例

import { EffectComposer, Bloom } from '@react-three/postprocessing';
 
<Canvas>
  <EffectComposer>
    <Bloom intensity={1.2} luminanceThreshold={0.6} />
  </EffectComposer>
</Canvas>

@react-three/uikit

uikit 让 UI 直接以 WebGL 渲染，而不是通过 DOM 覆盖。
它的核心理念是“3D 场景内的 UI，与模型同一空间对齐”，常用于全三维界面、XR 控制面板、虚拟仪表盘等。
相比 DOM，它的优势是沉浸感强、风格高度统一、视觉一致性好。对于做数字孪生、驾驶舱、虚拟控制室的团队尤其友好。
但它仍在发展中，布局系统较复杂，文本渲染、交互精度也比不上 DOM。建议用于需要 3D 融合 UI 的场景，而非传统信息 UI。

用法示例

import { Container, Text } from '@react-three/uikit';
 
<Container width={200} height={80} backgroundColor="black">
  <Text color="white">3D UI Panel</Text>
</Container>

@react-three/flex

flex 把 Yoga（React Native 用的 Flexbox 引擎）带到 3D 世界。
它允许你用 Flex 布局排列 3D 面板和 UI，让复杂布局不再依赖手算坐标。
适用于“3D 仪表盘布局”“3D 卡片墙”“信息面板”等场景。
优点是布局自然、响应式强；缺点是尺寸单位是 3D 空间坐标，需要适应空间尺度概念。
如果你的场景包含大量平面 UI，本库会极大提高效率。

用法示例

import { Flex, Box } from '@react-three/flex';
 
<Flex justify="center" align="center">
  <Box margin={0.1}>
    <mesh><boxGeometry /><meshBasicMaterial color="red" /></mesh>
  </Box>
  <Box margin={0.1}>
    <mesh><boxGeometry /><meshBasicMaterial color="blue" /></mesh>
  </Box>
</Flex>

@react-three/xr

xr 是 R3F 的 WebXR 入口，提供 VR/AR 设备支持、手柄事件、绑定姿态、空间坐标同步等能力。
它简化 WebXR 的底层复杂性，让开发者直接在 R3F 中构建 VR 交互界面，如操控器、手势、射线拾取、空间 UI。
适合需要构建 VR 展示、沉浸式体验、数字孪生漫游的团队。
缺点是高度依赖硬件与浏览器支持，不同设备行为不完全一致，需要测试矩阵。

用法示例

import { VRCanvas, Controllers } from '@react-three/xr';
 
<VRCanvas>
  <Controllers />
  <mesh>
    <boxGeometry />
    <meshStandardMaterial color="orange" />
  </mesh>
</VRCanvas>

@react-three/csg

csg 提供布尔运算（并集、交集、差集）。
用于切割模型、构造几何、生成动态形状，适合 CAD、工程可视化、科学计算可视化场景。
它把复杂的布尔逻辑变成 JSX 组合，让几何构造更直观。
但布尔运算开销较大，模型越复杂效果越慢。适合中等复杂度场景。

用法示例

import { CSG } from '@react-three/csg';
 
<CSG>
  <mesh><boxGeometry /></mesh>
  <mesh subtraction><sphereGeometry /></mesh>
</CSG>

@react-three/rapier

rapier 是速度极快的三维物理引擎（基于 Rust + WASM）。
适用于高性能模拟、交互丰富的场景，例如可视化中的物体运动、粒子碰撞、设备模拟、游戏化数据展示。
优势是性能强、稳定性高、API 清晰；缺点是 WASM 初始化略重，且需要适应新的 API 风格。
对于需要“真实物理反馈”的可视化场景，它优于 cannon。

用法示例

import { Physics, RigidBody } from '@react-three/rapier';
 
<Physics>
  <RigidBody>
    <mesh><boxGeometry /><meshStandardMaterial /></mesh>
  </RigidBody>
</Physics>

@react-three/cannon

cannon 是 Cannon.js 的 R3F 绑定，使用简单、社区成熟。
适合对性能要求不特别极限，但需要稳定物理模拟的可视化项目。
优势在于易用、调试成本低；缺点是性能不如 rapier，且部分算法较旧。
适合已有 cannon 项目迁移，或对性能要求一般的 3D 可视化。

用法示例

import { Physics, useBox } from '@react-three/cannon';
 
function Cube() {
  const [ref] = useBox(() => ({ mass: 1 }));
  return <mesh ref={ref}><boxGeometry /><meshStandardMaterial /></mesh>;
}
 
<Physics><Cube /></Physics>

@react-three/p2

p2 是二维物理引擎 P2 的 R3F 封装。
适合 UI 动效、数据节点碰撞、气泡布局、2D/3D 混合界面。
优势是轻量、稳定；缺点是仅适用于 2D 物理，不处理真实 3D 碰撞。
适合构建 2D 力导可视化、图节点布局、可视化动画。

用法示例

import { useP2Body } from '@react-three/p2';
 
const body = useP2Body({ mass: 1, position: [0,0] });

@react-three/a11y

a11y 让 3D 场景可以被屏幕阅读器、键盘导航识别。
它通过把 3D 中的可交互元素映射到隐藏 DOM，使无障碍需求在三维项目中也能实现。
适用于政企项目、无障碍合规要求高的企业级可视化。
缺点是需要额外组织结构，让“3D 物体→DOM 描述”保持一致性。

用法示例

import { A11y, A11yAnnouncer } from '@react-three/a11y';
 
<A11y role="button" description="Open Panel">
  <mesh><boxGeometry /><meshStandardMaterial /></mesh>
</A11y>
<A11yAnnouncer />

@react-three/test-renderer

test-renderer 允许在 Node 环境中测试 R3F 组件，不需要真实 WebGL。
适合大型可视化项目的 CI 与自动化测试。
优点是能做快照测试、结构验证、props 检查；缺点是无法测试真实性能与渲染结果。
适用于工程化程度高、多人协作的三维前端项目。

用法示例

import ReactThreeTestRenderer from '@react-three/test-renderer'
 
const renderer = await ReactThreeTestRenderer.create(
  <mesh>
    <boxGeometry args={[2, 2]} />
    <meshStandardMaterial
      args={[
        {
          color: 0x0000ff,
        },
      ]}
    />
  </mesh>,
)
 
// assertions using the TestInstance & Scene Graph
console.log(renderer.toGraph())```
 
---
 
# **@react-three/gpu-pathtracer**
![](./image/r3frecommend-10.png)
gpu-pathtracer 提供实时光线追踪渲染，让网页也能获得接近离线渲染的效果。  
适合建筑可视化、高端产品渲染、科学计算、真实光照模拟等场景。  
优势是图形质量极高；缺点是性能要求非常高，对硬件要求苛刻，不适合普通业务场景。  
在前端可视化中，适合做高端展示页、实验室类项目、品牌级视觉内容。
 
**用法示例**
 
```jsx
import { PathTracer } from '@react-three/gpu-pathtracer';
 
<PathTracer samples={1} />

最后

如果你把本文的 14 个仓库读完，你会发现 R3F 并不是一个“写 3D 的 React 语法糖”，而是一个完整的前端三维生态。

用 fiber 抽象渲染；
用 drei 快速构建场景；
用 gltfjsx 管模型；
用 postprocessing 做视觉增强；
用 rapier 加物理；
用 uikit/flex 构建 3D UI；
用 xr 进 VR/AR；
用 test-renderer 做工程化；
用 pathtracer 做顶级画质……

前端第一次拥有了“用一套方式构建复杂三维应用”的能力。
无论你做的是数据可视化、数字孪生、建模查看器还是沉浸式交互，R3F 生态都能为你提供合适的拼装方式。

RReact Three Fiber