React+Three.js项目GLTF模型正确加载方法

本文详解在 react 中使用 @react-three/drei 的 usegltf 加载本地 .gltf 文件时常见的路径错误（如返回 html 而非模型）、解决方案及最佳实践。

在React+Three.js项目里，用useGLTF加载模型时，你可能会遇到一个让人头疼的错误：Unexpected token '<', '。这个错误看着挺唬人，但本质其实很简单——浏览器没有拿到真正的GLTF模型文件，而是被服务器甩过来一个HTML页面，通常是开发服务器的fallback index.html。说白了，就是资源路径没对上，被前端路由或Webpack开发服务器给半路截胡了。今天我们就来彻底解决它。

正确路径规则：必须使用 / 开头的绝对路径（相对于 public 根目录）

先记住一条铁律：useGLTF内部用的是浏览器原生的fetch，它不认识Node.js风格的绝对路径（比如C:/Users/...），也不吃相对路径那一套（比如./FSFenix_Render.gltf）。唯一靠谱的做法就是把GLTF文件放到public/目录下，然后用/开头来指路：

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

function Model() {
  const { nodes, materials } = useGLTF('/FSFenix_Render.gltf'); //  正确：/ 表示 public/ 根目录
  return (
    
  );
}

几个关键提醒：

• 文件必须老老实实放在public/FSFenix_Render.gltf（如果放在子目录，比如public/models/FSFenix_Render.gltf，路径就写成 /models/FSFenix_Render.gltf）；
• 别用C:/...、./...、../...或src/...这些路径——运行时浏览器根本够不着它们；
• 别把.gltf文件塞在src/下面然后试图用模块导入——useGLTF只认HTTP可访问的URL，不认模块导入路径；
• 如果用了gltfjsx生成组件，记得手动把里面的useGLTF(...)路径改成 /xxx.gltf；
• 改完路径别忘了重启开发服务器（npm start / yarn dev），缓存没清掉可能让你白忙活半天。

验证路径是否有效

怎么确认路径真的对了？打开浏览器开发者工具的Network标签页，刷新页面，找到FSFenix_Render.gltf这个请求：

• 成功：Status是200，Type是glb或json，Preview里能看到二进制或JSON结构；
• 失败：Status虽然是200，但Type是html，Preview显示的是——这就说明路径错了，服务器拿index.html来糊弄你了。

进阶建议

• 优化加载体验：搭配Suspense和ErrorBoundary，把加载状态和失败情况都处理干净：

  import { Suspense } from 'react';
  import { Canvas } from '@react-three/fiber';
  
  function App() {
    return (
      
        }>
          
        
      
    );
  }

• GLB更推荐：如果模型带纹理和动画，建议优先导出成.glb格式。单文件二进制，部署省心，也没有外部资源路径那些幺蛾子；

• 生产环境注意：构建完之后，记得确认public/里的GLTF文件有没有被正确复制到最终的dist/目录。Create React App默认会帮你搞定，但别的脚手架可能得自己检查一下。

按这套规范来，那个“HTML instead of GLTF”的报错基本上就不会再出现了。3D模型在React应用里稳定、高效地跑起来，也就不是什么难事。