Vite+React+TS部署GitHub Pages遇模块加载错误及导航栏不显示问题

核心问题定位 #

浏览器提示的application/octet-stream MIME类型错误，本质是Github Pages对Vite生成的模块脚本文件类型识别异常，导致浏览器拒绝加载符合ES模块规范的脚本，进而引发页面元素（如导航栏）渲染失败。

针对性解决方案 #

1. 修正Vite基础路径配置 #

编辑项目根目录下的vite.config.ts，确保base字段与仓库名称完全一致：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  base: '/brasa-site/'
})

2. 校验package.json脚本配置 #

确认build和deploy命令的正确性，保证构建产物目录为dist且部署流程正常：

{
  "scripts": {
    "build": "tsc && vite build",
    "predeploy": "npm run build",
    "deploy": "gh-pages -d dist"
  }
}

如果未安装gh-pages依赖，先执行：

npm install gh-pages --save-dev

3. 清理缓存后重新构建部署 #

避免旧缓存或异常构建产物引发的问题，执行以下命令重置构建流程：

rm -rf node_modules dist package-lock.json
npm install
npm run build
npm run deploy

4. 检查Github Pages部署设置 #

进入仓库的Settings -> Pages页面，确认：

• 部署来源选择gh-pages分支的/root目录
• 若使用自定义域名，确保域名解析正常，无CDN或域名配置导致的MIME类型异常

5. 强制刷新浏览器缓存 #

使用Ctrl+Shift+R（Windows）或Cmd+Shift+R（Mac）强制清除浏览器缓存，重新加载页面，避免旧资源干扰。

内容的提问来源于stack exchange，提问作者Eric Dias Macedo