TypeScript Declaration Files 深度指南

什么是 Declaration Files？

TypeScript 的 declaration files（声明文件）是以 .d.ts 为扩展名的文件。它们的主要作用是为 JavaScript 代码提供类型信息。

核心作用

1. 为 JavaScript 库提供类型支持

• 很多 JavaScript 库本身没有类型信息
• Declaration files 让 TypeScript 项目能够对这些库进行类型检查
• 使用这些库时会获得代码补全和类型提示

2. 定义类型，不包含实现

• .d.ts 文件只声明类型、接口、类的结构，不包含实现代码
• 实际的逻辑代码在对应的 .js 文件中

.d.ts 文件的本质

从 TypeScript 编译器角度

.d.ts 文件和普通的 .ts 文件在语法上没有本质区别。 命名只是约定俗成：

• 都是 TypeScript 代码
• 都支持类型注解、接口、类型别名等所有 TypeScript 特性
• 编译器对两者的处理方式相同
• 命名（.d.ts）只是一个约定，用来表达"这是一个声明文件"的意图

实际区别在于使用场景

// 普通 .ts 文件：包含实现逻辑
// utils.ts
export function add(a: number, b: number): number {
return a + b;
}

// .d.ts 文件：通常只包含类型声明
// utils.d.ts
export function add(a: number, b: number): number;

编译器并不强制要求使用 .d.ts 扩展名，但这个约定帮助开发者快速识别这是一个声明文件。

declare 关键字的作用

为什么需要 declare？

declare 关键字告诉 TypeScript 编译器："这个东西存在，但它的实现在别处（通常是 JavaScript 运行时），我只是在这里声明它的类型"

declare 的核心作用：区分声明和实现

// 不用 declare：TypeScript 期望这里有实现
export function add(a: number, b: number): number {
return a + number; // 必须有实现
}

// 用 declare：只声明，不需要实现
declare export function add(a: number, b: number): number;

declare 的常见用法

1. 声明全局变量

// 某个外部 JS 库在全局挂了一个变量
declare const API_KEY: string; // 告诉 TS 这个全局变量存在

2. 声明全局函数

declare function fetch(url: string): Promise<Response>;

3. 声明类

declare class User {
name: string;
constructor(name: string);
}

4. 声明模块

// 告诉 TS"这个模块存在"，即使 node_modules 里没有类型
declare module 'my-untyped-lib' {
export function doSomething(): void;
}

5. 声明命名空间

declare namespace jQuery {
function ajax(settings: any): any;
}

实际例子：jQuery

假设你用一个通过