为什么Vite动态加载图片报错? 动态资源引入的那些事儿

在前端开发中，动态引入图片等静态资源是很常见的需求。但从 Vue2+Webpack 迁移到 Vue3+Vite 后，很多开发者会发现原本的动态资源引入方式不好使了，控制台各种 404 错误让人头疼。

今天我们就来详细对比一下这两种环境下动态资源引入的差异，以及背后的原因。

一、Vue2+Webpack 中的动态引入方式

在 Vue2 项目中，我们通常使用 Webpack 作为构建工具，动态引入图片资源的方式比较直观： 要么直接动态拼接url路径，要么写一个计算属性

直接动态拼接url路径：

    <!-- 方式1：直接拼接路径 -->
    <img :src="require(`@/assets/images/${imageName}.png`)" alt="动态图片">

写一个计算属性：

<template>
    <!-- 方式2：使用计算属性 -->
    <img :src="imageUrl" alt="计算属性图片">
</template>

<script>
export default {
  computed: {
    imageUrl() {
      // 根据不同类型返回不同图片
      const imgMap = {
        success: require('@/assets/images/success.png'),
        error: require('@/assets/images/error.png'),
        warning: require('@/assets/images/warning.png')
      }
      return imgMap[this.type] || imgMap.success
    }
  }
}
</script>

Webpack 之所以支持这种写法，是因为它在打包时会对 require() 进行静态分析，即使路径中包含变量，也能尝试识别可能的资源路径。

二、Vue3+Vite 中的动态引入方式

迁移到 Vite 后，上面的写法就失效了。Vite 基于 ES 模块系统，处理静态资源的方式与 Webpack 有很大不同。

在 Vite 中，正确的动态引入方式主要有两种：

方式 1：使用 new URL ()

JavaScript 写法

<template>
  <div>
    <img :src="imageUrl" alt="Vite动态图片">
  </div>
</template>

<script setup>
import { computed, ref } from 'vue'

const type = ref('success')

const imageUrl = computed(() => {
  const imgMap = {
    success: '/src/assets/images/success.png',
    error: '/src/assets/images/error.png',
    warning: '/src/assets/images/warning.png'
  }
  
  const imgPath = imgMap[type.value] || imgMap.success
  // Vite 特有的资源引入方式
  return new URL(imgPath, import.meta.url).href
})
</script>

TypeScript 写法

<template>
  <div>
    <img :src="imageUrl" alt="Vite动态图片">
  </div>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue'

// 定义类型，限制可能的值
type ImageType = 'success' | 'error' | 'warning'

const type = ref<ImageType>('success')

const imageUrl = computed(() => {
  // 类型安全的映射关系
  const imgMap: Record<ImageType, string> = {
    success: '/src/assets/images/success.png',
    error: '/src/assets/images/error.png',
    warning: '/src/assets/images/warning.png'
  }
  
  const imgPath = imgMap[type.value]
  // 明确指定返回类型为string
  return new URL(imgPath, import.meta.url).href as string
})
</script>

方式 2：使用 import.meta.glob 批量导入

当需要引入多个资源时，可以使用 Vite 提供的 import.meta.glob 方法批量导入：

JavaScript 写法

<template>
  <div>
    <img :src="imageUrl" alt="批量导入图片">
  </div>
</template>

<script setup>
import { computed, ref } from 'vue'

// 批量导入 assets/images 目录下的所有 png 图片
const imageModules = import.meta.glob('/src/assets/images/*.png', { eager: true })

const type = ref('success')

const imageUrl = computed(() => {
  const imgMap = {
    success: '/src/assets/images/success.png',
    error: '/src/assets/images/error.png',
    warning: '/src/assets/images/warning.png'
  }
  
  const imgPath = imgMap[type.value] || imgMap.success
  // 从批量导入的模块中获取图片
  return imageModules[imgPath]?.default
})
</script>

TypeScript 写法

<template>
  <div>
    <img :src="imageUrl" alt="批量导入图片">
  </div>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue'

// 定义类型
type ImageType = 'success' | 'error' | 'warning'

// 批量导入并指定模块类型
const imageModules = import.meta.glob<{ default: string }>('/src/assets/images/*.png', { 
  eager: true 
})

