react-three-start

react-three-start

@react-three/start 是一个以客户端为先的 React Three Fiber 应用外壳。它负责 Vite/React 引导、根元素、全屏 Canvas、场景发现、DOM 覆盖层和包装器组合。应用作者主要在 src/ 下添加文件。

项目结构

src/
  cube.scene.tsx      # rendered inside <Canvas>
  lights.scene.tsx    # rendered inside <Canvas>
  hud.dom.tsx         # rendered in the DOM overlay
start.config.ts       # optional framework config

使用 react-three-start dev、react-three-start build 和 react-three-start preview；r3s 是简写别名。使用 npx @react-three/start create my-app 创建应用。

入口文件

• src/**/*.scene.tsx 文件是 3D 层。默认导出 R3F 对象、灯光、摄像机、控制器、物理刚体或提供程序。
• src/**/*.dom.tsx 文件是 DOM 覆盖层。默认导出普通的 React DOM UI。
• 入口会自动发现并按路径排序。对于常规应用组合，不要创建手动场景注册表。
• DOM 覆盖层内容会固定在视口上方。使用默认注入的 Canvas 时，覆盖层容器的 pointer-events 为 none，因此交互式 DOM 控件应设置 pointerEvents: 'auto'。

插槽与包装器

仅在已发现的 *.scene.tsx 和 *.dom.tsx 入口文件中，从 @react-three/start 导入 Scene 或 Dom。Vite 插件会将这些导入重写为延续组件。

导入并渲染 <Scene /> 的场景文件会成为场景包装器。对于必须包裹其余 3D 场景的提供程序，请使用包装器：XR、物理、Suspense、控制器和环境设置。文件名排序决定嵌套顺序。

// src/00-xr.scene.tsx
import { Scene } from '@react-three/start'
import { Physics } from '@react-three/rapier'

export default function PhysicsWrapper() {
  return (
    <Physics>
      <Scene />
    </Physics>
  )
}

00-xr.scene.tsx       # outer wrapper
10-physics.scene.tsx  # inner wrapper
cube.scene.tsx        # leaf scene entry

导入并渲染 <Dom /> 的 DOM 文件会成为 DOM 包装器。DOM 文件也可以在手动管理 Canvas 时导入 <Scene />。

手动 Canvas

默认情况下，react-three-start 会注入全屏 Canvas，并在其中渲染 <Scene />。当需要自行管理布局、阴影、摄像机属性、XR 按钮或多个面板时，请禁用注入，并从 DOM 入口渲染 Canvas。

// start.config.ts
export default {
  injectCanvas: false,
  title: 'My R3F app'
}

// src/app.dom.tsx
import { Canvas } from '@react-three/fiber'
import { Scene } from '@react-three/start'

export default function App() {
  return (
    <Canvas shadows camera={{ position: [0, 2, 6], fov: 45 }}>
      <Scene />
    </Canvas>
  )
}

start.config.ts 可以导出 injectCanvas、title 和嵌套的 vite 配置对象。CLI 会将 vite 与生成的 Vite 配置合并，并将其余选项传递给 reactThreeStart()。优先使用 start.config.ts；仅在需要常规 Vite 管理时才添加 vite.config.ts。

Agent 使用要点

• 除非必须包裹其他场景入口，否则应将新的视觉内容添加为小型 *.scene.tsx 叶节点。
• 将 UI 添加为 *.dom.tsx；确保交互式覆盖层元素显式启用指针事件。
• 使用数字文件名前缀确定包装器顺序，而非导入顺序。
• 仅在入口文件中导入 Scene 和 Dom；通过常规导入传递普通 React 组件。
• 仅当默认全屏 Canvas 的限制过多时，才使用手动 Canvas。