React Three Fiber 从零入门：构建属于你的 3D 几何世界

想在网页中创建 3D 世界，但又不想从 Three.js 的底层开始摸索？
那么 React Three Fiber（简称 R3F） 是最值得尝试的选择。
它让 React 组件直接控制 Three.js 场景，让“搭 3D 世界”像写前端界面一样自然。

这篇文章将带你从零开始，用 R3F 构建一个包含多种几何体的 3D 世界。

一、创建 React + Vite 项目

首先初始化一个 React 开发环境：

npm create vite@latest r3f -- --template react
cd r3f
npm install

二、安装 3D 依赖

R3F 并不是单独存在的框架，它建立在 Three.js 基础上。
我们只需安装三个核心包：

包名	作用
`three`	3D 引擎本体
`@react-three/fiber`	React 版 Three.js 渲染器
`@react-three/drei`	R3F 辅助组件库（包含控制器、灯光等）

npm i three @react-three/fiber @react-three/drei

三、搭建基础结构

在 src/App.jsx 中引入我们后续的主场景组件：

import './App.css'
import ObjectC from './components/ObjectC'
 
function App() {
  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <ObjectC />
    </div>
  )
}
 
export default App

使用全屏容器是为了让 3D Canvas 占满整个窗口。

四、理解核心概念：Canvas、Mesh、Geometry、Material

React Three Fiber 的核心哲学是：
“把 Three.js 世界映射为 React 组件树。”

你可以把 <Canvas> 理解为三维世界的画布，
而 <mesh>、<geometry>、<material> 则是世界中的物体、形状与外观。

Canvas（3D 场景）
 └── Mesh（物体）
      ├── Geometry（形状）
      └── Material（材质）

Geometry（几何体）：定义物体的形状；
Material（材质）：定义物体表面的颜色和光照表现；
Mesh（网格体）：几何体 + 材质的组合，是可被渲染的对象。

你可以把它理解成：

Geometry 是骨架，Material 是皮肤，Mesh 是整个人。

五、创建第一个立方体

import { Canvas } from '@react-three/fiber'
import { OrbitControls } from '@react-three/drei'
 
export default function Minimal() {
  return (
    <Canvas camera={{ position: [0, 0, 5] }}>
      {/* 光源：方向光 */}
      <directionalLight position={[5, 5, 5]} />
 
      {/* Mesh：立方体 */}
      <mesh>
        <boxGeometry args={[1, 1, 1]} />
        <meshLambertMaterial color="#4ade80" />
      </mesh>
 
      {/* 鼠标交互控制器 */}
      <OrbitControls />
    </Canvas>
  )
}

运行后，页面中出现一个绿色立方体，鼠标拖动即可旋转查看。

1. `<Canvas>`：3D 世界的入口

相当于 Three.js 的 Scene + Renderer
负责渲染循环与相机管理
camera={{ position: [0, 0, 5] }} 表示相机离原点 5 个单位远

如果相机位置与物体重合 [0, 0, 0]，你将看不到任何东西。

2. `<mesh>`：三维物体容器

mesh 是场景中最基本的单位，由几何体和材质组成。

属性	含义	示例
`position`	位置（x, y, z）	`[0, 0, 0]`
`rotation`	旋转角度（弧度）	`[0, Math.PI/4, 0]`
`scale`	缩放比例	`[1, 1, 1]`

3. `<boxGeometry>`：立方体形状

<boxGeometry args={[1, 1, 1]} />

等价于：

new THREE.BoxGeometry(1, 1, 1)

4. `<meshLambertMaterial>`：漫反射材质

<meshLambertMaterial color="#4ade80" />

材质类型	是否受光照影响	特点
`meshBasicMaterial`	否	始终明亮，适合调试
`meshLambertMaterial`	是	漫反射，柔和自然
`meshStandardMaterial`	是	物理渲染，更真实

没有灯光时，Lambert 材质会变成纯黑。

5. `<directionalLight>`：方向光

<directionalLight position={[5, 5, 5]} />

模拟太阳光，从指定方向发出平行光线。

六、构建完整 3D 几何体展示场景

接下来我们制作一个“几何体展示页”，
展示多种常见基础形状。

创建 src/components/ObjectC.jsx：

