使用react-three-fiber加载GLB模型时出现URL解析失败错误

问题场景 #

我使用@react-three/fiber和@react-three/drei渲染3D模型，通过npx gltfjsx@6.1.4将.gltf文件转换为.tsx模块，核心代码如下：

import * as Models from './models'
import { OrbitControls } from '@react-three/drei/core/OrbitControls.cjs';
    
function Three(){
    return(
        <div style={{height: '100%'}}>
        <Canvas>
            <Suspense fallback={null}>
                <OrbitControls/>
                {Models.Cube}
            </Suspense>
        </Canvas>
        </div>
    )
}

export default Three;

models文件夹包含三个文件：

• Cube.tsx（gltfjsx生成的组件）
• cube-transformed.glb（转换后的模型文件）
• index.js（内容：export {Model as Cube} from './Cube'）

Cube.tsx核心逻辑代码：

/*
Auto-generated by: https://github.com/pmndrs/gltfjsx
Command: npx gltfjsx@6.1.4 cube.gltf --transform --shadows -k -t
*/

import * as THREE from 'three'
import React from 'react'
import { useGLTF } from '@react-three/drei'
import { GLTF } from 'three-stdlib'

type GLTFResult = GLTF & {
  nodes: {
    Main_cube: THREE.Mesh
    glowing_tubes: THREE.Mesh
    Cylinder007: THREE.Mesh
    Cylinder007_1: THREE.Mesh
    inner_fdark_cube: THREE.Mesh
  }
  materials: {
    ['main cube']: THREE.MeshStandardMaterial
    cube_pink_light: THREE.MeshStandardMaterial
    ['simple inner cube']: THREE.MeshStandardMaterial
  }
}

export function Model(props: JSX.IntrinsicElements['group']) {
  const { nodes, materials } = useGLTF('/cube-transformed.glb') as GLTFResult
  return (
    <group {...props} dispose={null}>
      <mesh name="Main_cube" castShadow receiveShadow geometry={nodes.Main_cube.geometry} material={materials['main cube']}>
        <mesh name="glowing_tubes" castShadow receiveShadow geometry={nodes.glowing_tubes.geometry} material={materials.cube_pink_light} position={[0, 0.25, 0]} />
        <group name="Heart_cyl_3_white" position={[0, 0.26, 0]}>
          <mesh name="Cylinder007" castShadow receiveShadow geometry={nodes.Cylinder007.geometry} material={materials['main cube']} />
          <mesh name="Cylinder007_1" castShadow receiveShadow geometry={nodes.Cylinder007_1.geometry} material={materials.cube_pink_light} />
        </group>
        <mesh name="inner_fdark_cube" castShadow receiveShadow geometry={nodes.inner_fdark_cube.geometry} material={materials['simple inner cube']} position={[0, 0.26, 0]} />
      </mesh>
    </group>
  )
}

useGLTF.preload('/cube-transformed.glb')

运行时，以下两行代码抛出错误：

const { nodes, materials } = useGLTF('/cube-transformed.glb') as GLTFResult;
useGLTF.preload('/cube-transformed.glb');

错误信息：TypeError: Failed to parse URL from /cube-transformed.glb

已尝试将cube-transformed.glb放在models目录和Next.js的public目录，均未解决。

解决方案 #

方案一：直接导入GLB文件（推荐） #

Next.js支持静态资源直接导入，让框架自动处理路径，避免手动路径错误：

1. 在Cube.tsx顶部添加GLB文件的导入：

   import cubeGLB from './cube-transformed.glb'
   

2. 修改useGLTF的调用和预加载代码：

   const { nodes, materials } = useGLTF(cubeGLB) as GLTFResult;
   useGLTF.preload(cubeGLB);
   

方案二：修正public目录下的路径 #

如果坚持使用路径字符串，需确保路径与public目录结构完全匹配：

1. 将cube-transformed.glb移动到public/models目录（若无models子目录则新建）。
2. 修改Cube.tsx中的路径：

   const { nodes, materials } = useGLTF('/models/cube-transformed.glb') as GLTFResult;
   useGLTF.preload('/models/cube-transformed.glb');
   

额外检查项 #

• 确保文件名拼写、大小写完全一致（Linux/macOS环境区分文件名大小写）。
• 若使用Next.js 13+ App Router，需在Three组件顶部添加客户端组件指令：

  'use client';
  

  因为@react-three/fiber依赖浏览器环境运行。

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