React应用部署Github Pages仅显示背景色的问题排查

1. 修正package.json中的homepage配置 #

你的项目仓库是space-tourism-website，对应的GitHub Pages地址应为仓库子路径，而非个人主页根域名。当前homepage配置错误，会导致打包后资源路径失效，无法加载组件代码（仅背景色能显示是因为背景样式可能为内联或相对路径）。修改为：

"homepage": "https://farhan-navas.github.io/space-tourism-website/"

2. 配置React Router的basename #

项目部署在子路径下时，react-router-dom需要指定basename匹配路由。在路由入口文件（如index.js或App.js）中修改BrowserRouter配置：

import { BrowserRouter } from 'react-router-dom';

ReactDOM.render(
  <BrowserRouter basename="/space-tourism-website">
    <App />
  </BrowserRouter>,
  document.getElementById('root')
);

未设置basename会导致路由在根路径下匹配，找不到对应组件。

3. 修复本地开发服务器跳转问题 #

npm start自动跳转到localhost:3000/space-tourism-website是因为react-scripts会依据homepage调整开发路径。若要在localhost:3000/直接访问，修改package.json的start脚本：

"scripts": {
  "start": "PUBLIC_URL=/ react-scripts start",
  // 其他脚本保持不变
}

4. 验证打包与部署流程 #

• 执行npm run build后，检查build/index.html中的资源引用路径，确认是否为/space-tourism-website/xxx.js这类正确的子路径。
• 重新运行npm run deploy，部署完成后打开开发者工具（F12），查看Console和Network标签，排查是否存在资源加载失败的报错。

5. 检查组件与路由匹配 #

• 确认根路径/对应的组件配置正确（如<Route path="/" element={<Home />} />），确保默认路由能正常渲染。
• 通过开发者工具Elements标签检查组件是否存在但被CSS样式隐藏（如display: none）。

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