React+Vite项目中StoryBook无法加载SVG组件的问题求助

问题原因 #

StoryBook 默认不会自动继承项目 vite.config.js 中的所有插件配置，你使用的 vite-plugin-svg-icons 插件未在 StoryBook 的 Vite 环境中生效，同时缺少图标注册脚本的导入，导致 SVG 资源无法被正确加载。

解决方案步骤 #

1. 在 StoryBook 配置中注入 SVG 图标插件 #

修改 .storybook/main.js，通过 viteFinal 钩子将 createSvgIconsPlugin 添加到 StoryBook 的 Vite 配置链中：

import type { StorybookConfig } from '@storybook/react-vite';
import { createSvgIconsPlugin } from 'vite-plugin-svg-icons';
import path from 'path';

const config: StorybookConfig = {
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    '@storybook/addon-links',
    '@storybook/addon-essentials',
    '@storybook/addon-onboarding',
    '@storybook/addon-interactions',
  ],
  framework: {
    name: '@storybook/react-vite',
    options: {},
  },
  docs: {
    autodocs: true,
    defaultName: 'Documentation',
  },
  // 合并Vite配置，注入SVG图标插件
  async viteFinal(config) {
    config.plugins = [
      ...(config.plugins || []),
      createSvgIconsPlugin({
        // 注意路径：__dirname指向.storybook目录，向上退一级匹配项目src路径
        iconDirs: [path.resolve(__dirname, '../src/shared/ui/icon/assets')],
        symbolId: 'icon-[dir]-[name]',
      }),
    ];
    return config;
  },
};
export default config;

2. 导入 SVG 图标注册脚本 #

在 .storybook/preview.js（无则新建）中添加以下代码，确保图标资源被全局注册：

import 'virtual:svg-icons-register';

3. 重启服务验证 #

• 清除 StoryBook 缓存：执行 npx storybook --no-manager-cache
• 重启 StoryBook 服务，检查 SVG 组件是否正常渲染

额外检查点 #

• 确认 SVG 组件中引用图标的 symbolId 与配置的 icon-[dir]-[name] 格式完全一致，例如使用 <use href="#icon-[文件夹名]-[图标文件名]" />
• 核对 src/shared/ui/icon/assets 目录下是否存在目标 SVG 文件，路径无拼写错误

内容的提问来源于stack exchange，提问作者Alex