vite-plugin-svg-icons是Vite生态中最稳、最省事、真正按需的CSS Sprites方案，原生支持HMR与自动symbol注入，避免PNG雪碧图无法换色、缩放失真等缺陷。
直接用 vite-plugin-svg-icons，别自己拼 PNG 雪碧图——Vite 生态里它才是当前最稳、最省事、真正按需的 CSS Sprites 方案。
为什么不用 webpack-spritesmith 或手动 PNG 合并
手动拼图 + 算 background-position 容易错位、难维护，且无法响应式改色；webpack-spritesmith 在 Vite 里要桥接 Webpack 插件，配置绕、构建慢、热更新卡顿。而 vite-plugin-svg-icons 原生支持 Vite 的插件系统，开发时 HMR 快，生产构建自动注入 <svg><symbol>，图标只在用到时才渲染，没有冗余 DOM。
安装与基础配置（vite.config.ts）
先装插件：
npm install vite-plugin-svg-icons -D
再在 vite.config.ts 中启用：
立即学习“前端免费学习笔记（深入）”；
import { createSvgIconsPlugin } from 'vite-plugin-svg-icons'
import path from 'path'
export default defineConfig({
plugins: [
createSvgIconsPlugin({
iconDirs: [path.resolve(process.cwd(), 'src/icons')],
symbolId: 'icon-[dir]-[name]'
})
]
})
-
iconDirs必须是绝对路径，相对路径会导致构建失败或图标丢失 -
symbolId模板里的[dir]和[name]会自动解析成文件夹名和文件名（不含扩展），比如src/icons/common/home.svg→icon-common-home - 插件默认把 Sprite 注入
<body>底部，不污染 HTML 模板，也不依赖index.html手动引入
在组件中怎么用（Vue/React/HTML 通用）
两种写法都行，推荐第一种：
✅ 推荐：用 <svg><use> 标签，轻量、可继承 color、支持伪类动画
<svg class="icon"> <use href="#icon-common-home" /> </svg>
⚠️ 注意：href 值必须和 symbolId 生成的 ID 完全一致，大小写、连字符都不能错；如果用了动态 ID（如 icon-${type}-${name}），得确保运行时拼对
✅ 补充：CSS 中可通过 .icon { width: 1em; height: 1em; fill: currentColor; } 统一控制尺寸和颜色，无需为每个图标写样式
❌ 不要用 background-image: url(sprite.png) 那套——那是在倒退，既不能换色，也无法缩放保真，还丢掉了 SVG 的矢量优势
容易被忽略的坑和边界情况
开发时图标显示正常，但 build 后 <use> 找不到符号？八成是以下之一：
- SVG 文件里包含
<style>或外部@import—— 插件只提取<svg><symbol>结构，其他内容会被过滤 - 图标文件名含大写字母或中文（如
Home.svg或首页.svg），部分系统可能大小写敏感或编码异常，建议统一小写 + 中划线 - Vite 开启了
build.sourcemap: true且用了某些混淆插件，可能导致href解析失败；临时关闭 sourcemap 可验证是否为此原因 - 多入口项目（如 admin + main）共用同一套图标目录，但插件默认只为当前入口注入 Sprite —— 实际上它全局注入一次就够了，无需额外处理
真正的“合并减少请求”在这里已经完成：所有 SVG 被读取、去重、归一化后塞进一个内联 <svg style="display:none">，页面全程只发 0 次图标请求。
