Wawa Sensei logo

环境搭建

Final code

在本课程中，我们将配置我们的环境，准备好所有的工具，以开始构建我们的第一个3D应用。然后我们将创建我们的第一个React项目并安装我们需要的依赖。

你的操作系统无关紧要。我使用的是Mac，但你也可以在Windows或Linux上继续进行。

Visual Studio Code

你可以使用任何你喜欢的代码编辑器，但我推荐使用Visual Studio Code。它是免费的、开源的，并且拥有众多优良的扩展。

你可以在这里下载：https://code.visualstudio.com/

如果你选择使用Visual Studio Code，这里有一些我推荐的扩展：

  • ESLint：JavaScript和JSX的Linting工具。它会在你的代码中显示错误和警告。
  • Prettier：代码格式化工具。它会根据你的设置在保存时自动格式化你的代码。
  • Copilot：AI编程助手。它会根据你的上下文为你提供代码建议，让你更快地编写代码。

Node.js

Node.js 是基于Chrome V8 JavaScript引擎构建的JavaScript运行环境。它允许你在浏览器之外运行JavaScript代码。在我们的案例中，我们将使用它来运行我们项目的开发服务器。

你可以在这里下载：https://nodejs.org/en/download/

下载LTS版本。它是最稳定的版本。

Yarn

Yarn 是一个 JavaScript 的包管理器。它类似于 npm，但速度更快且更安全。

你可以在这里下载：https://classic.yarnpkg.com/en/docs/install

我们将使用它来安装项目所需的库。例如 Three.js，React Three Fiber 等...

Vite

Vite 是一个现代 web 项目的构建工具。它快速，轻量且易于使用。

它不需要安装。

要创建一个新的 React 项目，请打开你的终端（在 Visual Studio Code 中你可以从菜单 Terminal > New Terminal 打开）并运行以下命令：

yarn create vite

然后输入你的项目名称，按下 enter，使用键盘箭头键选择 React 作为框架和 JavaScript 作为语言。

Framework selection with Vite

你应看到如下画面：

Project successfully created

现在在 Visual Studio Code 中，通过点击 Open Folder 打开项目文件夹并选择你刚创建的文件夹。

在终端中，运行以下命令以安装依赖并启动项目的开发服务器：

yarn
yarn dev

你的终端应该会提供一个本地 URL 来访问你的项目：

Development server started

在浏览器中打开它，或者在 Mac 上使用快捷键 cmd + click 或在 Windows/Linux 上 ctrl + click 点击 URL，你应该会看到默认的 Vite React 页面：

Default Vite React page

我们现在有一个能够正常工作的 React 项目了。接下来是安装我们需要的库。

React Three Fiber

要将 r3f 添加到我们的项目中，在终端中运行以下命令：

yarn add three @types/three @react-three/fiber

如果你的终端仍在运行开发服务器，请在运行上述命令之前按下 Mac 上的 cmd + c 或 Windows/Linux 上的 ctrl + c 停止它。

这将会把 three 和 react-three-fiber 安装为我们项目的依赖。

完成后，删除 App.css 文件，并用以下内容替换 index.css 的内容：

#root {
  width: 100vw;
  height: 100vh;
}

body {
  margin: 0;
}

这将使我们的 canvas 填满整个屏幕。

用以下内容替换 App.jsx 中的内容：

import { Canvas } from "@react-three/fiber";

function App() {
  return (
    <Canvas>
      <mesh>
        <boxGeometry />
        <meshNormalMaterial />
      </mesh>
    </Canvas>
  );
}

export default App;

Canvas 组件是每个 r3f 应用程序的根组件。它是一个创建 WebGL 上下文 和 Three.js 场景 的 React 组件。

在 Canvas 组件内部，我们有一个 mesh 组件。mesh 是可以在场景中渲染的对象。它由 geometry 和 material 组成。