const type = ref<ImageType>('success')

const imageUrl = computed<string>(() => {
  // 类型安全的映射
  const imgMap: Record<ImageType, string> = {
    success: '/src/assets/images/success.png',
    error: '/src/assets/images/error.png',
    warning: '/src/assets/images/warning.png'
  }
  
  const imgPath = imgMap[type.value]
  // 确保获取到正确的图片路径
  return imageModules[imgPath]?.default || ''
})
</script>

三、核心差异对比

特性	Vue2+Webpack	Vue3+Vite
路径别名	支持 @ 表示 src 目录	不推荐在 JS 中使用 @，建议使用绝对路径
资源处理	通过 require() 引入	通过 new URL() 或 import.meta.glob
静态分析	会尝试解析 require() 中的变量	必须明确指定路径，否则无法静态分析
构建时处理	打包时统一处理	开发环境直接请求，生产环境预构建
动态路径支持	有限支持路径变量	不支持完全动态的路径，需预先定义可能的路径

四、为什么会有这些差异？

根本原因在于 Webpack 和 Vite 的构建理念不同：

1. Webpack 是 bundler（打包器） ：

   • 会将所有资源打包成一个或多个 bundle
   • 编译时会递归解析所有依赖，包括 require() 调用
   • 对动态路径有一定的猜测能力

2. Vite 是 dev server + bundler：

   • 开发环境使用原生 ES 模块，不打包
   • 生产环境使用 Rollup 打包
   • 严格基于 ESM 规范，只能处理静态可分析的导入
   • 利用浏览器原生支持的模块系统，启动速度更快

以上基础方式在图片数量较少时可以工作，但当组件中有多处图片需要根据同一 type 切换时，就会显得冗余且难以维护。

五、进阶场景：同一组件多图片依赖同一变量

假设我们在同一组件有多个图片依赖同一变量，都要进行图片替换，比如一个状态卡片组件，需要根据 type 变量同时切换图标、背景图和徽章图片，这时就需要更系统的方案。

最佳实践：集中式资源映射配置

推荐创建一个集中式的资源映射中心 ，将所有与 type 相关的图片资源统一管理：

<template>
//假设有4张图片
  ..
       <img :src="imageResources.icon" :alt="imageResources.alt" class="icon">
     
 ......<img :src="imageResources.badge" :alt="`${type} badge`" class="badge">
      ...
 ..... <img :src="imageResources.background" :alt="`${type} background`" class="background">
      .....
     .. <img :src="imageResources.alt" :alt="`${type} alt`" class="alt">
       
</template>

<script setup lang="ts">
import { ref, computed } from 'vue';

// 1. 接收或定义type变量
const type = ref('success'); // 可能的值：success, warning, error, info
const title = ref('操作成功');
const description = ref('您的请求已成功处理完成');

// 2. 批量导入所有可能用到的图片
const imageModules = import.meta.glob('/src/assets/status/*.png', {
  eager: true,
  import: 'default'
});

// 3. 核心：创建资源映射配置中心
const resourceConfig = {
  success: {
    icon: imageModules['/src/assets/status/success-icon.png'],
    background: imageModules['/src/assets/status/success-bg.png'],
    badge: imageModules['/src/assets/status/success-badge.png'],
    alt: '成功状态图标'
  },
  warning: {
    icon: imageModules['/src/assets/status/warning-icon.png'],
    background: imageModules['/src/assets/status/warning-bg.png'],
    badge: imageModules['/src/assets/status/warning-badge.png'],
    alt: '警告状态图标'
  },
  error: {
    icon: imageModules['/src/assets/status/error-icon.png'],
    background: imageModules['/src/assets/status/error-bg.png'],
    badge: imageModules['/src/assets/status/error-badge.png'],
    alt: '错误状态图标'
  },
  info: {
    icon: imageModules['/src/assets/status/info-icon.png'],
    background: imageModules['/src/assets/status/info-bg.png'],
    badge: imageModules['/src/assets/status/info-badge.png'],
    alt: '信息状态图标'
  }
};

// 4. 根据当前type获取对应的资源集合
const imageResources = computed(() => {
  // 提供默认值，防止type值异常
  return resourceConfig[type.value as keyof typeof resourceConfig] || resourceConfig.success;
});
</script>

