使用Vite+React部署GitHub Pages时的绝对路径渲染问题

核心配置与构建验证 #

• 确认vite.config.ts的base配置在生产构建时生效：你的配置中base: '/cv_wizardy/'是正确的，但必须确保执行生产模式打包（运行npm run build，对应package.json中"build": "tsc && vite build"的命令），否则base配置可能不会被正确注入到构建产物中。
• 打包后检查dist目录下的index.html，确认JS/CSS资源的引用路径是否以/cv_wizardy/开头，比如应该是<script type="module" src="/cv_wizardy/assets/index.xxxx.js"></script>，如果不是，排查是否有其他配置覆盖了base，或打包命令是否存在异常。

静态资源引用规范 #

• 项目中所有静态资源（图片、字体等）禁止使用根路径/开头的绝对引用，改用相对路径或借助Vite内置环境变量拼接：

  // 方式1：使用相对路径
  <img src="./assets/logo.png" alt="logo" />
  
  // 方式2：用import.meta.env.BASE_URL拼接适配base配置
  const imagePath = `${import.meta.env.BASE_URL}assets/logo.png`;
  <img src={imagePath} alt="logo" />
  
  // 方式3：使用别名导入（已配置@的情况下，Vite会自动处理路径）
  import logo from '@/assets/logo.png';
  <img src={logo} alt="logo" />
  

路由适配（若使用React Router） #

• 如果你用了React Router，需要给BrowserRouter添加basename属性，确保路由跳转与子路径匹配：

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

仓库配置确认 #

• 确保GitHub Pages的仓库设置中，部署源指向正确的分支（通常是gh-pages分支），且仓库名称与base配置的子路径完全一致（注意GitHub路径区分大小写）。

内容的提问来源于stack exchange，提问作者Adel Ali Mohamed