SVG全站自定义图标架构实践方案

随着前端项目对高质量图标需求的不断提升，SVG 作为一种矢量图形格式，由于其无限缩放、轻量、易于样式控制等优势，已成为现代 Web 开发的首选。本文将详细介绍如何在 Next.js 项目中通过 SVGR 将 SVG 文件转换为 React 组件，实现全站统一管理、自动导入、动态调用和灵活定制的最佳实践方案。

1. 为什么选择 SVG 图标？

SVG 图标相比传统的位图（如 PNG、JPG）有以下显著优势：

• 无限缩放：不会失真，适用于高分辨率设备。
• 灵活的样式控制：通过 CSS 或组件属性（如 fill、stroke）轻松修改颜色和尺寸。
• 体积小：文件通常较小，加载速度快，有利于性能优化。
• 易于动画：SVG 天生支持基于路径的动画效果。

2. SVGR 简介

SVGR 是一个强大的工具，可以将 SVG 文件转换为 React 组件。这一转换不仅使得 SVG 可以像普通组件一样被直接引入和使用，而且支持在组件中传递各种属性进行样式定制。通过 SVGR，你可以摆脱传统静态资源管理的限制，实现全站统一的图标管理方案。

3. 在 Next.js 中使用 SVGR

默认情况下，Next.js 将 .svg 文件作为静态资源处理。如果希望将 SVG 文件转为 React 组件，需要修改 webpack 配置。以下是一个经过改进的 next.config.ts 示例，重点解决了以下问题：

• 区分 URL 模式和组件模式：通过资源查询（如 ?url）决定采用文件加载器或 SVGR 转换。
• 移除硬编码的颜色：利用 SVGO 插件自动移除 SVG 中写死的 fill 和 stroke 属性，从而支持动态样式。

// next.config.ts
import type { NextConfig } from "next";

const isDev = process.env.NODE_ENV !== "production";

const nextConfig: NextConfig = {
  output: "export",
  trailingSlash: true,
  assetPrefix: isDev ? "" : "https://career.zhaohuijian.com/",
  webpack(config) {
    // 找到处理 SVG 的现有规则
    const fileLoaderRule = config.module.rules.find(
      (rule: { test?: RegExp; resourceQuery?: { not: RegExp[] } }) =>
        rule.test?.test?.(".svg")
    );

    // 添加两个规则：一个用于 ?url 模式，另一个用于默认的 SVGR 转换
    config.module.rules.push(
      {
        // 保留现有文件 loader 处理 *.svg?url 的情况
        ...fileLoaderRule,
        test: /\.svg$/i,
        resourceQuery: /url/, // *.svg?url
      },
      {
        // 对于其他 *.svg 导入使用 SVGR 转换
        test: /\.svg$/i,
        issuer: fileLoaderRule.issuer,
        resourceQuery: { not: [...(fileLoaderRule.resourceQuery?.not || []), /url/] },
        use: [
          {
            loader: "@svgr/webpack",
            options: {
              icon: true,
              svgo: true,
              // 配置 SVGO 插件，移除写死的 fill 和 stroke 属性
              svgoConfig: {
                plugins: [
                  {
                    name: "removeAttrs",
                    params: { attrs: "(fill|stroke)" },
                  },
                ],
              },
            },
          },
        ],
      }
    );

    // 修改原有文件 loader 排除 *.svg 文件
    fileLoaderRule.exclude = /\.svg$/i;

    return config;
  },
  experimental: {
    turbo: {
      rules: {
        "*.svg": {
          loaders: ["@svgr/webpack"],
          as: "*.js",
        },
      },
    },
  },
};

export default nextConfig;

通过上述配置，项目中导入的 SVG 文件将被转换为 React 组件，并且原本写死的颜色属性会被移除，使得外部传入的 fill、stroke 或 CSS 控制能够生效。

4. 统一管理全站 SVG 图标

为实现全站统一管理，建议将所有 SVG 图标文件集中存放在一个专门的目录中（如 src/icon）。借助 webpack 的 require.context 方法，可以自动导入该目录下所有的 SVG 文件，并构建一个以文件名为键的图标映射对象。

自动导入并构建图标对象

// src/icon/index.js

// 使用 require.context 自动导入当前目录下所有 .svg 文件
const reqSvgs = require.context('./', false, /\.svg$/);

