React应用部署至GitHub Pages后页面显示黑屏,该如何排查错误?
React应用部署GitHub Pages黑屏问题排查步骤
- 首先检查
package.json中的homepage字段配置,你的项目部署在二级路径/my-portfolio下,必须正确配置该字段:
也可简写为"homepage": "https://itsmenick.github.io/my-portfolio""homepage": "."使用相对路径,或"homepage": "/my-portfolio",配置错误会导致静态资源加载路径错误,返回404引发黑屏。 - 检查路由配置:GitHub Pages为静态文件服务,默认不支持
BrowserRouter的H5历史模式,直接使用会导致路由匹配失败:- 建议将路由组件替换为
HashRouter,适配静态服务场景 - 如果坚持使用
BrowserRouter,需要给组件添加basename属性:<BrowserRouter basename="/my-portfolio">,同时配置404跳转规则
- 建议将路由组件替换为
- 打开浏览器控制台(F12)切换到Network面板,检查静态资源(js、css、图片)是否出现404错误,确认资源路径是否携带
/my-portfolio前缀,无前缀则为路径配置错误 - 检查
gh-pages分支内容,确认部署时是将build文件夹下的所有内容推送到该分支,而非整个项目源码,分支根目录必须存在打包后的index.html入口文件 - 切换到控制台Console面板,检查是否存在JavaScript运行报错,例如组件渲染异常、依赖缺失等运行时错误,此类错误会导致React应用终止渲染,出现黑屏
内容的提问来源于stack exchange,提问作者Nikhil Mehta
相关产品推荐
相关产品推荐

