如何使用gh-pages正确发布React应用 部署后页面无法渲染报错

你遇到的部署后白屏、应用不渲染问题本质是静态资源路径匹配错误：

• 控制台明确报出JS/CSS等打包资源404：
• 现有package.json未配置Github Pages对应的路径基准：
• 入口HTML引用的资源默认走站点根路径，和Github Pages项目页的子路径规则不匹配：

React项目执行build时，默认将公共资源路径设为根路径/，但Github Pages的项目页访问路径是https://<用户名>.github.io/<仓库名>/，所有资源都在/仓库名/这个子路径下，根路径请求自然找不到文件，导致应用无法加载。

1. 基础配置 #

打开项目根目录的package.json文件：

• 在配置最顶层新增homepage字段，值为你的Github Pages最终访问地址，格式固定为：

"homepage": "https://<你的Github用户名>.github.io/<当前项目的仓库名>"

例：用户名为zhangsan，仓库名为react-shop，则配置为"homepage": "https://zhangsan.github.io/react-shop"

• 找到scripts配置块，新增两个部署命令，原有启动、打包命令保留即可：

"scripts": {
  "start": "react-scripts start",
  "build": "react-scripts build",
  // 新增以下两行
  "predeploy": "npm run build",
  "deploy": "gh-pages -d build"
}

如果项目使用React Router的BrowserRouter，需要给组件添加basename属性，值为/<仓库名>，否则路由跳转后会出现404

2. 安装部署工具 #

在项目根目录终端执行命令，安装gh-pages部署依赖：
npm install gh-pages --save-dev

3. 执行部署 #

终端执行部署命令：
npm run deploy
命令会自动执行打包、创建/更新gh-pages分支、上传打包产物的全流程。执行完成后打开Github仓库的Settings-Pages页面，确认部署源选择gh-pages分支、根目录，等待1-2分钟生效即可访问。

1. 按照上述标准流程补全package.json中的homepage字段和scripts部署命令
2. 检查入口public/index.html，如果有手动写的/static/xxx.js这类根路径开头的资源引用，全部删掉，React打包时会自动注入匹配路径的资源标签
3. 重新执行npm run deploy完成部署，访问时按Ctrl+F5强刷浏览器清除缓存，应用即可正常渲染

不要手动把build目录的文件推送到gh-pages分支，gh-pages命令会自动处理路径替换、分支提交的逻辑，手动操作很容易出现路径错误

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