react-three-fiber项目Webpack加载GLB文件报错如何解决

核心报错原因 #

Module parse failed: Unexpected character '' (1:4)是Webpack尝试把二进制GLB文件当作JS/TS模块解析导致的，触发场景集中在三类：

• Webpack 5环境下混用已废弃的file-loader处理GLB，规则匹配失效
• resolve.extensions未配置.glb/.gltf后缀，导入时路径解析异常
• GLB文件导入路径写错、漏写文件后缀，或文件本身损坏

修复步骤 #

优先方案（适配Webpack 5，无需额外依赖） #

Webpack 5已经内置资源处理能力，不需要单独装file-loader/url-loader，直接替换原有GLB处理规则即可，和你当前处理图片、字体的规则逻辑保持一致：

1. 删除配置文件中原有针对glb/gltf的file-loader规则，替换为内置资源规则：

   {
     test: /\.(glb|gltf)$/i,
     type: 'asset/resource',
     generator: {
       filename: 'assets/models/[hash][ext][query]' // 保持你之前配置的模型输出目录
     }
   },
   

2. 修改resolve.extensions配置，补充模型后缀，避免路径解析时跳过自定义规则：

   resolve: {
     extensions: [".tsx", ".ts", ".js", ".css", ".glb", ".gltf"],
   },
   

兼容方案（适配Webpack 4及以下版本） #

如果你的项目用的是Webpack 4，无法使用内置Asset Modules，按以下调整：

1. 先确认项目已安装file-loader依赖，未安装的话执行安装命令：

   npm install file-loader --save-dev
   

2. 修改原有GLB规则，补充esModule: false配置，解决和react-three-fiber导入逻辑的兼容问题：

   {
     test: /\.(glb|gltf)$/,
     use: [
       {
         loader: 'file-loader',
         options: {
           outputPath: 'assets/models/',
           esModule: false
         }
       }
     ]
   },
   

3. 和上面的步骤一致，把.glb、.gltf补充到resolve.extensions列表中。

排障校验点 #

• 检查组件内导入GLB的语句，确保路径正确、后缀完整，示例：import gumballmachinepink from '../models/gumballmachinepink.glb'
• 找一个确认可用的标准GLB测试文件替换当前模型，排除文件本身损坏的问题
• 改完Webpack配置后必须完全停掉当前开发服务、重新执行构建/启动命令，Webpack配置改动不会触发热更新，不重启会一直加载旧配置

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