SVGR与Next.js集成：服务端渲染中的SVG最佳实践-优快云博客

SVGR与Next.js集成：服务端渲染中的SVG最佳实践

【免费下载链接】svgr Transform SVGs into React components 🦁 项目地址: https://gitcode.com/gh_mirrors/sv/svgr

在现代前端开发中，SVG（可缩放矢量图形）凭借其无损缩放和小文件体积的优势，成为图标和简单图形的首选格式。然而，在服务端渲染（SSR）环境如Next.js中使用SVG时，开发者常常面临兼容性、性能优化和开发体验的挑战。SVGR（SVG to React）作为一款强大的工具，能够将SVG文件转换为React组件，完美解决这些痛点。本文将详细介绍如何在Next.js项目中集成SVGR，并探讨服务端渲染环境下的SVG最佳实践。

为什么选择SVGR？

传统的SVG使用方式（如通过<img>标签引入或直接内联SVG代码）在React应用中存在诸多局限，尤其是在服务端渲染场景下：

无法直接使用React props：普通SVG无法像React组件那样接收className、style等props，难以实现动态样式和交互。
性能问题：未优化的SVG可能包含冗余代码，增加加载时间和渲染负担。
服务端渲染兼容性：直接内联SVG可能导致服务端和客户端渲染结果不一致（hydration mismatch）。

SVGR通过将SVG转换为React组件，解决了上述所有问题。转换后的组件具有以下优势：

完全可控：可以像普通React组件一样传递props，实现动态样式和行为。
自动优化：内置的SVGO优化器会自动移除SVG中的冗余代码，减小文件体积。
类型安全：支持TypeScript，提供良好的类型定义。
SSR友好：生成的React组件在服务端和客户端渲染时表现一致。

SVGR的核心转换过程包括：使用SVGO优化SVG、将SVG转换为HAST（HTML抽象语法树）、再将HAST转换为Babel AST（JSX抽象语法树）、应用Babel转换、最后生成格式化的React组件代码。这一复杂 pipeline 确保了转换的可靠性和安全性。

快速开始：在Next.js中安装SVGR

安装依赖

首先，在Next.js项目中安装SVGR的webpack loader：

npm install --save-dev @svgr/webpack
# 或使用yarn
yarn add --dev @svgr/webpack

配置Next.js

Next.js使用webpack作为构建工具，我们需要在next.config.js中配置webpack规则，以支持将SVG文件作为React组件导入。

创建或修改项目根目录下的next.config.js文件：

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  webpack(config) {
    // 查找现有的svg规则
    const fileLoaderRule = config.module.rules.find((rule) =>
      rule.test?.test?.(".svg"),
    );

    config.module.rules.push(
      // 确保svg规则优先于file-loader
      {
        test: /\.svg$/i,
        issuer: fileLoaderRule?.issuer,
        resourceQuery: { not: [...fileLoaderRule.resourceQuery.not, /react/] }, // 排除?react
        use: ["next-image-loader"],
      },
      // SVGR规则
      {
        test: /\.svg$/i,
        issuer: /\.[jt]sx?$/,
        resourceQuery: /react/, // 使用 ?react 参数导入为React组件
        use: [
          {
            loader: "@svgr/webpack",
            options: {
              icon: true, // 适合图标使用，默认将width和height设为1em
              svgoConfig: {
                plugins: [
                  {
                    name: "preset-default",
                    params: {
                      overrides: {
                        removeViewBox: false, // 保留viewBox属性，确保缩放正确
                      },
                    },
                  },
                ],
              },
            },
          },
        ],
      },
    );

    // 修改file-loader规则，排除.svg文件
    if (fileLoaderRule) {
      fileLoaderRule.exclude = /\.svg$/i;
    }

    return config;
  },
  /* 其他配置选项 */
};

export default nextConfig;

这个配置做了几件重要的事情：

保留了Next.js默认的图片处理能力（通过next-image-loader），但对SVG文件进行了特殊处理。
当SVG文件以?react查询参数导入时，使用@svgr/webpack loader将其转换为React组件。
配置SVGO优化器，禁用removeViewBox插件，以确保SVG能够正确缩放。
设置icon: true，使生成的组件默认宽高为1em，便于通过CSS控制大小。

TypeScript支持

如果你的项目使用TypeScript，需要添加类型声明以获得良好的类型提示。在项目根目录下创建svgr.d.ts文件：

declare module '*.svg?react' {
  import { FC, SVGProps } from 'react';
  const content: FC<SVGProps<SVGElement>>;
  export default content;
}

// 支持传统的URL导入方式
declare module '*.svg' {
  const content: string;
  export default content;
}

然后，在tsconfig.json的include数组中添加该声明文件：

{
  "include": [
    "svgr.d.ts",
    "next-env.d.ts",
    "**/*.ts",
    "**/*.tsx",
    ".next/types/**/*.ts"
  ]
  // ...其他配置
}

在Next.js中使用SVGR的两种方式

1. 作为React组件导入（推荐）

使用?react查询参数将SVG文件作为React组件导入：

import Logo from '../public/logo.svg?react';

export default function Home() {
  return (
    <div>
      <h1>Welcome to My App</h1>
      <Logo className="h-16 w-16 text-blue-500" />
    </div>
  );
}

这种方式的优势在于：

可以直接传递className、style等props，方便样式控制。
支持动态修改SVG的属性，如fill="currentColor"可以继承父元素的文本颜色。
组件化的方式更符合React的开发模式。

2. 作为图片URL导入

如果你需要将SVG作为普通图片使用（例如在<img>标签或background-image中），可以不使用?react参数：

import Image from 'next/image';
import logoUrl from '../public/logo.svg';

