将Create-React-App部署至GitHub Pages遇路由404问题求助

先搞懂为什么会出现404：HTML5 pushState路由的限制 #

你遇到的核心问题是GitHub Pages作为静态文件托管服务，不支持HTML5的pushState路由机制。我给你拆解一下：

平时我们用React Router的BrowserRouter时，它依赖HTML5的history.pushState API来创建干净的URL，比如/ToiletInfo或者/Location。这种方式下，用户在页面内跳转时，浏览器只是更新URL，不会向服务器发送新请求——React路由会在客户端自行处理路径匹配。

但如果用户直接在地址栏输入yourusername.github.io/your-repo/ToiletInfo，或者刷新这个页面，情况就变了：浏览器会向GitHub Pages服务器发送请求，要求获取/your-repo/ToiletInfo这个文件。但你的项目打包后只有一个index.html和静态资源文件，服务器根本找不到这个路径对应的文件，所以就返回404错误。

简单说：GitHub Pages没有配置重写规则，不知道要把所有路由请求都转发到index.html让React路由在客户端处理，这是静态托管服务的普遍限制。

你的代码已经选对了方向：HashRouter的作用 #

看你的代码，你已经使用了HashRouter，这其实就是解决该问题的标准方案！HashRouter会把路由信息放在URL的哈希部分（比如/#/ToiletInfo），而浏览器向服务器发送请求时，哈希部分不会被传递——也就是说，不管用户访问的是/#/还是/#/ToiletInfo，服务器只会收到yourusername.github.io/your-repo/的请求，返回index.html，之后React路由再根据哈希部分匹配对应的页面。

那为什么你还是遇到404？大概率是这几个细节没做好：

1. 必须配置homepage字段

在项目根目录的package.json里，一定要添加homepage字段，值为你的GitHub Pages访问地址：

{
  "homepage": "https://你的GitHub用户名.github.io/你的仓库名/"
}

如果是个人站点（仓库名是你的GitHub用户名.github.io），则写：

{
  "homepage": "https://你的GitHub用户名.github.io/"
}

这个配置会让Create React App打包时，正确生成静态资源的路径，避免资源加载失败或路由跳转异常。

2. 用正确的方式部署

推荐使用gh-pages工具来部署，步骤如下：

• 安装依赖：

  npm install --save gh-pages
  

• 在package.json的scripts中添加两个命令：

  "scripts": {
    "predeploy": "npm run build",
    "deploy": "gh-pages -d build"
  }
  

• 运行部署命令：

  npm run deploy
  

这个工具会自动把build文件夹的内容推送到GitHub仓库的gh-pages分支，GitHub Pages会自动从该分支拉取内容。

3. 访问时用正确的URL

部署完成后，你需要访问带哈希的路径：比如https://你的GitHub用户名.github.io/你的仓库名/#/ToiletInfo，而不是直接访问https://你的GitHub用户名.github.io/你的仓库名/ToiletInfo——后者还是会触发服务器请求，导致404。

额外：如果想使用干净的URL怎么办？ #

如果你非常想要不带哈希的干净URL，需要使用支持自定义服务器配置的托管服务（比如Vercel、Netlify），它们可以配置重写规则，把所有请求都转发到index.html。但GitHub Pages本身不支持这个，所以只能用HashRouter方案。

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