解决 TypeScript "Cannot find module" 类型声明错误

问题描述

在使用 TypeScript 开发项目时，你可能会遇到类似以下的错误信息：

Cannot find module 'module-name' or its corresponding type declarations.

这种错误通常出现在导入第三方库或自定义模块时，TypeScript 编译器无法找到相应的类型声明文件。虽然项目可能能够正常编译和运行，但这些错误提示会影响开发体验和代码质量。

解决方案

1. 安装类型定义文件

大多数流行的 JavaScript 库都有对应的 TypeScript 类型定义文件：

# 安装库的类型定义
npm install @types/library-name --save-dev

# 示例：安装 React 的类型定义
npm install @types/react --save-dev

INFO

类型定义文件通常位于 DefinitelyTyped 仓库，这是 TypeScript 社区维护的集中式类型定义库。

2. 自定义类型声明

如果库没有提供类型定义，可以创建自定义声明：

// 在 src/types 或根目录下创建 globals.d.ts 文件
declare module 'library-name' {
  // 可以留空作为最低限度声明
  export const any: any;
  export default any;
}

// 或者为特定文件类型添加声明
declare module '*.png' {
  const value: string;
  export default value;
}

declare module '*.scss' {
  const content: { [className: string]: string };
  export default content;
}

在 tsconfig.json 中包含自定义类型目录：

{
  "compilerOptions": {
    // 其他配置...
  },
  "include": [
    "src",
    "types"  // 包含自定义类型目录
  ]
}

3. 配置路径映射

如果遇到本地模块解析问题，可以配置 baseUrl 和 paths：

{
  "compilerOptions": {
    "baseUrl": "./src",
    "paths": {
      "@components/*": ["components/*"],
      "@utils/*": ["utils/*"]
    }
  }
}

4. 重启 TypeScript 服务器

有时 TypeScript 语言服务器需要重启以获取最新配置：

VSCode

# 打开命令面板 (Ctrl+Shift+P 或 Cmd+Shift+P)
# 选择 "TypeScript: Restart TS Server"

其他编辑器

# 或者尝试重新安装依赖
rm -rf node_modules
npm install

5. 检查文件扩展名和命名

确保文件扩展名和导入语句一致：

// 正确 ✅
import Component from './Component.tsx';
import Helper from './helper.ts';

// 或者在较新版本的 TypeScript 中可以直接省略扩展名
import Component from './Component';
import Helper from './helper';

6. 配置模块解析策略

在 tsconfig.json 中明确指定模块解析策略：

{
  "compilerOptions": {
    "module": "esnext",
    "moduleResolution": "node",
    // 其他配置...
  }
}

特殊情况处理

使用 Yarn PnP

如果使用 Yarn 2+ 的 PnP 功能，可能需要额外配置：

# 安装 SDK 工具
yarn dlx @yarnpkg/sdks vscode

# 确保 TypeScript 版本兼容
yarn add typescript@4.7 --dev

静态资源导入

对于图片、CSS 等静态资源，需要添加类型声明：

// 在类型声明文件中
declare module '*.png';
declare module '*.jpg';
declare module '*.jpeg';
declare module '*.gif';
declare module '*.svg';
declare module '*.css';
declare module '*.scss';

总结

"Cannot find module" 错误通常由以下原因引起：

1. 缺少类型定义文件
2. 模块解析配置不正确
3. 文件路径或扩展名不匹配
4. TypeScript 服务器需要重启

通过合理配置 tsconfig.json、安装正确的类型定义文件以及必要时创建自定义类型声明，可以解决大多数模块解析问题。

WARNING

避免使用 // @ts-ignore 忽略这些错误，这可能会隐藏真正的类型问题，影响代码质量和维护性。

如果问题仍然存在，建议检查 TypeScript 版本、清理缓存并确保开发环境配置正确。