You need to enable JavaScript to run this app. React应用部署至GitHub Pages后页面显示黑屏,该如何排查错误?
优惠活动
大模型
产品
解决方案
定价
更多

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

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.10.17 08:06:01