Vite配置base路径部署Github Pages报错及图片加载问题

先解决加base后网站空白的问题 #

• 确保vite.config.ts里的base值和Github仓库名称完全一致（大小写也要匹配），比如仓库名为my-react-demo，配置应为：

  // vite.config.ts
  export default defineConfig({
    base: "/my-react-demo/",
    // 其他配置...
  })
  

• 如果项目用了React Router，必须给BrowserRouter添加basename属性，和base值保持一致，否则路由匹配失败会导致页面空白：

  import { BrowserRouter } from "react-router-dom";
  
  function App() {
    return (
      <BrowserRouter basename="/my-react-demo/">
        {/* 路由内容 */}
      </BrowserRouter>
    );
  }
  

无需大量import的图片加载方案 #

针对public目录下的图片 #

直接结合Vite的环境变量import.meta.env.BASE_URL写路径，这个变量会自动替换成你配置的base值：

// 假设public目录下有tree.jpg
<img src={`${import.meta.env.BASE_URL}tree.jpg`} alt="tree" />

针对src/assets目录下的图片 #

• 写法和public目录类似，路径加上assets前缀即可：

  <img src={`${import.meta.env.BASE_URL}assets/tree.jpg`} alt="tree" />
  

• CSS背景图片也用同样的方式：

  .bg-tree {
    background-image: url(${import.meta.env.BASE_URL}assets/tree.jpg);
  }
  

  Vite默认会把src/assets里的资源打包到dist/assets目录下，所以这个路径是有效的。

验证打包结果 #

执行npm run build后，打开dist目录下的index.html，检查资源引用路径是否正确，比如图片路径应该是/my-react-demo/assets/tree.jpg这样的格式，确保和base配置一致。

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