TypeScript 中的声明文件（.d.ts）是什么？如何使用？

1. 声明文件的概念

• 声明文件（.d.ts）只包含类型信息，不包含任何可执行代码
• 它们告诉 TypeScript 编译器外部 JavaScript 代码的结构和类型
• 声明文件在编译时被完全擦除，仅用于类型检查和 IDE 智能提示

2. 环境声明

• 使用 declare 关键字声明在运行时存在但不在当前文件中定义的变量、函数、类或模块
• 例如 declare const __APP_VERSION__: string 声明一个全局常量
• 环境声明不会验证运行时是否真的存在该值，如果缺失会导致运行时错误

3. 为第三方库声明类型

• 当使用的 JavaScript 库没有自带类型定义时，可以创建声明文件描述其 API
• 例如为 lodash 声明类型：declare module "lodash" { export function chunk<T>(array: T[], size: number): T[][]; }
• 声明文件应放在 .d.ts 文件中，并在 tsconfig.json 的 include 范围内

4. DefinitelyTyped 与 @types

• DefinitelyTyped 是一个社区维护的声明文件仓库，包含数千个流行 JavaScript 库的类型定义
• 通过 npm install --save-dev @types/library-name 安装
• 安装后 TypeScript 会自动识别并加载这些类型定义
• 优先使用包自带的类型定义（bundled types），因为它们与包版本始终匹配

5. 生成声明文件

• 在 tsconfig.json 中启用 "declaration": true，编译时会自动生成 .d.ts 文件
• 配合 "declarationMap": true 生成声明文件的 source map，支持"跳转到定义"功能
• 使用 "emitDeclarationOnly": true 可以只生成声明文件，不生成 JavaScript 输出

6. 模块增强

• 使用 declare module "module-name" 为已有类型的模块添加新的类型定义
• 与声明合并结合，可以扩展第三方库的类型而不修改原始定义
• 例如为 Express 的 Request 对象添加自定义属性