TypeScript如何识别自定义命名的第三方类型扩展声明文件

问题现象 #

• 按照Emotion TypeScript开发指南扩展主题类型时，在src目录下新建emotion.d.ts写入模块扩展代码，TypeScript无法识别自定义的Theme接口
• 相同代码写入根目录global.d.ts时可以正常生效
• 目标是实现自定义命名的.d.ts文件被TS正常加载，完成第三方库类型扩展

使用的声明文件代码如下：

import '@emotion/react'

declare module '@emotion/react' {
  export interface Theme {
    color: {
      primary: string
      positive: string
      negative: string
    }
  }
}

核心原因 #

TypeScript不会无差别加载项目下所有.d.ts文件，默认自动加载规则仅覆盖：

• 根目录下无顶级import/export语法的全局声明文件（比如根目录的global.d.ts）
• node_modules/@types/、根目录@types/下的类型声明
  其余自定义路径、自定义命名、带有模块导入语法的声明文件，必须显式纳入TS的编译扫描范围才会生效。

可行配置方案 #

方案1：调整tsconfig.json的include扫描范围（推荐） #

打开项目根目录的tsconfig.json，在include字段中添加声明文件所在路径的匹配规则，确保你存放emotion.d.ts的目录被覆盖：

{
  "compilerOptions": {
    // 保留原有compilerOptions配置，不需要额外改动
  },
  "include": [
    "src/**/*.ts",
    "src/**/*.tsx",
    "src/**/*.d.ts" // 新增该行，匹配src目录下所有.d.ts声明文件
  ]
}

如果你的声明文件放在src外的自定义目录（比如根目录types/文件夹），把对应路径的匹配规则也加到include数组即可。

方案2：通过已生效的全局声明文件中转引入 #

如果不想调整tsconfig.json配置，可以在已经能被TS正常识别的global.d.ts顶部，通过相对路径引入你的自定义声明文件：

// 根目录global.d.ts
import './src/emotion.d.ts' // 替换为你的emotion.d.ts实际相对路径

// 其余原有全局类型声明保持不变

TS会顺着文件引用链加载到你写的Emotion类型扩展代码，不需要额外配置即可生效。

方案3：放到TS默认扫描的类型目录 #

在项目根目录新建@types文件夹，把emotion.d.ts移动到该文件夹下，TS默认会自动扫描根目录@types下的所有类型声明文件，不需要额外修改配置即可识别扩展。

内容的提问来源于stack exchange，提问作者sir-haver