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.tsdeclarevarmyGlobalVar:string;// 全局变量declarefunctionmyGlobalFunction(msg:string):void;declareclassGlobalClass{constructor(name:string);say():void;}declareconstBUILD_VERSION:string;// 全局常量

使用：

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

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

// augmentations.d.tsdeclareglobal{interfaceWindow{myAppConfig:{apiUrl:string;debug:boolean;};}namespaceNodeJS{interfaceProcessEnv{NODE_ENV:"development"|"production";API_KEY:string;}}}// 使用window.myAppConfig.apiUrl;// 有提示process.env.API_KEY;// 类型安全

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

// declarations/lodash.d.tsdeclaremodule"lodash"{exportfunctionchunk<T>(array:T[],size?:number):T[][];exportfunctiondebounce<TextendsFunction>(func:T,wait:number):T;// ... 其他函数exportdefault_;// 默认导出（如果库是 default）const_:any;}// 使用import_from"lodash";_.chunk([1,2,3,4],2);// 有类型提示

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

扩展第三方库（如 express）：

// types/express.d.tsimport"express";declaremodule"express-serve-static-core"{interfaceRequest{user?:{id:number;name:string;};}}// 使用 express 时app.use((req,res,next)=>{req.user?.name.toUpperCase();// 有提示，不报错});

4. DefinitelyTyped —— 社区类型定义

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

安装：

npminstall--save-dev @types/lodashnpminstall--save-dev @types/jquerynpminstall--save-dev @types/node# Node.js 全局类型npminstall--save-dev @types/react

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

5. 创建自己的声明文件

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

项目结构：

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

// utils.jsmodule.exports={formatDate(date){returndate.toISOString();},capitalize(str){returnstr.charAt(0).toUpperCase()+str.slice(1);}};

// utils.d.tsexportfunctionformatDate(date:Date):string;exportfunctioncapitalize(str:string):string;

使用：

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

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

// declarations/my-lib.d.tsdeclaremodule"my-lib"{exportinterfaceOptions{timeout?:number;retries?:number;}exportfunctionrequest(url:string,options?:Options):Promise<string>;exportdefaultrequest;}

放在项目中任意位置，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; } }`