在小程序中使用 React Three Fiber 快速搭建 3D 场景

minisheeep

已于 2025-05-08 13:22:43 修改

阅读量1k

点赞数 11

文章标签：小程序 react.js 3d

于 2025-05-07 19:22:22 首次发布

本文链接：https://blog.csdn.net/qq_26482581/article/details/147768465

版权

示例展示

示例1 示例2 示例3

什么是 React Three Fiber（R3F）？

React Three Fiber，简称 R3F，是一个基于 three.js 的 React 渲染器。它将 WebGL 场景以 React 组件的形式封装，使得开发者可以像写 React 页面一样去构建和组织 3D 场景。

如果你对 R3F 尚不了解，可以参考官方文档。本篇文章将重点介绍如何在小程序中集成并运行 R3F。

如何在小程序中使用 three.js？

如果你尚未了解如何在小程序中使用 three.js，推荐先阅读我之前的文章：《如何在小程序中优雅地使用 three.js》，为本篇打下基础。

快速启动示例

推荐直接使用模板仓库进行体验，顶部所有的 Demo 都可以在下方模板找到：

npx degit minisheeep/threejs-miniprogram-template#uni-ts-r3f my-project
cd my-project
pnpm install
pnpm dev:open

手动集成指南

如果你希望在现有小程序项目中手动集成 R3F，可按如下步骤操作。
当前支持基于 vite 或 rollup 的构建系统，未来将支持更多环境。

第一步：添加 `.npmrc` 配置

由于部分依赖未发布至 npm 官方仓库，需手动指定私有源：

@minisheep:registry=https://npm.minisheep.cn

第二步：安装依赖

pnpm i @minisheep/mini-program-polyfill-core @minisheep/three-platform-adapter @minisheep/platform-adapter-integration react @react-three/fiber @react-three/drei three
pnpm i @vitejs/plugin-react -D

第三步：配置 `vite.config.js`

import { defineConfig } from 'vite';
import threePlatformAdapter from '@minisheep/three-platform-adapter/plugin';
import react from '@vitejs/plugin-react';
// import { supportR3fInUni } from '@minisheep/platform-adapter-integration/r3f/plugin'; // 如果你使用 uni-app

export default defineConfig({
  plugins: [
    threePlatformAdapter(),
    react(),
    // supportR3fInUni(),
  ],
});

编写基础 3D 场景

`scenes/baseScene.jsx`

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

export function createBaseScene(eventSource) {
  return (
    <Canvas eventSource={eventSource}>
      <mesh>
        <torusGeometry args={[1, 0.5, 16, 32]} />
        <meshBasicMaterial color="orange" />
      </mesh>
      <ambientLight intensity={1} />
    </Canvas>
  );
}

小程序页面配置

`pages/scene.wxml`

<canvas
  type="webgl2"
  id="r3f_demo"
  bindtouchstart="defaultHandler"
  bindtouchmove="defaultHandler"
  bindtouchcancel="defaultHandler"
  bindtouchend="defaultHandler"
  bindtap="defaultHandler"
/>

`pages/scene.js`

import { adapter } from "@minisheep/three-platform-adapter";
import { createRoot } from "@minisheep/platform-adapter-integration/r3f";
import { createBaseScene } from "../scenes/baseScene";

Page({
  app: null,
  onLoad(query) {
    this.sceneId = query?.scene ?? 'base';
  },
  async onReady() {
    const result = await adapter.useCanvas('#r3f_demo', this);
    this.defaultHandler = result.eventHandler;
    this.app = createRoot(result.canvas).render(createBaseScene(result.canvas));
  },
  defaultHandler(e) {},
  onUnload() {
    this.app?.unmount();
  }
});