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; } } |
声明文件是 TypeScript 与 JavaScript 生态无缝衔接的桥梁。掌握它后，你可以安全地使用任何 JS 库，同时享受完整的类型支持。
如果您想看具体示例（如为 jQuery、Axios、或自定义 JS 项目写声明文件），或者如何发布自己的@types包，请告诉我！