如果你不理解 geometry 或 material 是什么，不用担心，我们将在后续课程中介绍。你只需知道这段代码将在屏幕中央渲染一个 立方体。

然后再次运行 yarn dev 来使用新依赖启动开发服务器。

你应该在屏幕中央看到一个正方形：

First r3f scene

但它看起来是二维的而不是三维的，这是因为 立方体 在 camera 的前方。

我们可以通过在 Canvas 组件中加入 camera 属性，将 camera 稍微向上、向右和向后移动：

<Canvas camera={{ position: [3, 3, 3] }}>

我们将在后续课程中介绍定位是如何工作的。

现在立方体在三维空间中可见：

First r3f scene camera moved

版本 ⚠️

Three.js 和 React Three Fiber 是经常更新的库。这意味着，如果你使用的版本不同，那么在本课程或其他教程中看到的代码可能会有不同的行为。

在撰写本课程时，Three.js 正在迁移到 WebGPU，这很可能会导致重大的更改或渲染方式的变化。

通过使用本课程提供的入门包，你可以确保使用的版本与你的一致，但了解如何检查依赖项的版本是很重要的。

打开 package.json 文件，查找 dependencies 和 devDependencies 对象：

{
  "name": "react-three-fiber-starter",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "lint": "eslint src --ext js,jsx --report-unused-disable-directives --max-warnings 0",
    "preview": "vite preview"
  },
  "dependencies": {
    "@react-three/drei": "^9.74.14",
    "@react-three/fiber": "^8.13.0",
    "@types/three": "^0.152.1",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "three": "^0.153.0"
  },
  "devDependencies": {
    "@types/react": "^18.0.37",
    "@types/react-dom": "^18.0.11",
    "@vitejs/plugin-react": "^4.0.0",
    "eslint": "^8.38.0",
    "eslint-plugin-react": "^7.32.2",
    "eslint-plugin-react-hooks": "^4.6.0",
    "eslint-plugin-react-refresh": "^0.3.4",
    "vite": "^4.3.9"
  }
}

你可以看到 Three.js 的版本是 ^0.153.0，而 React Three Fiber 的版本是 ^8.13.0。

符号 ^ 表示我们使用的是 semver 版本。 这意味着我们会收到库的所有更新，直到下一个主要版本。

要了解更多关于 语义化版本控制 的信息，请查看此链接: https://devhints.io/semver

ESLint

如果您为 Visual Studio Code 安装了 ESLint extension，您应该会在代码中看到一些错误。

这是因为 Vite 创建的默认配置文件不包含 r3f 规则。

为了解决这个问题，打开 .eslintrc.cjs 文件并在 extends 数组中添加这一行：

"plugin:@react-three/recommended",

整个文件应如下所示：

module.exports = {
  env: { browser: true, es2020: true },
  extends: [
    "eslint:recommended",
    "plugin:react/recommended",
    "plugin:react/jsx-runtime",
    "plugin:react-hooks/recommended",
    "plugin:@react-three/recommended",
  ],
  parserOptions: { ecmaVersion: "latest", sourceType: "module" },
  settings: { react: { version: "18.2" } },
  plugins: ["react-refresh"],
  rules: {
    "react-refresh/only-export-components": "warn",
  },
};

现在保存文件后，错误应该会消失。

为了能够 lint 我们的代码，我们需要将 @react-three/eslint-plugins 包安装到我们项目的开发依赖中：

yarn add -D @react-three/eslint-plugin

-D 将作为开发依赖安装该包。（因为它在最终的生产构建中不需要）

Drei

Drei 是一个在 r3f 之上提供的有用 helper 和抽象的集合。

在接下来的课程中，我们将大量使用它以更轻松和快速地创建 3D 体验。

要安装 drei 包，请在终端运行以下命令：

yarn add @react-three/drei

总结

我们已经为项目安装了所有需要的依赖，现在有了一个可以运行的 r3f 项目。这是我们开始创建 3D 体验的起点。

< React Three Fiber
3D Objects >