React Three.js+Vite部署Github Pages后.gltf文件加载失败求助

核心原因大概率是开发/生产环境的资源路径不匹配，尤其是Github Pages的子路径部署特性（你的站点部署在/ThreeJsReactFiber/子路径下），以下是具体排查和修复步骤：

1. 修正Vite的base配置 #

Vite默认开发环境base为/，但部署到Github Pages子路径时，必须将base设置为你的仓库名称：

// vite.config.js
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  base: '/ThreeJsReactFiber/' // 与Github仓库名称完全一致
})

这个配置会让生产打包后的所有资源路径都基于/ThreeJsReactFiber/，避免从根目录(/)查找资源导致404。

2. 统一GLTF文件的加载路径 #

不要硬编码资源路径，改用Vite提供的import.meta.env.BASE_URL来拼接，确保开发/生产环境路径一致：

方式1：使用@react-three/drei的useGLTF #

import { useGLTF } from '@react-three/drei'

const YourModel = () => {
  // 用BASE_URL拼接模型路径，适配不同环境
  const modelPath = `${import.meta.env.BASE_URL}models/your-model.gltf`
  const { scene } = useGLTF(modelPath)
  return <primitive object={scene} scale={0.5} />
}

useGLTF.preload(modelPath) // 可选：预加载提升体验

方式2：直接使用GLTFLoader #

import { useEffect, useRef } from 'react'
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader'

const YourModel = () => {
  const meshRef = useRef(null)
  
  useEffect(() => {
    const loader = new GLTFLoader()
    const modelPath = `${import.meta.env.BASE_URL}models/your-model.gltf`
    loader.load(modelPath, (gltf) => {
      meshRef.current.add(gltf.scene)
    })
  }, [])
  
  return <group ref={meshRef} />
}

3. 验证打包与部署流程 #

• 确认package.json的build命令正确：

  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "deploy": "gh-pages -d dist" // 确保用gh-pages工具部署dist目录
  }
  

• 执行npm run build后，检查dist目录下的资源路径：所有静态资源（包括GLTF文件）的引用都应该以/ThreeJsReactFiber/开头。
• 检查Github Pages设置：确保站点是从gh-pages分支的根目录部署，而非其他分支或目录。

4. 控制台报错验证 #

打开浏览器控制台（F12），查看Network面板中GLTF文件的请求地址：

• 如果请求地址是https://thehero9.github.io/models/xxx.gltf（缺失/ThreeJsReactFiber/），说明base配置未生效或路径拼接错误。
• 如果返回404，确认GLTF文件是否被正确打包到dist目录的对应路径下（比如dist/models/xxx.gltf）。

内容的提问来源于stack exchange，提问作者Vladimir B.