Vite+Vue3+TS项目导入three.js SVGLoader报504网关超时错误

这个504 Gateway Timeout不是真实的网络网关错误，是Vite本地开发服务器的依赖预构建环节处理three.js示例模块时阻塞/超时，返回的错误状态码，常见触发原因有三个：

• Vite默认对node_modules下的依赖做ESM预打包，three/examples/jsm路径下的模块存在深层互相关联的依赖链，Vite 4及更早版本扫描依赖时容易出现解析阻塞、甚至临时死循环，最终触发超时
• 依赖版本不兼容：使用r150以上版本的three.js搭配低版本Vite时，ESM模块解析逻辑不匹配，预构建SVGLoader时进程卡住
• Vite开启了严格预构建校验，但没有提前将SVGLoader加入预构建白名单，页面访问时才触发临时按需预构建，大模块构建耗时超过Vite默认超时阈值触发504

按优先级依次尝试：

1. 清理Vite缓存后重启服务，解决偶发的预构建进程卡住问题
   执行以下命令：

   # 删除Vite预构建缓存目录
   rm -rf node_modules/.vite
   # 重启本地开发服务
   npm run dev
   

2. 手动在Vite配置中声明需要预构建的three相关模块，避免运行时临时预构建超时
   配置示例：

   // vite.config.ts
   import { defineConfig } from 'vite'
   import vue from '@vitejs/plugin-vue'
   
   export default defineConfig({
     plugins: [vue()],
     optimizeDeps: {
       include: [
         'three',
         'three/examples/jsm/loaders/SVGLoader'
       ]
     }
   })
   

3. 修复版本兼容问题
   • 将Vite升级到5.0及以上稳定版本，该版本对深层ESM依赖的预构建效率、路径解析兼容性有明显提升
   • 安装对应稳定版three和类型定义，避免使用beta/next分支版本：

     npm install three@latest
     npm install -D @types/three@latest
     

4. 替换为官方推荐的导入路径
   three.js r148及以上版本推荐使用three/addons/作为示例模块的规范导入路径，路径解析更符合ESM标准，能减少Vite的解析异常，导入代码修改为：

   import { SVGLoader } from 'three/addons/loaders/SVGLoader.js'
   

   注意路径末尾必须加.js后缀。

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