TypeScript 声明文件

TypeScript 中的声明文件（Declaration Files）详解

声明文件（Declaration Files） 是 TypeScript 的核心机制之一，用于为非 TypeScript 编写的代码（如纯 JavaScript 文件、第三方库、浏览器 API、全局变量等）提供类型信息。声明文件以 .d.ts 为后缀，只包含类型定义，不包含实现代码，编译后不会生成 JavaScript。

1. 为什么需要声明文件？

• JavaScript 库（如 jQuery、Lodash）没有类型信息。
• 浏览器内置 API（如 document、window、fetch）是全局的。
• 项目中混用 .js 文件。
• 第三方 npm 包没有内置类型定义。

使用声明文件后，TypeScript 能在使用这些代码时提供智能提示、类型检查和错误提示。

2. 基本语法与结构

声明文件的核心关键字：

• declare：声明变量、函数、类、模块等存在（不实现）。
• module / namespace：组织全局或模块声明。
• interface / type：定义类型。
• export / import：模块化声明。

3. 常见声明类型

a. 全局变量/函数声明

// globals.d.ts
declare var myGlobalVar: string;           // 全局变量

declare function myGlobalFunction(msg: string): void;

declare class GlobalClass {
  constructor(name: string);
  say(): void;
}

declare const BUILD_VERSION: string;       // 全局常量

使用：

myGlobalFunction("hello");  // 有类型提示

b. 全局命名空间声明（扩展现有对象）

// augmentations.d.ts
declare global {
  interface Window {
    myAppConfig: {
      apiUrl: string;
      debug: boolean;
    };
  }

  namespace NodeJS {
    interface ProcessEnv {
      NODE_ENV: "development" | "production";
      API_KEY: string;
    }
  }
}

// 使用
window.myAppConfig.apiUrl;     // 有提示
process.env.API_KEY;           // 类型安全

c. 模块声明（为 JS 模块提供类型）

// declarations/lodash.d.ts
declare module "lodash" {
  export function chunk<T>(array: T[], size?: number): T[][];
  export function debounce<T extends Function>(func: T, wait: number): T;
  // ... 其他函数
  export default _;  // 默认导出（如果库是 default）
  const _: any;
}

// 使用
import _ from "lodash";
_.chunk([1,2,3,4], 2);  // 有类型提示

d. 为现有模块添加类型（Module Augmentation）

扩展第三方库（如 express）：

// types/express.d.ts
import "express";

declare module "express-serve-static-core" {
  interface Request {
    user?: {
      id: number;
      name: string;
    };
  }
}

// 使用 express 时
app.use((req, res, next) => {
  req.user?.name.toUpperCase();  // 有提示，不报错
});

4. DefinitelyTyped —— 社区类型定义

最常用的声明文件来源：@types 组织

安装：

npm install --save-dev @types/lodash
npm install --save-dev @types/jquery
npm install --save-dev @types/node   # Node.js 全局类型
npm install --save-dev @types/react

• 超过 10,000+ 个流行库的类型定义。
• 优先使用 @types/xxx，避免自己写。

5. 创建自己的声明文件

示例：为一个 JS 文件提供类型

项目结构：

src/
  utils.js          // 纯 JavaScript
  utils.d.ts        // 类型声明

// utils.js
module.exports = {
  formatDate(date) {
    return date.toISOString();
  },
  capitalize(str) {
    return str.charAt(0).toUpperCase() + str.slice(1);
  }
};

// utils.d.ts
export function formatDate(date: Date): string;
export function capitalize(str: string): string;

使用：

import * as utils from "./utils";
utils.capitalize("hello");  // 有类型提示

示例：为第三方无类型库写声明

// declarations/my-lib.d.ts
declare module "my-lib" {
  export interface Options {
    timeout?: number;
    retries?: number;
  }

  export function request(url: string, options?: Options): Promise<string>;

  export default request;
}

放在项目中任意位置，TS 会自动识别。

6. tsconfig.json 中的声明文件配置

{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./types"],  // 自定义类型目录
    "types": ["node", "lodash"]                         // 只加载指定 @types
  },
  "include": [
    "src/**/*.ts",
    "src/**/*.d.ts",        // 包含自定义声明文件
    "types/**/*.d.ts"
  ]
}

7. 最佳实践建议

建议	说明
优先使用 @types/xxx	社区维护，质量高
自定义声明放 types/ 或项目根	便于管理
全局增强用 declare global	扩展 Window、process 等
模块声明用 declare module "xxx"	为 JS 库提供类型
避免重复声明	利用模块增强而非重写
声明文件不包含实现代码	只写类型，编译后消失
开启 skipLibCheck: true	加速编译（可选）

小结：声明文件类型速查

场景	写法示例
全局变量	declare var $: any;
扩展 Window	declare global { interface Window { app: any; } }
为 JS 模块	declare module "my-lib" { export function fn(): void; }
第三方库	npm install @types/lodash
Node.js 全局	@types/node
模块增强	declare module "express" { interface Request { user?: User; } }

声明文件是 TypeScript 与 JavaScript 生态无缝衔接的桥梁。掌握它后，你可以安全地使用任何 JS 库，同时享受完整的类型支持。

如果您想看具体示例（如为 jQuery、Axios、或自定义 JS 项目写声明文件），或者如何发布自己的 @types 包，请告诉我！