const icons = reqSvgs.keys().reduce((iconsMap, filePath) => {
  // filePath 形如 "./example.svg"，去除 "./" 和 ".svg" 得到文件名 "example"
  const fileName = filePath.replace('./', '').replace('.svg', '');
  // SVGR 转换后的组件通常为 default 导出
  iconsMap[fileName] = reqSvgs(filePath).default;
  return iconsMap;
}, {});

export default icons;

通过这种方式，任何一个 SVG 文件只需放入该目录，无需手动修改导入列表，即可在整个项目中统一调用。

5. 封装通用 SVG 图标组件

为了方便全站统一调用 SVG 图标，可以封装一个通用的图标组件（如 SvgIcon），实现按名称调用图标并支持灵活的属性传递。下面给出一个改进版示例：

// src/components/SvgIcon/index.jsx
import React from "react";
import SvgIcons from "@/icon"; // 自动导入所有 svg 文件，得到 { iconName: Component }

/**
 * SvgIcon 组件用于渲染指定名称的 SVG 图标
 *
 * @param {Object} props - 组件属性
 * @param {string} props.name - 图标名称（对应文件名，不包含扩展名）
 * @param {string|number} [props.width='1em'] - 图标宽度
 * @param {string|number} [props.height='1em'] - 图标高度
 * @param {string} [props.fill='currentColor'] - 图标填充色
 * @param {string} [props.className] - 附加的 CSS 类名
 * @param {Object} props.rest - 其他会透传给 svg 的属性，如 onClick、style 等
 *
 * @returns {JSX.Element|null} 返回 SVG 图标组件或 null（若图标不存在）
 */
const SvgIcon = ({
  name,
  width = "1em",
  height = "1em",
  fill = "currentColor",
  className = "",
  ...props
}) => {
  const IconComponent = SvgIcons[name];

  if (!IconComponent) {
    console.warn(`SvgIcon: Icon with name "${name}" not found.`);
    return null;
  }

  return (
    <IconComponent
      width={width}
      height={height}
      fill={fill}
      className={`inline-block align-[-0.15em] ${className}`}
      {...props}
    />
  );
};

export default SvgIcon;

在页面中使用时，只需通过图标名称（对应 SVG 文件名）调用组件即可：

jsx复制

import React from "react";
import SvgIcon from "@/components/SvgIcon";

export default function Page() {
  return (
    <div>
      <h1>SVG 图标示例</h1>
      {/* 调用图标名称为 "date" 的 SVG 图标 */}
      <SvgIcon name="date" width="2em" height="2em" fill="red" onClick={() => alert("clicked")} />
    </div>
  );
}

这种封装不仅简化了图标的使用方式，还通过透传 props 方式保证了组件的灵活性和扩展性。

6. 如何处理 SVG 写死的颜色

在部分 SVG 文件中，可能存在硬编码的 fill 或 stroke 属性，导致图标无法根据外部传入的样式变化颜色。为了解决这个问题，可以在 SVGR 转换过程中使用 SVGO 插件移除这些属性，确保图标样式能够由外部控制。

在 next.config.ts 中配置 SVGO 插件，如下所示：

{
  loader: "@svgr/webpack",
  options: {
    icon: true,
    svgo: true,
    svgoConfig: {
      plugins: [
        {
          name: "removeAttrs",
          params: { attrs: "(fill|stroke)" },
        },
      ],
    },
  },
}

这样，经过转换后的 SVG 组件不再携带写死的颜色属性，你可以在调用组件时通过传入 fill="currentColor" 或直接设置其他颜色，实现图标颜色的灵活定制。

7. 扩展性与维护建议

为了保证全站 SVG 图标方案的长远可维护性，建议注意以下几点：

• 文件命名规范：确保所有 SVG 文件的命名统一且具有语义，便于后续调用与维护。
• 组件参数类型：若项目中使用 TypeScript，可为 SvgIcon 组件添加严格的类型定义，提升开发体验和代码可读性。
• 备用图标处理：在 SvgIcon 组件中，可考虑对未找到的图标返回一个默认占位图标或输出友好的警告信息。
• 图标库更新机制：当新增或修改图标时，仅需将对应 SVG 文件放入指定目录，无需修改代码逻辑，从而实现自动化管理。