export default function Home() {
  return (
    <div>
      <Image src={logoUrl} alt="Logo" width={64} height={64} />
      <div style={{ backgroundImage: `url(${logoUrl})`, width: 64, height: 64 }} />
    </div>
  );
}

这种方式适用于不需要交互或动态样式的静态SVG。

服务端渲染中的SVG最佳实践

1. 避免使用`dangerouslySetInnerHTML`

在服务端渲染时，应避免使用dangerouslySetInnerHTML插入SVG代码，这可能导致XSS安全风险，并且不利于SEO。使用SVGR生成的React组件是更安全的选择。

2. 优化SVG大小

SVGR内置了SVGO优化器，可以通过配置进一步减小SVG文件体积。在next.config.js的svgoConfig中添加更多优化插件：

use: [
  {
    loader: "@svgr/webpack",
    options: {
      icon: true,
      svgoConfig: {
        plugins: [
          {
            name: "preset-default",
            params: {
              overrides: {
                removeViewBox: false,
                removeTitle: true, // 移除标题，减少体积
              },
            },
          },
          "removeDimensions", // 移除width和height属性，使用CSS控制
          "removeRasterImages", // 移除SVG中的 raster 图片
          "removeUnknownsAndDefaults", // 移除未知属性和默认值
        ],
      },
    },
  },
]

3. 使用`currentColor`实现主题适配

在SVG中使用currentColor作为填充色，可以使SVG的颜色继承父元素的color属性，方便实现主题切换：

<!-- icon.svg -->
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
  <path fill="currentColor" d="M12 2L2 7l10 5 10-5-10-5z" />
</svg>

在React组件中使用：

import Icon from './icon.svg?react';

// 主题色为蓝色
<div style={{ color: 'blue' }}>
  <Icon />
</div>

// 主题色为红色
<div style={{ color: 'red' }}>
  <Icon />
</div>

4. 处理大型SVG图标库

如果项目中使用大量SVG图标，可以考虑使用SVGR的CLI工具批量转换SVG文件，并生成图标组件库。

首先，安装SVGR CLI：

npm install --save-dev @svgr/cli

然后，在package.json中添加脚本：

{
  "scripts": {
    "build-icons": "svgr -d src/components/icons public/icons"
  }
}

运行该脚本，将public/icons目录下的所有SVG文件转换为React组件，并输出到src/components/icons目录。

高级配置：自定义SVG转换

自定义模板

SVGR允许使用自定义模板生成React组件。创建一个模板文件svgTemplate.js：

// svgTemplate.js
function template({ template }, opts, { imports, componentName, props, jsx, exports }) {
  const plugins = ['jsx'];
  if (opts.typescript) {
    plugins.push('typescript');
  }
  const typeScriptTpl = template.smart({ plugins });
  return typeScriptTpl.ast`
    ${imports}
    import { memo } from 'react';

    const ${componentName} = memo((${props}) => {
      return ${jsx};
    });

    ${exports}
  `;
}

module.exports = template;

这个模板使用React.memo包装生成的组件，提高性能。在next.config.js中配置使用该模板：

use: [
  {
    loader: "@svgr/webpack",
    options: {
      icon: true,
      template: require.resolve('./svgTemplate.js'), // 自定义模板路径
      // ...其他配置
    },
  },
]

使用Babel插件扩展功能

SVGR提供了多个Babel插件，可以进一步扩展其功能：

@svgr/babel-plugin-add-jsx-attribute：自动为SVG元素添加属性。
@svgr/babel-plugin-remove-jsx-attribute：移除指定属性。
@svgr/babel-plugin-transform-react-native-svg：适配React Native。

安装所需插件：

npm install --save-dev @svgr/babel-plugin-add-jsx-attribute

在next.config.js中配置：

use: [
  {
    loader: "@svgr/webpack",
    options: {
      icon: true,
      babelConfig: {
        plugins: [
          [
            '@svgr/babel-plugin-add-jsx-attribute',
            {
              elements: ['svg'],
              attributes: [{ name: 'data-icon', value: '{componentName}', spread: true }],
            },
          ],
        ],
      },
      // ...其他配置
    },
  },
]

常见问题与解决方案

1. SVG导入时报错“Cannot find module './icon.svg?react'”

这通常是TypeScript类型声明问题。确保svgr.d.ts文件已正确创建并包含在tsconfig.json的include数组中。

2. SVG组件样式不生效

检查是否正确传递了className或style props。如果使用CSS Modules，确保类名引用正确。

3. 服务端与客户端渲染结果不一致

确保所有SVG组件都使用React安全的属性（如className而非class，htmlFor而非for）。SVGR会自动转换这些属性，但手动编写的SVG代码需要注意。

4. SVG大小不响应式

确保SVG文件中包含viewBox属性，并且没有固定的width和height。在SVGR配置中设置removeDimensions: true可以移除固定尺寸。

总结

SVGR是Next.js项目中处理SVG的理想工具，它将SVG转换为React组件，解决了服务端渲染中的兼容性问题，同时提供了丰富的优化和扩展选项。通过本文介绍的方法，你可以轻松地在Next.js项目中集成SVGR，并遵循最佳实践使用SVG，提升应用性能和开发体验。

要了解更多关于SVGR的信息，可以参考以下资源：

官方文档：website/pages/docs/next.mdx
SVGR核心功能：packages/core/
CLI工具：packages/cli/
插件系统：packages/babel-plugin-transform-svg-component/

通过合理配置和使用SVGR，你可以充分发挥SVG在现代Web应用中的潜力，创建出既美观又高效的用户界面。

【免费下载链接】svgr Transform SVGs into React components 🦁 项目地址: https://gitcode.com/gh_mirrors/sv/svgr

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

SVGR与Next.js集成：服务端渲染中的SVG最佳实践