5月27日 14:35

如何在项目中搭建一套可维护的 SVG 图标系统？

前端项目里的图标管理，往往是从"随便放几个 PNG"开始的。等到图标多了，尺寸不统一、颜色改不动、重复加载——问题一个接一个冒出来。SVG 图标系统解决的就是这件事：用一套工程化的方式，让图标的存储、引用、样式控制和更新维护都有章可循。

SVG Sprite 的核心原理

SVG Sprite 的思路和 CSS Sprite 类似——把多个图标合并到一个文件里，减少 HTTP 请求。不同的是，CSS Sprite 靠背景定位裁切，SVG Sprite 依赖 <symbol> 和 <use> 的引用机制，天然支持缩放和样式继承。

一个典型的 SVG Sprite 文件长这样：

xml
<svg xmlns="http://www.w3.org/2000/svg" style="display:none">
  <symbol id="icon-home" viewBox="0 0 24 24">
    <path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z"/>
  </symbol>
  <symbol id="icon-search" viewBox="0 0 24 24">
    <path d="M15.5 14h-.79l-.28-.27A6.47 6.47 0 0016 9.5 6.5 6.5 0 109.5 16c1.61 0 3.09-.59 4.23-1.57l.27.28v.79l5 4.99L20.49 19l-4.99-5z"/>
  </symbol>
</svg>

使用时通过 <use> 引用：

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

整个 Sprite 只需加载一次，之后引用任意图标都是零网络开销。

symbol 与 use 的复用机制

<symbol> 本身不渲染，它只是一个定义。关键的复用能力来自 <use>：

同文档引用：<use href="#icon-home"/>，Sprite 直接内联在页面 HTML 中。
外部文件引用：<use href="/sprites/icon.svg#icon-home"/>，Sprite 作为独立文件被缓存。

外部引用的优势是浏览器可以缓存 Sprite 文件，后续页面无需重新下载。但要注意，IE11 不支持跨文件引用，如果有兼容需求，可以用 polyfill（如 svg4everybody）或回退到内联方案。

一个实际的问题是：Sprite 内联后，<use> 引用的图标无法通过 CSS 直接修改 <symbol> 内部的 fill 或 stroke，因为 Shadow DOM 的隔离。解决办法是：源 SVG 中不要写死 fill 颜色，而是用 currentColor，这样外部 color 属性就能穿透进去。

图标组件化：React 与 Vue 的实现

组件化的目的是把 <svg><use/></svg> 这个模板封装起来，提供统一的 API。

React 实现

jsx
import spriteUrl from '/sprites/icon.svg';

function Icon({ name, size = 24, className }) {
  return (
    <svg
      className={className}
      width={size}
      height={size}
      aria-hidden="true"
    >
      <use href={`${spriteUrl}#${name}`} />
    </svg>
  );
}

// 使用
<Icon name="home" size={20} />

Vue 实现

vue
<template>
  <svg :class="className" :width="size" :height="size" aria-hidden="true">
    <use :href="`${spriteUrl}#${name}`" />
  </svg>
</template>

<script setup>
import spriteUrl from '/sprites/icon.svg';

defineProps({
  name: { type: String, required: true },
  size: { type: Number, default: 24 },
  className: { type: String, default: '' },
});
</script>

组件化之后，图标的使用变得声明式——不需要记住 <use> 的写法，只需要关心 name 和 size。颜色通过 currentColor + CSS color 控制，或者直接给组件传 style/className。

构建工具集成

手动维护 Sprite 文件是不现实的，图标一多就容易漏。构建工具的介入让整个过程自动化。

svg-sprite：通用的 Sprite 生成器

svg-sprite 是一个 Node.js 工具，把一个目录下的 SVG 文件合并成 Sprite：