相当于套了两层，这样这个type下所有的图片被整合到一块儿了，方便改动

这种方案的优势解析

1. 集中管理，一次修改到处生效

   • 所有与type相关的图片资源都集中在resourceConfig中
   • 当需要更换某一状态的图片时，只需修改一处配置
   • 新增状态类型时，只需在配置中添加一组新的资源

2. 类型安全，减少错误

   • 结合 TypeScript 的类型检查，避免拼写错误
   • 提供默认值 fallback，防止type值异常导致的图片丢失

3. 模板简洁，逻辑与视图分离

   • 模板中只需直接使用imageResources的属性
   • 避免在模板中写复杂的条件判断或计算逻辑

4. 性能优化

   • 一次性批量导入所有图片，避免多次网络请求
   • 计算属性会缓存结果，不会重复计算

六、扩展：大型项目的进阶方案

当项目规模较大，多个组件都需要根据type切换图片时，可以进一步优化：

1. 创建资源管理工具类

// src/utils/resourceManager.ts
export function createResourceManager<T extends string>(config: Record<T, any>) {
  // 批量导入资源
  const importAll = (requireContext: __WebpackModuleApi.RequireContext) => {
    const modules: Record<string, string> = {};
    requireContext.keys().forEach(key => {
      modules[key] = requireContext(key);
    });
    return modules;
  };
  
  // 获取资源
  const getResource = (type: T) => {
    return config[type] || config[Object.keys(config)[0] as T];
  };
  
  return {
    getResource
  };
}

2. 创建状态资源配置文件

// src/assets/status/resources.ts
import { createResourceManager } from '@/utils/resourceManager';

// 导入所有状态相关图片
const imageModules = import.meta.glob('/src/assets/status/*.png', {
  eager: true,
  import: 'default'
});

// 定义状态资源配置
const statusResources = {
  success: {
    icon: imageModules['/src/assets/status/success-icon.png'],
    background: imageModules['/src/assets/status/success-bg.png'],
    badge: imageModules['/src/assets/status/success-badge.png'],
  },
  // ... 其他状态
};

// 创建资源管理器
export const statusResourceManager = createResourceManager(statusResources);

3. 在组件中使用

<script setup>
import { statusResourceManager } from '@/assets/status/resources';
import { ref, computed } from 'vue';

const type = ref('success');
const imageResources = computed(() => {
  return statusResourceManager.getResource(type.value);
});
</script>

这种方案将资源管理与组件完全分离，适合在多个组件间共享相同的资源切换逻辑。

七、总结

同一组件中多处图片依赖同一type变量时，最佳实践的核心原则是：

1. 集中配置：将所有相关资源统一管理，避免分散

2. 类型安全：利用 TypeScript 确保配置的完整性和正确性

3. 逻辑封装：将资源获取逻辑封装，保持模板简洁

4. 易于扩展：新增类型时只需添加配置，无需修改组件逻辑

这种方式不仅能让代码更清晰、更易于维护，还能减少因路径错误、类型遗漏等导致的 bug，特别适合中大型项目。

你在项目中是如何处理类似场景的？欢迎在评论区分享你的经验！

分享

八、最佳实践建议

1. 路径规范：

   • 统一使用绝对路径（从 /src 开始）
   • 避免在路径中使用过多变量拼接

2. 图片管理：

   • 少量图片：使用 new URL() 方式
   • 大量图片：使用 import.meta.glob 批量导入
   • 考虑将常用图片路径集中管理，方便维护

3. 迁移注意事项：

   • 从 Webpack 迁移到 Vite 时，务必检查所有动态资源引入
   • 注意开发环境和生产环境的路径差异
   • 利用 TypeScript 类型定义避免路径拼写错误

总结

从 Vue2+Webpack 到 Vue3+Vite，动态资源引入方式的变化，反映了前端构建工具从「打包优先」到「原生 ESM 优先」的理念转变。虽然初期可能需要适应新的写法，但 Vite 带来的开发体验提升是值得的。

理解这些差异背后的原因，不仅能帮助我们更好地使用这些工具，也能加深对前端工程化的理解。

希望本文能帮助大家顺利解决动态资源引入的问题，如果你有其他好的实践经验，欢迎在评论区分享！