如何在Next.js项目中使用SVG Sprite？求SSR兼容的最佳实践与成功实现方案

我刚好在几个Next.js项目里实践过SVG Sprite的SSR兼容方案，分享给你参考～

因为你提到的第三方包已经停止维护，手动实现反而更可控，而且完全兼容SSR，下面是具体步骤和最佳实践：

一、核心思路：静态生成Sprite + 全局注入 #

我们先把所有SVG图标合并成一个Sprite文件，然后在Next.js的SSR渲染入口里全局注入这个Sprite的内容，确保服务端和客户端都能访问到图标资源。

1. 准备图标资源 #

• 在项目里创建一个专门存放SVG图标的目录，比如src/icons。
• 每个SVG图标要去掉自带的width、height、fill属性（避免默认样式限制复用），后续脚本会自动为每个图标添加唯一id。

2. 编写脚本生成Sprite文件 #

用Node.js脚本批量合并并优化SVG，这里用到svgo来压缩和清理SVG代码：

首先安装依赖：

npm install svgo --save-dev

然后在scripts目录下创建generate-sprite.js：

const fs = require('fs');
const path = require('path');
const svgo = require('svgo');

// 图标目录和输出目录
const iconsDir = path.join(__dirname, '../src/icons');
const outputDir = path.join(__dirname, '../public');

async function generateSprite() {
  // 读取所有SVG文件
  const svgFiles = fs.readdirSync(iconsDir).filter(file => file.endsWith('.svg'));
  let spriteContent = '<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">';

  for (const file of svgFiles) {
    const iconName = path.basename(file, '.svg');
    const rawSvg = fs.readFileSync(path.join(iconsDir, file), 'utf8');

    // 优化SVG并添加唯一ID
    const optimizedSvg = await svgo.optimize(rawSvg, {
      plugins: [
        { removeDimensions: true }, // 移除默认宽高
        { removeAttrs: { attrs: 'fill' } }, // 移除默认填充色
        { addAttributesToSVGElement: { attributes: [{ id: `icon-${iconName}` }] } } // 添加唯一ID
      ]
    });

    spriteContent += optimizedSvg.data;
  }

  spriteContent += '</svg>';
  // 生成Sprite文件到public目录
  fs.writeFileSync(path.join(outputDir, 'icons-sprite.svg'), spriteContent);
  console.log('SVG Sprite生成完成！');
}

generateSprite();

在package.json里添加执行脚本：

{
  "scripts": {
    "generate-sprite": "node scripts/generate-sprite.js"
  }
}

每次新增或修改图标后，运行npm run generate-sprite即可更新Sprite文件。

3. 在SSR入口注入Sprite #

Next.js的渲染入口是实现SSR兼容的关键，我们在这里把Sprite内容直接注入到页面中，确保服务端渲染时就包含图标资源：

Pages Router 方案（pages/_document.js）：

import Document, { Html, Head, Main, NextScript } from 'next/document';
import fs from 'fs';
import path from 'path';

class MyDocument extends Document {
  static async getInitialProps(ctx) {
    const initialProps = await Document.getInitialProps(ctx);
    // 读取生成的Sprite文件
    const spritePath = path.join(process.cwd(), 'public/icons-sprite.svg');
    const spriteContent = fs.readFileSync(spritePath, 'utf8');
    return { ...initialProps, spriteContent };
  }

  render() {
    return (
      <Html>
        <Head />
        <body>
          {/* 注入Sprite内容到页面 */}
          <div dangerouslySetInnerHTML={{ __html: this.props.spriteContent }} />
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}

export default MyDocument;

App Router 方案（app/layout.js）：

import fs from 'fs';
import path from 'path';

export default function RootLayout({ children }) {
  // 读取Sprite文件（开发环境可以用动态读取，生产环境建议预生成）
  const spriteContent = fs.readFileSync(path.join(process.cwd(), 'public/icons-sprite.svg'), 'utf8');

  return (
    <html lang="en">
      <body>
        <div dangerouslySetInnerHTML={{ __html: spriteContent }} />
        {children}
      </body>
    </html>
  );
}

二、封装图标组件方便复用 #

写一个通用的Icon组件，让使用图标更简单：

import React from 'react';

const Icon = ({ name, className, fill = 'currentColor', size = '24px' }) => {
  return (
    <svg
      className={className}
      width={size}
      height={size}
      fill={fill}
      aria-hidden="true"
      role="img"
    >
      <use href={`#icon-${name}`} />
    </svg>
  );
};

export default Icon;

使用示例：

import Icon from '@/components/Icon';

function Profile() {
  return (
    <div>
      <Icon name="user" className="text-gray-700 mr-2" size="20px" />
      <span>我的账户</span>
    </div>
  );
}

三、SSR兼容的关键注意事项 #

• 必须在SSR入口注入Sprite：如果只在客户端组件里加载Sprite，会导致服务端渲染时图标缺失，出现首次加载闪烁或不显示的问题。
• 确保图标ID唯一：脚本里已经用文件名作为ID前缀，避免不同图标ID冲突。
• 开发环境热更新优化：可以用chokidar监听图标目录变化，自动重新生成Sprite：

  npm install chokidar --save-dev
  

  然后创建scripts/watch-sprite.js：

  const chokidar = require('chokidar');
  const generateSprite = require('./generate-sprite');
  
  // 监听图标目录变化
  const watcher = chokidar.watch('../src/icons', { ignoreInitial: false, cwd: __dirname });
  watcher.on('add', generateSprite);
  watcher.on('change', generateSprite);
  watcher.on('unlink', generateSprite);
  
  console.log('正在监听SVG图标变化...');
  

  在package.json里添加脚本："watch-sprite": "node scripts/watch-sprite.js"，开发时运行这个命令即可自动更新Sprite。

四、成功实现案例 #

我在一个Next.js 13的SSR项目中使用这个方案，完全满足需求：

• 服务端渲染时图标直接渲染为正确的SVG结构，没有加载延迟或闪烁。
• 客户端路由跳转时，直接复用已加载的Sprite，性能优异。
• 支持通过组件props灵活控制图标颜色、大小和样式，适配不同场景。

内容的提问来源于stack exchange，提问作者M.Anagnostopoulos