Vite项目中的SVG雪碧图

在当前前端开发过程中，图标管理痛点问题解决办法：

1、字体图标（如iconfont）虽然方便，但在高清屏幕下容易模糊，且颜色单一；

2、而直接使用<img>加载多个SVG文件又会带来大量HTTP请求。

3、SVG雪碧图结合了两者的优点：既能保持矢量清晰度，又能合并请求，还可以通过CSS灵活控制颜色。

4、以下介绍如何在Vite项目中使用vite-plugin-svg-icons插件，优雅地实现SVG雪碧图。

什么是SVG雪碧图？

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

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

xml

ini 复制代码

<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>

然后在页面中引用：

html

xml 复制代码

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

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

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

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

原理简述

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

快速上手

1. 安装插件

在Vite项目根目录执行：

bash

csharp 复制代码

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

2. 配置 vite.config.js

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

javascript

php 复制代码

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"/>
      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）中添加一行特殊的导入语句，这行代码会触发插件的运行时逻辑，将雪碧图注入到页面中。

javascript

javascript 复制代码

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文件：

vue

xml 复制代码

<!-- src/components/SvgIcon.vue -->
<template>
  <svg
    aria-hidden="true"
    :class="['svg-icon', $attrs.class]"
    :style="customStyle"
  >
    <use :xlink:href="iconName" />
  </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. 全局注册组件（可选）

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

javascript

javascript 复制代码

// 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组件中：

vue

xml 复制代码

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

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

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

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

html

bash 复制代码

<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控制颜色：

javascript

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覆盖：

css

arduino 复制代码

.svg-icon {
  fill: currentColor;
}

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

参考资料：

vite-plugin-svg-icons GitHub仓库

SVG symbols 规范