Vite项目中SVG雪碧图的实现

更新时间：2026年03月05日 09:03:36 作者：NB_R

本文介绍了SVG雪碧图在前端开发中的应用,并提供了在Vite项目中使用vite-plugin-svg-icons插件的详细步骤,文中通过示例代码介绍的非常详细,需要的朋友们下面随着小编来一起学习学习吧

什么是SVG雪碧图？

SVG雪碧图的核心思想是将多个SVG图标合并到一个文件中，每个图标用一个<symbol>元素定义，并赋予唯一的id。使用时，通过<use xlink:href="#icon-id">来引用对应的图标。这样做不仅减少了网络请求，而且所有图标都以矢量形式存在，无论放大多少倍都清晰锐利。

一个典型的雪碧图文件结构如下：

<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
  <symbol id="icon-home" viewBox="0 0 24 24">
    <path d="..."/>
  </symbol>
  <symbol id="icon-user" viewBox="0 0 24 24">
    <path d="..."/>
  </symbol>
</svg>

然后在页面中引用：

<svg><use xlink:href="#icon-home" rel="external nofollow" /></svg>

为什么选择 vite-plugin-svg-icons？

手动维护雪碧图不仅繁琐，而且容易出错。vite-plugin-svg-icons是专为Vite设计的插件，它可以：

自动扫描指定文件夹中的所有SVG文件，并生成雪碧图；
开发环境实时更新，新增或修改图标无需重启服务；
支持SVGO优化，压缩图标体积；
可自定义symbolId格式，方便在代码中引用；
与Vite完美集成，无需额外配置loader。

原理简述

插件的核心逻辑是在构建时（或开发服务器启动时）读取iconDirs目录下的所有SVG文件，将它们转换为<symbol>片段，并组合成一个大的<svg>元素。在开发模式下，这个<svg>会通过一个虚拟模块动态注入到DOM中；生产构建时，则会将雪碧图打包到最终的assets目录，并通过入口文件中的注册代码自动注入。

快速上手

1. 安装插件

在Vite项目根目录执行：

npm install -D vite-plugin-svg-icons
# 或
yarn add -D vite-plugin-svg-icons

2. 配置 vite.config.js

打开vite.config.js，引入插件并配置：

import { defineConfig } from 'vite'
import { createSvgIconsPlugin } from 'vite-plugin-svg-icons'
import path from 'path'

export default defineConfig({
  plugins: [
    // ... 其他插件
    createSvgIconsPlugin({
      // 指定要缓存的图标文件夹，即存放SVG文件的目录
      iconDirs: [path.resolve(process.cwd(), 'src/assets/icons')],
      // 指定symbolId格式，这里设置为 'icon-文件名'，后面使用 <use href="#icon-xxx" rel="external nofollow" />
      symbolId: 'icon-[name]',
      // 可选：SVGO压缩配置
      svgoOptions: {
        plugins: [
          // 例如，移除所有图标的fill属性，以便通过CSS控制颜色
          { name: 'removeAttrs', params: { attrs: 'fill' } }
        ]
      }
    })
  ]
})

注意：iconDirs路径必须正确指向你的图标文件夹。建议将所有SVG图标存放在src/assets/icons下。

3. 在入口文件中注册插件

在项目的入口文件（如src/main.js或src/main.ts）中添加一行特殊的导入语句，这行代码会触发插件的运行时逻辑，将雪碧图注入到页面中。

import { createApp } from 'vue'
import App from './App.vue'
import 'virtual:svg-icons-register'  // 关键！注入雪碧图

createApp(App).mount('#app')

virtual:svg-icons-register是一个由插件提供的虚拟模块，它会在DOM中创建一个隐藏的<svg>元素，包含所有图标的<symbol>定义。

4. 封装一个通用的 SvgIcon 组件

为了使用方便，我们通常封装一个可复用的图标组件。以Vue 3为例，创建一个SvgIcon.vue文件：

<!-- src/components/SvgIcon.vue -->
<template>
  <svg
    aria-hidden="true"
    :class="['svg-icon', $attrs.class]"
    :style="customStyle"
  >
    <use :xlink:href="iconName" rel="external nofollow"  />
  </svg>
</template>

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

const props = defineProps({
  name: {
    type: String,
    required: true
  },
  color: {
    type: String,
    default: 'currentColor'
  },
  size: {
    type: [Number, String],
    default: '1em'
  }
})

const iconName = computed(() => `#icon-${props.name}`)
const customStyle = computed(() => ({
  width: typeof props.size === 'number' ? `${props.size}px` : props.size,
  height: typeof props.size === 'number' ? `${props.size}px` : props.size,
  color: props.color
}))
</script>

<style scoped>
.svg-icon {
  vertical-align: -0.15em;  /* 与文字对齐 */
  fill: currentColor;        /* 继承颜色 */
  overflow: hidden;
}
</style>

5. 全局注册组件（可选）

为了让组件在项目中随处可用，可以在入口文件中全局注册：

