ReactJS + Vite项目执行npm run build后dist缺失assets内图片求助

问题根源 #

favicon能被正常打包，是因为它在index.html里直接引入，Vite会自动抓取这类资源；其他图片没被打包，核心原因是资源引用方式不符合Vite的静态资源处理规则，导致构建时Vite没识别到这些图片，自然不会将它们打包到dist目录。另外浏览器请求返回200却只显示alt文本，大概率是服务器把不存在的图片请求重定向到了首页（返回的是HTML页面而非图片），所以状态码显示200但实际资源不对。

分步解决 #

1. 修正组件内的图片引用方式 #

Vite对本地静态资源的引用有明确要求，不能直接写字符串路径：

• 错误示例（Vite构建时无法识别，不会打包图片）：

  <img src="../assets/photo.jpg" alt="示例图" />
  

• 正确写法1：通过import引入

  import Photo from '../assets/photo.jpg'
  <img src={Photo} alt="示例图" />
  

• 正确写法2：用new URL()生成路径

  <img src={new URL('../assets/photo.jpg', import.meta.url).href} alt="示例图" />
  

• CSS中的背景图引用，只要路径是相对于CSS文件的正确相对路径，Vite会自动处理：

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

2. 配置Vite识别所有图片格式 #

打开vite.config.js，添加assetsInclude配置，确保所有图片格式都被Vite识别为静态资源：

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

export default defineConfig({
  plugins: [react()],
  assetsInclude: ['**/*.png', '**/*.jpg', '**/*.jpeg', '**/*.gif', '**/*.webp']
})

3. 确认dist目录的资源情况 #

执行npm run build后，检查dist/assets目录下是否存在带哈希后缀的图片文件（比如photo.hash.jpg）。如果没有，说明Vite还是没识别到图片引用，回到第一步检查引用方式是否正确。

4. 处理路径匹配问题 #

如果dist里有图片但预览/部署后不显示：

• 若部署在cPanel的子目录下（比如https://你的域名.com/项目子目录/），需要在vite.config.js中配置base：

  export default defineConfig({
    plugins: [react()],
    base: '/项目子目录/' // 替换为你的实际子目录路径
  })
  

• 检查浏览器控制台的图片请求路径，确认和dist里的实际文件路径一致。

5. cPanel部署额外注意事项 #

• 把dist目录下的所有文件上传到cPanel的public_html（或对应子目录），不要只上传部分文件。
• 检查cPanel的.htaccess配置，避免将图片请求重定向到首页（这会导致请求返回200但实际是HTML页面，从而显示alt文本）。
• 清理浏览器缓存后再测试，避免缓存旧的错误路径。

内容的提问来源于stack exchange，提问作者Joao Hugo Leda