Typescript中.d.ts文件的加载规则、目录及优先级咨询

云上老周

2026-7-28

TypeScript .d.ts 文件解析规则与常见问题解答

一、.d.ts 文件的基本解析范围

TypeScript 默认会自动解析项目根目录下所有符合 tsconfig.json 包含规则的.d.ts 文件，不管它们在哪个子目录——只要没被exclude排除，或者被include明确包含，都会被识别。
并非只有baseUrl指定目录或package.json的types目录下的.d.ts才会被解析，这两个只是特定场景的配置，不是唯一的解析路径。

tsconfig.json 的 files 数组明确列出的.d.ts 文件：只要在这个数组里，无论位置如何都会优先加载。
package.json 的 types/typings 字段指定的文件/目录：多用于npm包的声明文件配置，当你导入某个包时，TS会优先读取这个字段指向的声明。
@types/* 包中的声明文件：TS会自动从node_modules/@types目录加载第三方包的声明，这是默认的第三方声明来源。
被include包含、未被exclude排除的项目内.d.ts 文件：你放在src或其子目录里的自定义声明，只要符合tsconfig的包含规则就会被解析。
baseUrl 与 paths 映射路径下的.d.ts 文件：baseUrl主要用于简化模块导入，TS会把指定目录作为模块查找的根目录，里面的.d.ts会按照模块导入规则被解析。

如果你的自定义全局声明文件没被识别，大概率是以下几个问题：

tsconfig.json 的 include 配置不全：比如你的include只写了["src/**/*.tsx", "src/**/*.ts"]，漏掉了.d.ts文件。可以改成["src/**/*.tsx", "src/**/*.ts", "src/**/*.d.ts"]，或者更简洁的["src/**/*"]。
文件被exclude排除：检查tsconfig里的exclude数组，有没有不小心把包含这个.d.ts的子目录加进去了。
声明写法错误：
- 如果你的.d.ts文件里有导入/导出语句（属于模块文件），全局声明必须放在declare global块中，并且要加空导出让TS识别为模块：
```
// src/utils/globals.d.ts
declare global {
  interface Window {
    myGlobalVar: string;
  }
}

export {};
```
- 如果文件里没有任何导入/导出，TS会把它当成全局脚本文件，直接写全局声明即可：
```
// src/globals.d.ts
interface MyGlobalType {
  id: number;
  name: string;
}
```
TS服务器缓存问题：重启VS Code的TypeScript服务器（Ctrl+Shift+P -> 选择"TypeScript: Restart TS Server"）就能解决缓存导致的声明不更新问题。

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