React TypeScript组件中SVG文件无法渲染的问题求助

问题描述 #

我用 React TypeScript 构建组件时，导入 SVG 文件后无法渲染，PNG 可以正常显示。试过以下几种导入方式：

import { ReactComponent as /*any name*/} from '../../assets/';
const Name = require('../../assets');
import Name from '../../assets/';

也尝试过自定义类型声明方案，但操作后没成功。当前代码示例如下：

import { BackButton, BackIcon, HeaderDiv, PeriodoTitle, SwitchButton, SwitchDiv, SwitchImg } from "./style";

type header = {
    title: string;
};

export default function PageHeader({title}: header) {
    return (
        <HeaderDiv>
            <BackButton>
                <BackIcon src={require('../../assets/Back.png')}/>
            </BackButton>

            <SwitchDiv>
                <SwitchButton>
                    <SwitchImg src={require('../../assets/goright.svg')}/>
                </SwitchButton>

                <PeriodoTitle>{title} Período</PeriodoTitle>
                
                <SwitchButton>
                    <SwitchImg src={require('../../assets/goleft.svg')}/>
                </SwitchButton>
            </SwitchDiv>
        </HeaderDiv>
    );
};

如代码所示，PNG 图片正常显示，但 SVG 完全无法渲染。

解决步骤 #

1. 使用 ReactComponent 正确导入 SVG #

在 React + TypeScript 项目中，SVG 需要通过 ReactComponent 方式导入为 React 组件，而非像 PNG 那样用 img 标签的 src 属性引用：

// 正确导入 SVG 为组件
import { ReactComponent as GoRightIcon } from '../../assets/goright.svg';
import { ReactComponent as GoLeftIcon } from '../../assets/goleft.svg';

之后直接在组件中使用该组件：

<SwitchButton>
  <GoRightIcon />
</SwitchButton>

<SwitchButton>
  <GoLeftIcon />
</SwitchButton>

这种方式会将 SVG 转换为 React 组件，支持直接渲染，还能通过 props 修改颜色、尺寸等属性。

2. 配置 TypeScript 类型声明（若项目未自动配置） #

如果导入时出现类型报错，在项目根目录创建 src/types/svg.d.ts 文件，添加以下类型声明：

declare module '*.svg' {
  import React = require('react');
  export const ReactComponent: React.FC<React.SVGProps<SVGSVGElement>>;
  const src: string;
  export default src;
}

同时确保 tsconfig.json 包含该类型文件路径：

{
  "compilerOptions": {
    "typeRoots": ["./src/types", "./node_modules/@types"]
  }
}

3. 避免用 img 标签加载 SVG #

你当前使用 require('../../assets/goright.svg') 作为 img 标签的 src，这种方式可能因构建工具配置问题无法正确解析 SVG 路径，或 SVG 本身包含外部资源引用（如字体）导致渲染失败。改用 ReactComponent 方式是最可靠的方案。

4. 检查构建工具配置（非 Create React App/Vite 项目） #

如果是自定义 Webpack 配置的项目，需安装 @svgr/webpack 并添加 SVG 处理规则：

module.exports = {
  module: {
    rules: [
      {
        test: /\.svg$/,
        use: ['@svgr/webpack'],
      },
    ],
  },
};

Vite 项目默认支持 SVG 组件导入，无需额外配置，只需确保使用 import { ReactComponent as Icon } from 'xxx.svg' 语法即可。

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