React项目npm run build部署时动态加载的头像图片无法渲染

DevOps 小满

2026-8-29

问题现象

执行npm run dev启动开发环境时项目运行完全正常，但执行npm run build打包部署后，testimonials数据中的avatar头像图片无法正常渲染。

涉及的Testimonials组件代码如下：

const Testimonials = ({ testimonials }) => {
  return (
    <div id='testimonials' className='mt-20'>
      <div className='text-center mb-8'>
        <p className='text-xs uppercase mb-4 md:text-base'>Testimonials</p>
        <h1 className='text-3xl md:text-5xl font-bold capitalize mb-10'>Read What Other<br />have to Say</h1>
      </div>
      <div className='flex flex-col gap-4 items-center md:flex-row'>
        {testimonials.map(item =>
          <div className='bg-light-gray rounded-3xl p-8 transition-transform duration-300 hover:-translate-y-2'>
            <div className='w-32 h-32 mx-auto mb-4'>
              <img src={item.avatar} alt="Person's avatar" className='rounded-full border' />
            </div>
            <p className='font-bold text-center'>{item.fullName}</p>
            <p className='text-center mt-6'>{item.feedback}</p>
          </div>
        )}
      </div>
    </div>
  )
}

该组件通过props接收testimonials数组，遍历渲染用户评价模块。App.jsx中定义的testimonials初始数组如下：

const testimonials = [
    {
      avatar: '../src/images/avatars/avatar-1.png',
      fullName: 'Andrew Rathore',
      feedback: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc ullamcorper scelerisque mi, in malesuada felis malesuada vel. '
    },
    {
      avatar: '../src/images/avatars/avatar-2.png',
      fullName: 'Vera Duncan',
      feedback: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc ullamcorper scelerisque mi, in malesuada felis malesuada vel. '
    },
    {
      avatar: '../src/images/avatars/avatar-3.png',
      fullName: 'Mark Smith',
      feedback: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc ullamcorper scelerisque mi, in malesuada felis malesuada vel. '
    }
  ];

问题原因

你的预判完全正确。不管是用Vite还是Create React App搭建的React项目，打包时都会对src目录下的资源做统一处理：给文件名加哈希值、全部输出到构建产物的assets目录，不会保留开发阶段的src目录结构。直接在数组里写死源码阶段的相对路径，打包后路径指向的位置根本不存在对应文件，自然加载失败。开发环境下构建工具做了特殊的路径兼容，所以这类路径问题不会暴露，才会出现开发正常、打包后图片加载失败的情况。

解决方案

两种常用方案，优先选择第一种：

方案1：通过import静态导入图片（官方推荐，兼容性最好）
构建工具会自动识别import导入的图片资源，打包时自动替换为最终可访问的正确路径，不需要手动计算路径适配生产环境。只需要修改App.jsx的代码即可：

// 文件顶部先导入所有头像资源，注意路径写当前App.jsx到图片文件的相对路径即可
import avatar1 from './images/avatars/avatar-1.png'
import avatar2 from './images/avatars/avatar-2.png'
import avatar3 from './images/avatars/avatar-3.png'

const testimonials = [
    {
      avatar: avatar1, // 用导入的变量替换原来的路径字符串
      fullName: 'Andrew Rathore',
      feedback: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc ullamcorper scelerisque mi, in malesuada felis malesuada vel. '
    },
    {
      avatar: avatar2,
      fullName: 'Vera Duncan',
      feedback: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc ullamcorper scelerisque mi, in malesuada felis malesuada vel. '
    },
    {
      avatar: avatar3,
      fullName: 'Mark Smith',
      feedback: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc ullamcorper scelerisque mi, in malesuada felis malesuada vel. '
    }
  ];

改完重新执行npm run build，图片就能正常渲染了。

方案2：将图片放到public目录，用绝对路径引入
如果觉得逐个写import太麻烦，可以把存头像的avatars文件夹整个从src/images/下移动到项目根目录的public文件夹中。public目录下的资源打包时会原封不动复制到构建产物根目录，不会被重命名修改路径。此时testimonials里的头像路径要改成以站点根目录开头的绝对路径：

const testimonials = [
    {
      avatar: '/images/avatars/avatar-1.png', // 路径开头加/，不要带public、src前缀
      fullName: 'Andrew Rathore',
      feedback: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc ullamcorper scelerisque mi, in malesuada felis malesuada vel. '
    },
    {
      avatar: '/images/avatars/avatar-2.png',
      fullName: 'Vera Duncan',
      feedback: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc ullamcorper scelerisque mi, in malesuada felis malesuada vel. '
    },
    {
      avatar: '/images/avatars/avatar-3.png',
      fullName: 'Mark Smith',
      feedback: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc ullamcorper scelerisque mi, in malesuada felis malesuada vel. '
    }
  ];

注意：这种写法存在适配问题，如果项目最终不是部署在域名根路径（比如部署在https://xxx.com/demo/这类子路径下），绝对路径会直接查找域名根目录下的文件，导致资源加载失败，没有特殊需求优先使用第一种import方案。

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