本文详解在 react 中使用 @react-three/drei 的 usegltf 加载本地 .gltf 文件时常见的路径错误（如返回 html 而非模型）、解决方案及最佳实践。
本文详解在 react 中使用 @react-three/drei 的 usegltf 加载本地 .gltf 文件时常见的路径错误（如返回 html 而非模型）、解决方案及最佳实践。
在 React + Three.js 项目中，通过 useGLTF 加载 GLTF 模型时出现 “Unexpected token '<', '<!DOCTYPE...' is not valid JSON” 错误，本质是浏览器尝试请求一个 HTML 页面（通常是开发服务器的 fallback index.html），而非真正的 GLTF 文件——这说明资源路径未被正确解析为静态资源，而是被前端路由或 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 (
<primitive object={nodes.FSFenix} material={materials.default} />
);
}⚠️ 注意事项：
- ✅ 文件必须放在 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 显示 <DOCTYPE html> —— 这说明路径错误，服务器返回了 index.html。
? 进阶建议
-
优化加载体验：配合 Suspense 和 ErrorBoundary 处理加载状态与失败：
import { Suspense } from 'react'; import { Canvas } from '@react-three/fiber'; function App() { return ( <Canvas> <Suspense fallback={<LoadingSpinner />}> <Model /> </Suspense> </Canvas> ); } GLB 更推荐：若模型含纹理和动画，优先导出为 .glb（单文件二进制格式），更易部署且无外部资源路径问题；
生产环境注意：确保构建后 public/ 中的 GLTF 文件被正确复制到最终 dist/ 目录（Create React App 默认支持）。
遵循以上规范，即可彻底规避 “HTML instead of GLTF” 类错误，让 3D 模型稳定、高效地渲染在 React 应用中。
