React部署GitHub Pages绑定自定义域名出现404报错求助

报错现象 #

未配置自定义域名时项目可正常访问，绑定自定义域名后所有静态资源加载失败，控制台报错：

Failed to load resource: the server responded with a status of 404 (Not Found)

报错截图：

问题原因 #

未绑定自定义域名时，GitHub Pages 站点访问路径为https://<GitHub用户名>.github.io/<仓库名>/，构建工具默认会给所有静态资源拼接/<仓库名>/的路径前缀；绑定自定义域名后站点根路径变为https://你的自定义域名/，旧的带仓库名的资源路径不存在，就会触发404。除此之外CNAME文件丢失、路由配置不匹配、DNS缓存也可能导致同类问题。

修复步骤 #

• 修正构建路径配置
  • 若使用Create React App搭建的项目：修改package.json中的homepage字段，去掉原有仓库名后缀，直接填写自定义域名地址：

    {
      "homepage": "https://你的自定义域名"
    }
    

  • 若使用Vite搭建的项目：除了修改上述homepage字段，还要同步修改vite.config.js中的base配置，将原有/<仓库名>/改为根路径：

    export default defineConfig({
      base: '/',
      // 其余原有配置保持不变
    })
    

  修改完成后重新执行构建命令，将新的产物推送到GitHub Pages对应的部署分支。
• 确保CNAME文件持久化
  自定义域名配置生效后，GitHub Pages会在部署分支根目录生成内容为你的纯域名（不带http/https前缀）的CNAME文件。如果每次构建会清空产物目录，需要把CNAME文件放到项目的public目录下，构建时该目录文件会被直接复制到产物根目录，避免部署时CNAME被覆盖导致域名配置失效。
• 修正路由配置
  如果项目使用react-router-dom的BrowserRouter，绑定自定义域名后不需要再带仓库名前缀，将basename属性设置为/即可：

  import { BrowserRouter } from 'react-router-dom'
  
  ReactDOM.createRoot(document.getElementById('root')).render(
    <BrowserRouter basename="/">
      <App />
    </BrowserRouter>
  )
  

  如果不想额外配置GitHub Pages的SPA重定向规则，也可以直接替换为HashRouter，路径哈希段不会触发服务端资源请求，不会出现404问题。
• 缓存校验
  所有配置修改部署完成后，使用Ctrl+F5（Windows）/Cmd+Shift+R（Mac）强制刷新浏览器清理本地缓存，同时到GitHub仓库的Settings > Pages页面确认自定义域名状态显示为DNS校验通过，等待解析完全生效即可。

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