部署React站点至Github Pages等平台出现空白页求助

1. 路由模式不兼容（最易踩坑） #

如果你的项目用了React Router，默认的BrowserRouter依赖服务器的路由重定向配置，静态托管平台（Github Pages、Netlify、Vercel）默认不支持这种模式，会导致首页加载异常或子路由404：

• 快速解决：将BrowserRouter替换为HashRouter；
• 保留BrowserRouter的话，需在平台配置重定向：
  • Github Pages：在public目录下新建404.html，内容完全复制index.html；
  • Netlify：根目录新建_redirects文件，写入规则：/* /index.html 200；
  • Vercel：根目录新建vercel.json，配置：

    {
      "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
    }
    

2. Homepage字段配置错误 #

检查package.json里的homepage：

• 你的仓库是用户主页仓库（tosha5252.github.io），正确配置应为"."或"https://tosha5252.github.io"；
• 如果是普通项目仓库（如username/repo）才需要设为"/repo-name"；
• 配置错误会导致静态资源路径失效，打开浏览器控制台（F12）的Network标签，能看到404的js/css文件。

3. 构建产物的资源路径问题 #

执行npm run build后，查看build/index.html里的资源引入路径：

• 如果路径是绝对路径（如/static/js/main.xxx.js），非根域名部署时会找不到资源；
• 解决：确保homepage配置正确，或手动修改index.html，把资源路径开头的/去掉，改为相对路径（如static/js/main.xxx.js）；
• 自定义Webpack配置的话，可设置publicPath: "./"。

4. 代码中的硬编码路径或环境变量问题 #

检查代码里的硬编码路径：

• 比如axios的baseURL写死了http://localhost:3000，或图片资源用了绝对路径/assets/img.png；
• 解决：改用相对路径，或通过.env.production设置生产环境变量，比如：

  REACT_APP_API_URL="/api"
  

  代码里用process.env.REACT_APP_API_URL引用。

5. 查看浏览器控制台的错误提示 #

打开F12切换到Console标签，直接定位问题：

• 出现ReferenceError：可能是依赖未正确打包、代码存在未定义变量；
• 出现404：回到资源路径或homepage配置排查；
• 出现CORS错误：检查API请求的跨域配置。

针对你的仓库的具体建议 #

你的仓库是Github用户主页仓库，额外确认两点：

1. 部署时将build文件夹的内容推到main分支（用户主页仓库默认用main分支部署）；
2. 如果用了gh-pages包部署，需确保package.json的scripts里有"deploy": "gh-pages -d build"，且推送到gh-pages分支后，在仓库设置里将部署分支改为gh-pages。

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