TypeScript 通过声明文件（.d.ts）为 JS 库、全局变量等提供编译期类型信息，不生成运行时代码；核心是准确描述已有代码形状，常见于补全第三方库类型、JS 项目渐进迁移、声明全局变量及适配非 ES 模块格式。
TypeScript 通过 声明文件（.d.ts） 来为 JavaScript 库、全局变量、模块或现有 JS 代码提供类型信息，它本身不生成运行时代码，只供编译期和编辑器使用。编写声明文件的核心是准确描述“已有代码的形状”，而不是重新实现逻辑。
什么时候需要写 .d.ts 文件
常见场景包括：
- 为没有内置类型定义的第三方 JavaScript 库补充类型（比如一个纯 JS 的工具包）
- 在 JS 项目中渐进式引入 TS，给已有 JS 模块加类型提示
- 声明全局变量（如 window 上挂载的 SDK 对象）、全局函数或命名空间
- 为 CommonJS / UMD / IIFE 等非 ES 模块格式的库编写类型入口
基本结构与常用语法
声明文件以 declare 开头，不包含实现，只描述接口。典型内容包括：
-
declare const/let/var：声明全局变量或模块导出的常量 -
declare function：声明函数签名（参数、返回值、重载） -
declare class：描述类的构造签名、属性和方法 -
interface或type：定义对象结构或联合类型 -
declare module 'xxx'：为特定模块提供类型（支持通配符、路径映射） -
export =和export as namespace：适配 CommonJS 或 UMD 导出方式
例如，为一个挂载在 window 上的 JS 对象写声明：
立即学习“Java免费学习笔记（深入）”；
declare global {
interface Window {
mySDK: {
init(options: { debug?: boolean }): void;
version: string;
};
}
}
如何组织与引用声明文件
声明文件需被 TypeScript 找到才能生效。常用方式有：
- 放在项目根目录下命名为
types/index.d.ts，并在tsconfig.json的typeRoots或files中包含 - 直接在源码同目录下建
xxx.d.ts（如utils.js对应utils.d.ts），TS 会自动识别 - 发布 npm 包时，在
package.json中设置"types": "index.d.ts"字段 - 用
/// <reference types="..."></reference>在单个文件顶部手动引入（较少用）
验证与调试技巧
写完声明文件后，可通过以下方式确认是否生效：
- 在 TS 文件中导入/使用对应 API，看编辑器是否给出正确提示和类型检查
- 运行
tsc --noEmit --watch，观察是否有类型错误或“无法找到模块”警告 - 用
tsc --showConfig查看实际加载的声明文件路径 - 在 VS Code 中按 Ctrl+点击跳转，确认是否定位到你的 .d.ts 而不是 any 类型回退
遇到类型未识别，优先检查文件是否在 include 范围内、模块名拼写是否一致、导出语法是否匹配（default export vs named export vs UMD 命名空间）。
