React项目部署GitHub Pages遇空白页及MIME类型错误求助

问题核心 #

你的React项目本地运行正常，但部署到GitHub Pages后显示空白页，控制台报错：

main.tsx:1 Failed to load module script: Expected a JavaScript module script but the server responded with a MIME type of "application/octet-stream". Strict MIME type checking is enforced for module scripts per HTML spec.

排查与解决步骤 #

• 设置正确的homepage配置
  打开项目根目录的package.json，添加或修改homepage字段，格式为https://<你的GitHub用户名>.github.io/<仓库名>，针对你的项目应该是：

  "homepage": "https://lazipops.github.io/Pokepedia"
  

  缺失或错误的homepage会导致资源路径异常，GitHub Pages无法正确识别文件类型。

• 配置部署脚本并安装依赖
  在package.json的scripts中添加部署相关命令：

  "scripts": {
    "predeploy": "npm run build",
    "deploy": "gh-pages -d build"
  }
  

  若未安装gh-pages依赖，执行命令安装：

  npm install --save-dev gh-pages
  

• 调整构建工具的基础路径（针对Vite项目）
  如果你用Vite构建项目，打开vite.config.ts，添加base配置，值为你的仓库名称：

  import { defineConfig } from 'vite';
  import react from '@vitejs/plugin-react';
  
  export default defineConfig({
    plugins: [react()],
    base: '/Pokepedia/'
  });
  

  （Create React App项目无需额外配置，确保homepage正确即可）

• 重新部署项目
  执行以下命令重新构建并部署：

  npm run deploy
  

  等待GitHub Pages部署完成后，刷新页面验证结果。

• 确认GitHub Pages部署源
  进入仓库的Settings -> Pages -> Build and deployment，确认部署源选择的是gh-pages分支的/root目录，避免因分支或路径错误导致资源加载异常。

原因说明 #

MIME类型错误本质是资源路径配置错误，导致GitHub Pages无法正确识别JS模块文件，将其标记为二进制流（application/octet-stream），进而无法加载模块，最终出现空白页。

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