TypeScript 无法识别 SVG？一劳永逸地解决问题

引言：“Cannot find module”——熟悉的痛点？

您正在使用 TypeScript 编写代码，向项目中添加一个漂亮的 SVG 格式图标，并尝试以标准方式导入它：

import Logo from './assets/logo.svg';

然后 TypeScript 给您显示一个红色错误：

Cannot find module './assets/logo.svg' or its corresponding type declarations.

熟悉吗？如果您曾经遇到过这个问题——您并不孤单。Stack Overflow 上的问题 “Unable to import svg files in typescript” 已有数千次浏览和数十个答案。问题在于 TypeScript 默认不知道如何处理非代码文件（SVG、PNG、CSS）。

在本文中，我们将详细解释 完整的代码说明：为什么会出现错误以及如何一劳永逸地修复它。您将了解 声明文件、Webpack 和 Vite 的配置，以及如何在 React 项目中正确类型化 SVG。

为什么 TypeScript 无法识别 SVG？

TypeScript 是一种严格类型化的语言。它在编译阶段检查类型。当您编写 import Logo from './logo.svg' 时，TypeScript 期望模块 ./logo.svg 导出具有已知类型的内容。但 SVG 不是 TypeScript 文件，它是 XML。TypeScript 没有针对 SVG 模块的内置描述。

因此出现错误：编译器无法找到该文件的 类型声明。

解决这个问题主要有三种方法：

\n
• 方法 1： 创建全局声明文件（.d.ts）
\n
• 方法 2： 使用带有正确加载器的 Webpack/Vite
\n
• 方法 3： 通过 url 或 raw 导入 SVG（适用于特定情况）
\n

我们将用代码示例逐一讲解每种方法。

方法 1：全局声明文件（最流行）

这是来自 Stack Overflow 的解决方案，在 90% 的情况下有效。您创建一个扩展名为 .d.ts 的文件（例如 src/declarations.d.ts 或 src/svg.d.ts），并为 SVG 声明模块。

以下是最小代码：

// src/declarations.d.ts\ndeclare module '*.svg' {\n  const content: string;\n  export default content;\n}

这里发生了什么？我们告诉 TypeScript：“任何扩展名为 .svg 的文件都是一个模块，默认导出一个字符串（文件路径或内容）”。

如果您使用 React 并希望将 SVG 作为 React 组件导入（通过 @svgr/webpack 或 vite-plugin-svgr），声明将有所不同：

// src/declarations.d.ts\ndeclare module '*.svg' {\n  import React from 'react';\n  const SVGComponent: React.FC<React.SVGProps<SVGSVGElement>>;\n  export default SVGComponent;\n}

重要提示： 确保 .d.ts 文件包含在您的 tsconfig.json 中。通常，只要它位于 src/ 目录内即可，但如果没有，请在 include 字段中添加路径：

// tsconfig.json\n{\n  "compilerOptions": {\n    // ... 其他配置\n  },\n  "include": ["src/**/*"]\n}

之后，错误 “Cannot find module” 将消失，您可以像往常一样导入 SVG。

方法 2：配置 Webpack 或 Vite

全局声明只是成功的一半。要使导入在运行时（浏览器中）真正工作，您需要配置打包工具。

对于 Webpack

安装 file-loader 或 url-loader：

npm install --save-dev file-loader

在 webpack.config.js 中添加规则：

// webpack.config.