create-react-app搭建的React TypeScript项目无法识别*.d.ts报错如何解决？

报错根本原因 #

该报错是打包器/运行时的模块解析失败，不属于TypeScript编译层面的错误。.d.ts是纯类型声明文件，不含任何运行时代码，默认不会被webpack/Vite/Rollup等打包工具纳入可执行模块的解析范围，当打包器无法找到对应路径下的有效可执行文件时，就会抛出该错误。

常见触发场景：

• 导入路径中主动添加了.d.ts后缀
• 未使用import type导入类型，打包器尝试检索该路径下的运行时导出内容
• tsconfig.json未将.d.ts文件纳入类型检索范围
• 项目的模块解析规则与配置不匹配

可行解决方案 #

方案1（最推荐）：用普通.ts文件存放类型声明 #

将类型定义写在仅导出类型的普通.ts文件中，不需要使用.d.ts后缀。
示例：

// src/types/user.ts
export type User = {
  id: number
  name: string
  email: string
}

导入时使用import type语法：

import type { User } from '@/types/user'

import type导入的内容会在TypeScript编译后被完全移除，不会产生任何冗余运行时代码，同时完全满足类型与业务代码拆分的需求。

方案2：导入.d.ts时省略后缀 #

如果坚持使用.d.ts后缀的声明文件，导入时不要携带.d.ts后缀，TypeScript会自动检索对应路径的声明文件。
错误写法：

import type { User } from './types/user.d.ts'

正确写法：

import type { User } from './types/user'

方案3：调整tsconfig.json配置 #

确保声明文件所在目录被纳入include配置范围，同时模块解析规则适配项目打包工具：

{
  "compilerOptions": {
    "moduleResolution": "bundler", // Vite/Webpack项目用该值，Node.js项目用"Node"
    "typeRoots": ["./node_modules/@types", "./src/types"] // 可选，指定自定义类型目录
  },
  "include": ["src/**/*", "src/types/**/*.d.ts"] // 包含声明文件所在目录
}

方案4：使用全局类型声明 #

如果是全项目通用的类型，可以直接定义为全局类型，不需要导出导入：

// src/types/global.d.ts
declare type GlobalConfig = {
  appVersion: string
  baseUrl: string
}

配置好tsconfig.json的include后，项目内所有文件都可以直接使用GlobalConfig类型，无需手动导入。

方案5（不推荐）：调整打包器解析配置 #

如果必须导入带.d.ts后缀的文件，可以在打包器配置中添加.d.ts为可解析后缀，以webpack为例：

// webpack.config.js
module.exports = {
  resolve: {
    extensions: ['.ts', '.js', '.d.ts']
  }
}

该方案可能引发其他类型解析冲突，非必要不建议使用。

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