部署后GitHub Pages上的React应用显示空白页问题排查

问题描述 #

将React应用托管到GitHub Pages后，页面显示空白无内容，控制台抛出以下错误：

/%PUBLIC_URL%/manifest.json:1     
Failed to load resource: the server responded with a status of 400 ()
/%PUBLIC_URL%/manifest.json:1 Manifest: Line: 1, column: 1, Syntax error.

本地运行完全正常，仅部署版本出现问题。项目结构如下：

├── CNAME
├── index.html  
├── package-lock.json
├── package.json  
├── postcss.config.js
├── public
│   ├── CNAME  
│   ├── favicon.ico  
│   ├── index.html  
│   ├── manifest.json
│   └── robots.txt  
├── src
│   ├── App.js  
│   ├── assets
│   │   ├── C++.png
│   │   ├── StreetAssist.png
│   │   ├── WHDparser.PNG
│   │   ├── angular.png
│   │   ├── aws.png
│   │   ├── bereaCollege.jpg
│   │   ├── bootstrap.png
│   │   ├── css.png
│   │   ├── ecoB4C.jpg
│   │   ├── flask.png
│   │   ├── git.png
│   │   ├── github.png
│   │   ├── golang.png
│   │   ├── html.png
│   │   ├── javascript.png
│   │   ├── logo.png
│   │   ├── mold.png
│   │   ├── mysql.png
│   │   ├── powershell.png
│   │   ├── python.png
│   │   ├── react.png
│   │   ├── reactPortfolio.PNG
│   │   ├── sqlite.png
│   │   └── tailwind.png
│   ├── components
│   │   ├── About.jsx
│   │   ├── Contact.jsx
│   │   ├── Experience.jsx
│   │   ├── Home.jsx
│   │   ├── Navbar.jsx
│   │   ├── Skills.jsx
│   │   └── Work.jsx
│   ├── index.css
│   └── index.js
└── tailwind.config.js

托管网址：https://www.garrett-clark.com/
仓库地址：https://github.com/Boorclark/boorclark.github.io

解决方案 #

1. 配置package.json的homepage字段 #

在package.json中添加或确认homepage配置，值为你的自定义域名：

"homepage": "https://www.garrett-clark.com/"

该字段会在构建时自动替换index.html中的%PUBLIC_URL%变量，确保资源路径正确。

2. 清理重复的根目录文件 #

项目根目录存在额外的index.html和CNAME文件，这会与React构建后的build目录文件冲突：

• 删除根目录的index.html和CNAME，仅保留public目录下的对应文件，构建时public目录的文件会被自动复制到build目录中。

3. 确认部署流程正确 #

• 执行npm run build生成最新的构建产物（build目录）。
• 确保GitHub Pages的部署来源指向build目录：如果使用main分支部署，需在仓库设置中选择main分支的/build文件夹；如果使用gh-pages分支，需将build目录内容推送到该分支。

4. 清理缓存并重新部署 #

• 删除仓库中旧的构建文件，重新推送最新的build目录内容。
• 在浏览器中强制刷新页面（Ctrl+F5），清除本地缓存。

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