如何将React应用部署到GitHub Pages并正常展示？

正确部署步骤 #

• 安装部署依赖：在项目根目录执行 npm install gh-pages --save-dev
• 修改package.json配置：
  1. 在文件顶部添加主页地址，替换成你的GitHub用户名和仓库名：

     "homepage": "https://你的GitHub用户名.github.io/你的仓库名/"
     

  2. 在scripts字段中新增两个部署脚本：

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

• 提交项目代码到GitHub的主分支（如main）
• 执行部署命令：npm run deploy，该命令会自动构建项目，并将build文件夹的内容推送到仓库的gh-pages分支
• 配置GitHub Pages：进入仓库的Settings -> Pages页面，确认源分支选择gh-pages、目录选择/root，保存后等待几分钟即可访问

为什么直接上传HTML文件无效 #

直接上传public目录下的index.html只会显示默认的"Getting Started with Create React App"，原因是：

• Create React App是单页应用，运行依赖打包后的静态资源（JS、CSS、图片等），这些资源在build目录中，直接传HTML文件会缺失这些依赖
• 未经过构建的代码没有处理路由、资源路径等适配GitHub Pages的配置，导致页面无法正常加载

常见错误排查 #

• 页面空白：检查homepage的URL是否拼写正确，确认gh-pages分支中存在static目录及完整的构建资源
• 样式丢失：确保npm run build执行过程无报错，构建后的build目录完整
• 路由刷新404：如果使用react-router，需将BrowserRouter替换为HashRouter，因为GitHub Pages不支持SPA的路由重定向规则

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