// src/main.js
import { createApp } from 'vue'
import App from './App.vue'
import 'virtual:svg-icons-register'
import SvgIcon from '@/components/SvgIcon.vue'

const app = createApp(App)
app.component('SvgIcon', SvgIcon)
app.mount('#app')

6. 在页面中使用图标

现在，只需将SVG文件放入src/assets/icons目录，例如home.svg和user.svg，然后在任意Vue组件中：

<template>
  <div>
    <!-- 基础用法，使用 home.svg 图标，大小1em，颜色默认 -->
    <SvgIcon name="home" />

    <!-- 自定义颜色和大小 -->
    <SvgIcon name="user" color="#ff6b6b" size="32" />

    <!-- 动态绑定 -->
    <SvgIcon :name="isActive ? 'star-filled' : 'star'" />
  </div>
</template>

最终渲染时，插件会自动生成类似下面的DOM结构：

<svg id="__svg__icons__dom__" style="display: none;">
  <symbol id="icon-home" viewBox="...">...</symbol>
  <symbol id="icon-user" viewBox="...">...</symbol>
</svg>

然后<SvgIcon name="home">会生成<use href="#icon-home">，从而显示对应图标。

进阶配置

自定义 symbolId 格式

symbolId选项支持多种占位符：

[name]：文件名（不含扩展名）
[dir]：相对于iconDirs的目录路径
[path]：完整相对路径

例如：symbolId: 'icon-[dir]-[name]'，如果你的文件结构是src/assets/icons/common/logo.svg，生成的id就是icon-common-logo。

SVG 压缩与优化

通过svgoOptions可以自定义SVGO配置。例如，移除fill属性以允许通过CSS控制颜色：

svgoOptions: {
  plugins: [
    { name: 'removeAttrs', params: { attrs: 'fill' } }
  ]
}

你也可以完全自定义SVGO配置，详情参考SVGO文档。

常见问题与解决

1. 图标不显示？

检查iconDirs路径是否正确，确保SVG文件确实存放在该目录下。
确认在入口文件中已导入'virtual:svg-icons-register'。
检查生成的symbolId是否与<use>中的href一致。可以在浏览器开发者工具中查看隐藏的<svg>元素，确认是否有对应的<symbol>存在。

2. 图标颜色无法改变？

SVG文件本身可能自带了fill或stroke属性。可以通过SVGO的removeAttrs插件移除这些属性，或者在封装组件时通过CSS覆盖：

.svg-icon {
  fill: currentColor;
}

同时在vite.config.js中配置removeAttrs插件（如上所示），以确保图标不包含固定颜色。

参考资料：

到此这篇关于Vite项目中SVG雪碧图的实现的文章就介绍到这了,更多相关Vite SVG雪碧图内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

您可能感兴趣的文章:

使用vuex的时候,出现this.$store为undefined问题
这篇文章主要介绍了使用vuex的时候,出现this.$store为undefined问题及解决，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教
2023-06-06
详解vue数据响应式原理之数组
这篇文章主要为大家详细介绍了vue数据响应式原理之数组，文中示例代码介绍的非常详细，具有一定的参考价值，感兴趣的小伙伴们可以参考一下，希望能够给你带来帮助
2022-02-02
一文详解Vue中内存泄漏的场景与预防技巧
即便是功能强大的 Vue.js 也无法完全避免内存泄漏的问题,内存泄漏不仅会影响应用的性能,还可能导致浏览器崩溃,下面我们来看看Vue 中常见的内存泄漏场景以及如何避免这些问题吧
2024-12-12
详解Vue.js组件可复用性的混合(mixin)方式和自定义指令
本篇文章主要介绍了详解Vue.js组件可复用性的混合(mixin)方式和自定义指令，具有一定的参考价值，有兴趣的可以了解一下
2017-09-09
el-table分页多选及回显方式
这篇文章主要介绍了el-table分页多选及回显方式,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐教
2026-01-01
Vue中的局部组件介绍
这篇文章主要介绍了Vue中的局部组件，文章围绕Vue局部组件得相关资料展开内容，需要的的小孩伙伴请参考下面文章的具体介绍，希望对你有所帮助
2021-12-12
Vue3中引入Pinia存储库使用示例详解
这篇文章主要介绍了Vue3中引入Pinia存储库使用,本文给大家介绍的非常详细，对大家的学习或工作具有一定的参考借鉴价值，需要的朋友可以参考下
2023-03-03
Vue父子组件属性传递实现方法详解
这篇文章主要介绍了Vue父子组件属性传递实现方法，我们主要从案例出发，用Vue3的写法写父子组件之间的属性传递，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习吧
2023-02-02
vue实现竖屏滚动公告效果
这篇文章主要为大家详细介绍了vue实现竖屏滚动公告效果，文中示例代码介绍的非常详细，具有一定的参考价值，感兴趣的小伙伴们可以参考一下
2022-04-04
vuejs如何清空表单数据、删除对象中的空属性公共方法
这篇文章主要介绍了vuejs如何清空表单数据、删除对象中的空属性公共方法,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐教
2025-03-03