React应用部署GitHub Pages及本地运行时URL异常求助

1. 本地URL自动追加仓库名的原因与修复 #

package.json中的homepage字段会让Create React App自动设置应用的基础路径，所以本地运行时会自动追加/my-portfolio。如果想本地开发时使用根路径，有两种方式：

• 开发阶段临时将homepage改为"/"，部署前再改回GitHub Pages的完整地址；
• 启动开发服务时通过环境变量覆盖：PUBLIC_URL=/ npm start，无需修改package.json。

2. 部署后404错误的修复 #

使用createBrowserRouter时，必须配置basename匹配GitHub Pages的仓库路径，否则路由无法正确匹配：

const router = createBrowserRouter([
  {
    path: "/",
    element: <RootElement />,
    errorElement: <Error />,
    children: [
      { index: true, element: <Home /> },
      { path: "about-me", element: <About /> },
      { path: "work-history", element: <WorkHistory /> },
      { path: "projects", element: <Projects /> },
      { path: "skills", element: <Skills /> },
      { path: "blog", element: <Blog /> },
      { path: "contact", element: <Contact /> },
    ],
  },
], {
  basename: "/my-portfolio" // 添加上仓库名作为路由基础路径
});

另外，GitHub Pages静态托管无法直接处理HTML5 History模式的路由刷新，需要在项目public目录下创建404.html，内容与public/index.html完全一致。这样用户刷新子路由时，GitHub Pages会返回404.html，React Router就能正确接管路由逻辑。

3. 确认部署命令正确性 #

确保package.json中的部署脚本配置正确：

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

执行npm run deploy即可完成部署。

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