React多页网站部署Github Pages后子页面URL正确却报404

问题核心 #

Github Pages是静态文件服务器，不支持单页应用（SPA）的History模式路由。直接访问子路由时，服务器会尝试查找对应路径的静态文件，找不到就返回404；而本地开发环境的dev-server默认配置了回退到index.html，所以不会出现该问题。

具体修复步骤 #

1. 替换原生<a>标签为React Router的<Link>组件 #

原生<a>标签会触发页面硬刷新，直接请求服务器对应路径，导致404。改用React Router的<Link>实现客户端路由跳转：

修改Home.js：

// 先导入Link组件
import { Link } from 'react-router-dom';

<div>
  <Link to='/project'>
    <img alt='Project 1' src={Sunset} />
  </Link>
</div>

注：因为Router已经配置了basename={/${process.env.PUBLIC_URL}}，所以to属性只需写路由相对路径，无需手动拼接/my-website前缀。

2. 配置package.json的homepage字段 #

确保项目根目录的package.json中添加正确的homepage，让process.env.PUBLIC_URL能正确获取仓库路径：

"homepage": "https://myname.github.io/my-website"

或者使用相对路径适配任意部署环境：

"homepage": "./"

3. 添加404.html解决直接访问子路由的404问题 #

在项目的public目录下创建404.html，完全复制index.html的内容。这样当Github Pages服务器找不到对应路径的文件时，会返回404.html，React Router就能接管并解析当前URL，渲染对应页面。

4. 重新部署项目 #

执行部署命令（通常是npm run deploy，需提前配置部署脚本），将修改后的代码推送到Github Pages。

验证修复 #

部署完成后：

• 从主页点击<Link>跳转子页面，应正常加载
• 直接在地址栏输入子路由URL（如https://myname.github.io/my-website/project），应正常渲染对应页面，不再返回404

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