TypeScript 声明文件

TypeScript 要检查代码就必须知道每个变量、函数、模块的类型，可大量 JavaScript 库本身没有类型。声明文件（.d.ts）专门干这件事：它只描述"有什么、类型是什么"、不写实现，为已有 JS 代码补上一份类型说明书，让 TS 项目也能安全地使用纯 JS 库。

.d.ts 是什么

• .ts 文件同时含类型与实现，会参与编译并产出 JS；
• .d.ts（declaration）只含类型声明，编译后不产生任何 JS 代码。

自己写的 .ts 可以用编译器自动生成配套声明，发布给其他人用：

tsc app.ts --declaration   // 同时产出 app.js 与 app.d.ts

declare 声明全局

用 declare 告诉编译器"运行时里已经存在这些东西"（比如 <script> 引入的全局库）：

// globals.d.ts —— 全局声明文件
declare const VERSION: string; // 全局变量
declare function formatDate(d: Date): string; // 全局函数
declare class Logger {
  log(msg: string): void; // 全局类：只声明成员，不写实现
}

// app.ts —— 无需 import 直接使用（运行时确实存在）
console.log(VERSION); // 输出：1.0.0
const logger = new Logger();
logger.log("启动"); // 输出：启动

声明模块：给第三方库补类型

npm 上某些库不带类型也不在 @types 里，可以自己描述它的模块形状：

// mylib.d.ts
declare module "mylib" {
  export const version: string;
  export function parse(s: string): number;
}

// app.ts
import { parse } from "mylib";
console.log(parse("42")); // 输出：42

优先使用 @types

社区已经把主流库的类型整理成包，直接安装即可获得完整提示：

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

TypeScript 默认会从 node_modules/@types 自动加载类型。只有少数冷门老库没有现成包时，才需要自己写 .d.ts 并保证文件被 tsconfig 的 include 覆盖。

三斜线指令

在彼此没有 import 关系的声明文件之间建立引用：

/// <reference path="./globals.d.ts" /> // 引用某个本地文件
/// <reference types="node" /> // 引用 @types/node

注意：只要文件里出现了 import/export，它就是一个模块，应直接用 import 引入类型，而不是靠三斜线。

小结

声明文件 = 给 JS 补类型契约的 .d.ts：全局用 declare var/function/class，第三方包用 declare module。优先装 @types，没有就自己写。它只提供类型、零运行时开销，是 TS 生态兼容海量 JS 库的桥梁。