Next.js 14中react-three-fiber的<mesh>标签未识别问题求助

浏览器无法识别标签。如果您想渲染React组件，请将其名称以大写字母开头

环境与代码 #

Next.js 14项目，使用gltfjsx生成Ethereum组件，代码如下：

/*
Auto-generated by: gltfjsx
Command: npx gltfjsx@6.2.16 mystic+ethereum+in+place+vertical.gltf --transform 
Files: mystic+ethereum+in+place+vertical.gltf [133.47MB] > /home/mystic+ethereum/mystic+ethereum+in+place+vertical-transformed.glb [886.29KB] (99%)
*/
"use client";
import { extend } from "@react-three/fiber";

import React, { useRef, useEffect } from "react";
import { useGLTF } from "@react-three/drei";
import { useFrame, useThree } from "@react-three/fiber";
// this enables animations
import { a } from "@react-spring/three";

export function Ethereum(props) {
  const ethereumRef = useRef();
  const { nodes, materials } = useGLTF(
    "/mystic+ethereum+in+place+vertical-transformed.glb"
  );
  return (
    <a.group {...props}>
      <mesh
        geometry={nodes.mesh_0.geometry}
        material={materials.PaletteMaterial001}
      />
      <mesh
        geometry={nodes.mesh_1.geometry}
        material={materials.PaletteMaterial002}
      />
      <mesh
        geometry={nodes.mesh_2.geometry}
        material={materials.PaletteMaterial003}
      />
    </a.group>
  );
}

useGLTF.preload("/mystic+ethereum+in+place+vertical-transformed.glb");

Home页面渲染代码：

export default function Home() {
  return (
    <main className="flex min-h-screen flex-col items-center justify-between p-24 bg-white">
      <div className="z-10 max-w-5xl w-full items-center justify-between font-mono text-sm lg:flex">
        <>
          <Canvas
            className={`w-full h-screen bg-transparent 
          `}
            camera={{ near: 0.1, far: 1000 }}
          >
            <Suspense fallback={<Loader />}>
              <directionalLight position={[1, 1, 1]} intensity={2} />
              <ambientLight intensity={0.5} />
              <pointLight position={[10, 5, 10]} intensity={2} />
              <spotLight
                position={[0, 50, 10]}
                angle={0.15}
                penumbra={1}
                intensity={2}
              />
              <hemisphereLight
                groundColor="#000000"
                intensity={1}
              />

              <Ethereum />

            </Suspense>
          </Canvas>
        </>
      </div>
    </main>
  );
}

已尝试的无效方案 #

• 将<a.group>替换为<group>
• 用<></>包裹<mesh>标签
• 使用@react-three/drei的<Html>组件包裹Ethereum组件
• 使用<a.mesh>替代<mesh>标签

解决方案 #

1. 补全客户端组件标识 #

Next.js 14默认是服务器组件，R3F的3D元素只能在客户端组件中渲染，给Home页面添加客户端指令：

"use client"; // 必须添加这一行
import { Canvas } from "@react-three/fiber";
import { Suspense } from "react";
import { Loader } from "@react-three/drei";
import { Ethereum } from "./path-to-your-component"; // 替换为实际组件路径

2. 修复Ethereum组件的动画元素关联 #

使用@react-spring/three的动画组件时，所有3D元素都要使用a.前缀的版本，确保动画上下文生效：

"use client";
import React, { useRef } from "react";
import { useGLTF } from "@react-three/drei";
import { a } from "@react-spring/three";

export function Ethereum(props) {
  const ethereumRef = useRef();
  const { nodes, materials } = useGLTF(
    "/mystic+ethereum+in+place+vertical-transformed.glb"
  );
  return (
    <a.group ref={ethereumRef} {...props}>
      {/* 所有mesh替换为a.mesh */}
      <a.mesh
        geometry={nodes.mesh_0.geometry}
        material={materials.PaletteMaterial001}
      />
      <a.mesh
        geometry={nodes.mesh_1.geometry}
        material={materials.PaletteMaterial002}
      />
      <a.mesh
        geometry={nodes.mesh_2.geometry}
        material={materials.PaletteMaterial003}
      />
    </a.group>
  );
}

useGLTF.preload("/mystic+ethereum+in+place+vertical-transformed.glb");

3. 确保依赖版本兼容 #

执行以下命令安装/更新兼容版本的依赖：

npm install three@latest @react-three/fiber@latest @react-three/drei@latest @react-spring/three@latest

4. 核心排查点 #

• 所有包含R3F元素的文件必须添加"use client";，服务器组件无法解析3D元素标签
• <mesh>、<group>等R3F元素只能在<Canvas>组件内部渲染，不能在外部使用
• 不要用<Html>包裹3D组件，该组件用于在3D场景中渲染普通DOM元素

内容的提问来源于stack exchange，提问作者Yilmaz