Vite(React)项目构建后dist/assets无图片，GitHub部署页面不显示图片

排查与解决步骤 #

• 检查图片引入方式
  • 别直接用字符串写相对路径（比如src="../assets/img.png"），Vite需要用规范方式引入：

    // 方式1：import引入
    import img from '../assets/img.png';
    <img src={img} alt="示例图" />
    
    // 方式2：new URL()构造路径
    <img src={new URL('../assets/img.png', import.meta.url).href} alt="示例图" />
    

  • CSS背景图要保证路径写法正确：

    .bg-box {
      background-image: url('../assets/bg.png');
    }
    

• 检查Vite配置
  • 确认vite.config.js里的assetsInclude包含了你用的图片格式，避免漏打包：

    import { defineConfig } from 'vite';
    import react from '@vitejs/plugin-react';
    
    export default defineConfig({
      plugins: [react()],
      base: '/你的GitHub仓库名/', // 确保和Pages部署路径一致
      assetsInclude: ['**/*.png', '**/*.jpg', '**/*.webp', '**/*.svg'], // 覆盖默认规则，包含所有需要的图片格式
    });
    

• 核对文件路径细节
  • 确认图片确实在代码引用的目录下，文件名大小写要和代码里的完全匹配（比如Logo.png和logo.png会被Vite判定为不同文件）
• 清理缓存重构建
  • 删除node_modules/.vite缓存文件夹，再执行npm run build，避免缓存导致的打包异常

GitHub部署额外检查 #

• 确认GitHub Pages的部署源设置为dist文件夹
• 若用自定义域名，检查CNAME文件是否配置正确，避免路径跳转异常

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