使用Vite部署Babylon.js至GitHub Pages遇空白页及MIME类型错误

问题描述 #

使用Vite打包Babylon.js游戏并部署到GitHub Pages时，遇到两个核心问题：

• 构建生成的dist文件夹中，index.html打开为空白页面
• 访问部署后的GitHub Pages时，出现MIME类型错误：

  Failed to load module script: Expected a JavaScript-or-Wasm module script but the server responded with a MIME type of "video/mp2t". Strict MIME type checking is enforced for module scripts per HTML spec.
  

相关配置文件：

• Vite配置：vite.config.js
• TS配置：tsconfig.json
• package.json

已尝试但未解决的操作：

• 在vite.config中设置base为'/'、'./'及空值
• 执行vite build --base=/命令构建dist目录
• 移除vite.config中的"build.emptyOutDir"和"server"配置项
• 修改index.html中的文件路径为"/src"、"./src"及"src"

解决建议 #

针对空白页面问题 #

1. 修正Vite base配置
   GitHub Pages项目站点（非根域名站点）的base必须设置为仓库名称，在vite.config.js中配置：

   export default defineConfig({
     base: '/defiance-engine/',
     // 其他原有配置
   })
   

   配置完成后执行vite build，不要额外添加--base=/参数覆盖配置。

2. 验证dist资源完整性与本地预览
   构建后检查dist目录是否包含所有必需的静态资源（js、css、assets等）；执行vite preview本地预览dist目录，确认本地能否正常显示——如果本地也空白，打开浏览器控制台查看具体报错（资源加载失败/代码运行错误）。

3. 检查Babylon.js依赖打包规则
   确认vite.config.js的build.rollupOptions没有错误排除Babylon.js相关依赖，确保所有引擎相关代码被正确打包进dist资源。

针对MIME类型错误问题 #

该错误本质是资源路径解析错误，导致服务器误将JS/Wasm文件识别为视频资源：

1. 确认资源路径正确性
   检查dist/index.html中script标签的src路径，应符合base配置的相对路径规则，例如/defiance-engine/assets/index-xxx.js，避免路径错误触发服务器返回异常MIME类型。

2. 确认GitHub Pages部署源配置
   进入仓库Settings -> Pages，确认部署源设置为dist文件夹；若使用GitHub Actions部署，检查Action脚本是否正确将dist目录内容推送至Pages服务。

3. 清理缓存并重新部署
   GitHub Pages可能缓存旧资源，可通过提交空commit触发重新部署，或在浏览器中使用Ctrl+F5强制刷新清除本地缓存。

额外排查点 #

• 确保Babylon.js使用ES模块方式导入（如import * as BABYLON from '@babylonjs/core'），避免CommonJS导入方式导致打包异常。
• 始终通过浏览器F12控制台的Console、Network标签定位问题：Network标签查看资源返回状态码与MIME类型，Console标签查看代码运行报错，这是快速定位问题的核心手段。

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