import { Canvas } from "@react-three/fiber";
import * as THREE from "three";
import { OrbitControls } from "@react-three/drei";
 
const ObjectC = () => {
  return (
    <Canvas camera={{ position: [0, 0, 20] }}>
      <directionalLight position={[0, 19, 10]} />
      <OrbitControls />
 
      {/* 第一排：立方体、球体、圆环体、圆锥体 */}
      <mesh position={[-10, 4, 0]}>
        <boxGeometry args={[1, 1, 1]} />
        <meshLambertMaterial color={0x00ff00} />
      </mesh>
      <mesh position={[-6, 4, 0]}>
        <sphereGeometry args={[1, 32, 32]} />
        <meshLambertMaterial color={0x00ff00} />
      </mesh>
      <mesh position={[-2, 4, 0]}>
        <torusGeometry args={[1, 0.5, 16, 100]} />
        <meshLambertMaterial color={0x00ff00} />
      </mesh>
      <mesh position={[2, 4, 0]}>
        <coneGeometry args={[1, 2, 32]} />
        <meshLambertMaterial color={0x00ff00} />
      </mesh>
 
      {/* 第二排：平面、圆环、圆形、圆柱体 */}
      <mesh position={[-10, 0, 0]} rotation={[0, 1, 0]}>
        <planeGeometry args={[3, 3]} />
        <meshLambertMaterial color={0x00ff00} side={THREE.DoubleSide} />
      </mesh>
      <mesh position={[-6, 0, 0]}>
        <ringGeometry args={[0.5, 1.5, 32]} />
        <meshLambertMaterial color={0xff9900} side={THREE.DoubleSide} />
      </mesh>
      <mesh position={[-2, 0, 0]}>
        <circleGeometry args={[1.5, 32]} />
        <meshLambertMaterial color={0x0099ff} side={THREE.DoubleSide} />
      </mesh>
      <mesh position={[2, 0, 0]}>
        <cylinderGeometry args={[0.8, 0.8, 2, 32]} />
        <meshLambertMaterial color={0xff00ff} />
      </mesh>
 
      {/* 第三排：多面体系列 */}
      <mesh position={[-10, -4, 0]}>
        <icosahedronGeometry args={[1, 0]} />
        <meshLambertMaterial color={0x00ffff} />
      </mesh>
      <mesh position={[-6, -4, 0]}>
        <octahedronGeometry args={[1, 0]} />
        <meshLambertMaterial color={0xffff00} />
      </mesh>
      <mesh position={[-2, -4, 0]}>
        <tetrahedronGeometry args={[1, 0]} />
        <meshLambertMaterial color={0xff0000} />
      </mesh>
      <mesh position={[2, -4, 0]}>
        <capsuleGeometry args={[0.7, 1.5, 4, 8]} />
        <meshLambertMaterial color={0x888888} />
      </mesh>
    </Canvas>
  );
};
 
export default ObjectC;

运行后，你会看到一个整齐排列的“几何体展览墙”。

常见几何体参数对照

几何体	JSX 写法	参数说明
Box	`<boxGeometry args={[w,h,d]} />`	宽、高、深
Sphere	`<sphereGeometry args={[r,wSeg,hSeg]} />`	半径、水平分段、垂直分段
Torus	`<torusGeometry args={[r,tube,radialSeg,tubularSeg]} />`	主半径、管半径、细分
Cone	`<coneGeometry args={[r,h,seg]} />`	底面半径、高度、分段数
Plane	`<planeGeometry args={[w,h]} />`	宽、高
Ring	`<ringGeometry args={[innerR,outerR,seg]} />`	内外半径、分段数
Circle	`<circleGeometry args={[r,seg]} />`	半径、分段数
Cylinder	`<cylinderGeometry args={[rTop,rBottom,h,seg]} />`	上下半径、高度、分段
Icosahedron	`<icosahedronGeometry args={[r,detail]} />`	半径、细节层级
Capsule	`<capsuleGeometry args={[r,length,capSeg,radialSeg]} />`	半径、长度、分段

八、总结与下一步方向

React Three Fiber 的基础结构：

✅ Canvas 负责创建 3D 世界；
✅ mesh 组合几何体与材质；
✅ OrbitControls 提供交互；
✅ directionalLight 提供光照；
✅ 不同几何体通过 args 参数定义形状。

play smoke