Gatsby TypeScript项目导入SVG报错：元素类型无效，期望为字符串

AI 小北

2026-9-29

Gatsby TypeScript项目SVG导入错误解决方案

错误根因

这个报错核心是你引入的SVG模块没有被正确解析为React组件，导入结果为undefined，触发React渲染的类型校验失败，常见触发原因有3种：

gatsby-plugin-react-svg配置规则和Gatsby内置SVG处理逻辑冲突，插件未生效，SVG被当成静态资源返回路径字符串
导入语法混用了默认导出和命名导出
TypeScript缺少SVG模块的类型声明，识别不到组件导出

修复步骤

调整插件配置
在gatsby-config.ts中为gatsby-plugin-react-svg添加明确的匹配规则，避免和Gatsby默认的静态资源处理冲突，推荐用后缀区分需要作为组件导入的SVG：

module.exports = {
  plugins: [
    {
      resolve: "gatsby-plugin-react-svg",
      options: {
        rule: {
          // 仅将后缀为.inline.svg的文件解析为React组件
          include: /\.inline\.svg$/
          // 也可指定目录匹配：include: /src\/assets\/svg/
        }
      }
    }
  ]
}

调整SVG命名与导入方式
将需要作为组件使用的SVG文件重命名为符合匹配规则的格式，比如logo.svg改为logo.inline.svg，使用默认导入语法引入：

// 不要使用命名导入 import { Logo } from './logo.inline.svg'
import Logo from './logo.inline.svg'

const IndexPage = () => {
  // 直接作为组件使用
  return <Logo width={100} height={100} />
}

添加TypeScript类型声明
在src目录下新建typings.d.ts类型声明文件，写入SVG模块的类型定义：

declare module "*.svg" {
  import type React from "react";
  const SvgComponent: React.FC<React.SVGProps<SVGSVGElement>>;
  export default SvgComponent;
}