TypeScript 声明文件基础

声明文件是 TypeScript 与 JavaScript 交互的桥梁，下面梳理核心用法。

.d.ts 作用

声明文件（.d.ts）为没有类型信息的 JavaScript 库提供类型描述，使 TS 编译器能够进行类型检查与智能提示。

// lodash.d.ts
declare function chunk(array: any[], size: number): any[][];
declare function debounce<T extends (...args: any[]) => void>(
  func: T,
  wait?: number
): T;

declare const _: {
  chunk: typeof chunk;
  debounce: typeof debounce;
};

export = _;

注意：声明文件仅包含类型信息，不包含实现代码，编译后不产生 .js 文件。

declare 关键字

声明全局变量

declare const API_URL: string;
declare function initApp(config: object): void;
declare namespace utils {
  function format(str: string): string;
}

声明全局类

declare class EventEmitter {
  on(event: string, listener: (...args: any[]) => void): this;
  emit(event: string, ...args: any[]): boolean;
}

模块声明

声明模块

// 声明一个第三方模块
declare module "my-lib" {
  export function create(options: object): void;
  export const VERSION: string;
}

使用：

import { create, VERSION } from "my-lib";
create({ debug: true });

声明模块扩展

// 扩展 Express Request 类型
declare global {
  namespace Express {
    interface Request {
      user: {
        id: string;
        role: string;
      };
    }
  }
}

第三方库声明

安装 @types 包

npm install --save-dev @types/lodash
npm install --save-dev @types/node

手动编写声明文件

当没有现成 @types 时，在项目根目录创建 types/ 目录：

src/
types/
  my-lib.d.ts
tsconfig.json

tsconfig.json 配置：

{
  "compilerOptions": {
    "typeRoots": ["./types", "./node_modules/@types"]
  }
}

声明文件最佳实践

常见声明模式

函数重载声明

declare function parse(input: string): object;
declare function parse(input: Buffer): object;

泛型声明

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

interface User { id: string; name: string; }
const user = await fetch<User>("/api/user");

类与接口声明

declare interface LoggerOptions {
  level: "debug" | "info" | "warn" | "error";
}

declare class Logger {
  constructor(options: LoggerOptions);
  log(msg: string): void;
  static create(options: LoggerOptions): Logger;
}

要点总结

• .d.ts 声明文件为 JS 库提供类型信息，编译后消失
• declare 关键字声明全局变量/函数/类，不产生运行时代码
• declare module 声明第三方模块或扩展现有模块类型
• 第三方库优先安装 @types/* 包，没有时手动编写声明文件
• 声明文件只应包含类型信息，不应包含运行时逻辑