bash
npx svg-sprite --symbol --symbol-dest sprites --symbol-sprite icon.svg src/icons/*.svg

它也提供 Gulp 和 Webpack 插件：

js
// gulp
const svgSprite = require('gulp-svg-sprite');

gulp.src('src/icons/*.svg')
  .pipe(svgSprite({ mode: { symbol: true } }))
  .pipe(gulp.dest('dist/sprites'));

SVGR：SVG 转 React 组件

如果你不想要 Sprite 方案，而是让每个 SVG 变成独立的 React 组件，SVGR 是更合适的选择。它会将 SVG 源码转换为 JSX，同时执行 SVGO 优化：

bash
npx @svgr/cli --icon --replace-attr-values "#000=currentColor" src/icons/home.svg

输出：

jsx
const SvgHome = (props) => (
  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" {...props}>
    <path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z" />
  </svg>
);

Webpack 配置：

js
// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.svg$/,
        issuer: /\.[jt]sx?$/,
        use: ['@svgr/webpack'],
      },
    ],
  },
};

Vite 配置：

js
// vite.config.js
import svgr from 'vite-plugin-svgr';

export default {
  plugins: [svgr()],
};

Vue 项目可以用 vite-svg-loader，效果类似：

js
import svgLoader from 'vite-svg-loader';

export default {
  plugins: [svgLoader()],
};

按需加载与 Tree-Shaking

Sprite 方案的局限在于：不管页面用了几个图标，整个 Sprite 都会被加载。对于图标量超过 200 的大型项目，这可能导致几十 KB 的浪费。

两种解法：

方案一：拆分 Sprite。按业务模块拆成多个 Sprite 文件（如 common.svg、dashboard.svg、editor.svg），页面只加载当前需要的 Sprite。

方案二：SVGR 组件化 + 按需导入。每个图标是独立组件，只有被 import 的图标才会打包：

jsx
import HomeIcon from './icons/Home';
import SearchIcon from './icons/Search';

function App() {
  return (
    <div>
      <HomeIcon />
      <SearchIcon />
    </div>
  );
}

这种方式天然支持 tree-shaking。但要注意避免 barrel file（icons/index.ts）把所有图标都引入——如果写了 export { default as Home } from './Home' 之类的统一导出，打包工具可能无法正确 tree-shake。解决方法是配置 "sideEffects": false，或者干脆不写 barrel file，直接从文件路径导入。

Vue 项目可以用 defineAsyncComponent 做动态加载：

js
const icon = defineAsyncComponent(() =>
  import(`../icons/${props.name}.svg?component`)
);

图标尺寸与颜色控制

尺寸

最简单的做法是组件上暴露 size 属性，同时设置 width 和 height。更灵活的方式是用 em 单位，让图标尺寸跟随字体大小：

css
.icon {
  width: 1em;
  height: 1em;
}

这样 font-size: 16px 时图标 16px，font-size: 24px 时图标 24px，和文字对齐非常方便。

颜色

控制颜色的前提是 SVG 源文件中使用 currentColor 而非硬编码色值。SVGO 可以自动做这个替换：

js
// svgo.config.js
module.exports = {
  plugins: [
    { name: 'preset-default' },
    {
      name: 'replaceAttrValues',
      params: { values: { '#000': 'currentColor', '#333': 'currentColor' } },
    },
  ],
};

之后 CSS 控制颜色即可：

css
.icon { color: #333; }
.icon-danger { color: #e53e3e; }
.icon-muted { color: #a0aec0; }

如果图标有两种颜色（比如外框 + 填充），可以用 CSS 变量区分：

css
.icon {
  --icon-primary: currentColor;
  --icon-secondary: #a0aec0;
}

SVG 源码中对应 fill="var(--icon-primary)" 和 fill="var(--icon-secondary)"。

Figma 导出 SVG 的工作流

设计到开发的图标流转，Figma 是大多数团队的起点。一个高效的导出流程长这样：

统一画板尺寸：所有图标放在相同尺寸的 Frame 里（通常 24×24），保证 padding 一致。导出时选 Frame 而非内部路径，否则 padding 会丢。
描边转轮廓：导出前执行 Outline Stroke（Cmd+Shift+O），把 stroke 转成 fill。否则导出的 SVG 会保留 stroke 属性，后续用 currentColor 控制颜色会出问题。
批量导出：选中多个 Frame → Export 面板 → 格式选 SVG → 导出。图标多的时候用插件（如 Freya DS Icon Exporter）一键批量导出。
命名规范：Frame 名称就是导出文件名，用 icon- 前缀 + kebab-case（如 icon-arrow-left），和代码中的引用名保持一致。
SVGO 二次优化：Figma 导出的 SVG 可能包含多余属性（id、data-name、冗余 <g>），用 SVGO 清理一遍：

bash
npx svgo -f src/icons --config=svgo.config.js

CI 集成：在 CI 流程中加入 Figma API 拉取 + SVGO + Sprite 生成的步骤，设计师在 Figma 里改图标后，开发者无感更新。

性能优化要点

SVGO 压缩。这是成本最低、收益最明确的优化。默认 preset 就能去掉注释、元数据、编辑器私有属性，通常能减少 30%-60% 体积。关键配置是保留 viewBox（关闭 removeViewBox）、移除固定尺寸（开启 removeDimensions），让图标通过 CSS 控制大小。

HTTP 缓存。Sprite 文件配置长期缓存（Cache-Control: max-age=31536000），文件名加 content hash。更新图标时 hash 变化，缓存自动失效。

预加载。如果 Sprite 是外部文件，可以在 <head> 中加 <link rel="preload" href="/sprites/icon.svg" as="fetch" crossorigin>，让浏览器提前下载。

内联 vs 外链的取舍。内联 Sprite 首屏零延迟，但会让 HTML 体积变大，且无法跨页缓存。外链 Sprite 可以缓存，但首次加载有一次额外请求。实践建议：核心图标（< 20 个）内联，其余走外链。

避免重复定义。同一个图标不要在 Sprite 中出现两次。构建时对 id 去重，否则 <use> 引用会指向错误的目标。

懒加载非关键图标。首屏不可见的图标，可以用 loading="lazy" 或在 Intersection Observer 触发后再插入 <use> 引用。

搭建 SVG 图标系统，核心决策只有两个：用 Sprite 还是组件化，内联还是外链。小项目 Sprite 内联就够了，中大型项目组件化 + 按需导入更合适。不管选哪条路，currentColor + viewBox + SVGO 这三件事做好，后续维护就能省掉大量重复劳动。Figma 到代码的自动化流程补上最后一环，让设计变更不再是手动搬运的体力活。

标签：SVG