在 Vue 3 + Vite 项目中，推荐使用 vite-plugin-svg-icons 管理 SVG 图标，其核心是将图标转为 Symbol 雪碧图并通过 按需引用；需安装插件、规范存放 SVG 文件、配置 vite.config.ts、入口引入 virtual:svg-icons-register、封装 SvgIcon 组件，并注意命名规范与热更新限制。
在 Vue 3 + Vite 项目中，用 vite-plugin-svg-icons 管理 SVG 图标是最主流、最轻量且工程化程度高的方案。它不依赖额外构建步骤，开箱即用，核心是把图标转为 Symbol 雪碧图，再通过 <use></use> 按需引用，兼顾性能与开发体验。
安装插件并准备图标目录
确保图标文件统一放在指定路径（如 src/assets/icons），格式为标准 SVG，无内联 fill/stroke 属性更利于后期样式控制：
- 运行安装命令：
pnpm install vite-plugin-svg-icons fast-glob -D（推荐 pnpm；fast-glob是插件依赖，必须一并安装） - 创建目录：
src/assets/icons/，把所有 SVG 文件放进去（例如home.svg、user.svg）
配置 vite.config.ts
在 vite.config.ts 的 plugins 数组中加入插件实例，关键参数要写全：
-
iconDirs：传入绝对路径数组，建议用path.resolve(process.cwd(), 'src/assets/icons') -
symbolId：推荐设为'icon-[name]'（简洁）或'icon-[dir]-[name]'（防重名） -
inject：设为'body-last'，确保雪碧图注入到页面末尾，避免 SSR 或 Shadow DOM 场景下找不到节点 -
svgoOptions：可选，用于构建时自动清理冗余属性（如fill、style），提升图标纯净度
示例片段：
立即学习“前端免费学习笔记（深入）”；
Springboot Vue Builder
下载
从零开始编排 SpringBoot+Vue 全栈项目工作流，适用于新建全栈项目或完整脚手架请求，触发后依次调用 product‑spec‑builder（需求调研）等模块。
import { createSvgIconsPlugin } from 'vite-plugin-svg-icons'
import path from 'path'
export default defineConfig({
plugins: [
vue(),
createSvgIconsPlugin({
iconDirs: [path.resolve(process.cwd(), 'src/assets/icons')],
symbolId: 'icon-[name]',
inject: 'body-last',
svgoOptions: {
plugins: [{ name: 'removeAttrs', params: { attrs: ['fill', 'stroke', 'class'] } }]
}
})
]
})
注册全局 SVG 注入模块
在项目入口文件（如 main.ts）顶部添加一行虚拟模块导入，这是插件自动生成的注册逻辑，**必须存在且位置靠前**：
import 'virtual:svg-icons-register'- 这行代码不报错、不需手动创建文件，Vite 会在 dev 和 build 时自动处理
封装 SvgIcon 通用组件
新建 src/components/SvgIcon.vue，用 <use></use> 引用 symbol ID：
-
props.name对应 SVG 文件名（不含后缀），会拼成#icon-home这类 ID - 支持传入
class或内联style控制尺寸、颜色（推荐用currentColor继承文字色） - 加上
aria-hidden="true"保证可访问性合规
基础实现示例：
<script setup lang="ts">
import { computed } from 'vue'
const props = defineProps<{ name: string; className?: string }>()
const symbolId = computed(() => `#icon-${props.name}`)
</script>
<template>
<svg :class="['svg-icon', props.className]" aria-hidden="true">
<use :xlink:href="symbolId" />
</svg>
</template>
<style scoped>
.svg-icon { width: 1em; height: 1em; fill: currentColor; }
</style>
使用方式：<svgicon name="home" class="text-blue-500 w-5 h-5"></svgicon>
注意事项与避坑点
几个高频问题要提前留意：
- SVG 文件命名不要含大写字母或特殊符号，否则生成的 symbol ID 可能不匹配
- 开发时修改 SVG 内容会触发热更新，但新增/删除文件需重启 Vite 服务才能生效
- 若图标不显示，先检查浏览器控制台是否报
Failed to execute 'use' on 'SVGSVGElement'，大概率是symbolId格式和实际注入的 ID 不一致 - 如需主题色切换，可在 CSS 中定义
.svg-icon[data-theme="dark"] { fill: #fff; }，再由父组件动态传入data-theme
