React+Vite部署GitHub Pages后图片无法加载问题求助

1. 配置Vite的base路径 #

GitHub Pages部署项目仓库时，网站根路径并非/，而是/你的仓库名称/。必须在vite.config.js中指定正确的base值：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  base: '/your-repo-name/' // 替换为你的GitHub仓库实际名称
})

如果是用户主页仓库（如username.github.io），base可直接设为'/'。

2. 修正图片路径写法 #

public文件夹下的资源，Vite会直接复制到dist根目录，引用时需注意：

• 推荐结合import.meta.env.BASE_URL动态拼接路径，适配本地和部署环境：

  const ImageCard = ({ imgName }) => {
    const imgUrl = `${import.meta.env.BASE_URL}${imgName}`
    return <img src={imgUrl} alt="内容图片" />
  }
  

• 禁止使用相对路径（如../public/xxx.png）或带public前缀的路径（如/public/xxx.png）。

3. 验证props传递的路径正确性 #

确保父组件传递的图片路径是public文件夹下的相对文件名，而非带前缀的错误路径：

// 正确写法
<ImageCard imgName="banner.jpg" />

// 错误写法（避免）
<ImageCard imgName="/public/banner.jpg" />
<ImageCard imgName="src/public/banner.jpg" />

4. 检查构建产物与部署设置 #

• 执行npm run build后，打开dist文件夹，确认图片文件是否在根目录下（与index.html同级）；
• 查看dist/index.html中的图片src属性，确认路径是否包含正确的仓库名前缀；
• 进入GitHub仓库的Settings → Pages页面，确认部署来源为gh-pages分支（或指定dist文件夹），等待部署完成后刷新页面（可强制清除浏览器缓存）。

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