TypeScript声明文件指南

可视化演示

交互展示TypeScript声明文件.d.ts的结构语法：模块声明、全局声明和类型定义方式。

声明文件基础

老宅的电路图不会画桌椅板凳，也不会画墙漆颜色，它只关心电从哪里来、开关接到哪里、线径承受多大电流。声明文件也是这样：.d.ts 文件里没有函数体、没有具体逻辑，只有一份“这里有什么接口、参数是什么、返回什么”的类型图纸。TypeScript 编译器在编译前打开这份图纸，就能知道一个 JS 库的每个角落该怎么接线，而不用去翻那堆被压缩、被混淆的源码。

为什么需要专门一张图纸，而不是直接在源码里写注释？因为很多老库是用纯 JavaScript 写的，改造源码成本高、风险大。声明文件的妙处在于它独立于源码：你可以在不触碰老宅墙体的前提下，把图纸画在另一张纸上，TS 会照着图纸检查，最终编译产出时又会把图纸整个扔掉，不影响运行时的一砖一瓦。

从数学视角看，一个 JS 库对外暴露的接口，可以看作“导出名字到类型”的对应关系：

对小陈来说，拿到这张图纸后，他不用再拿电笔逐个戳墙洞试探；对 TypeScript 来说，声明文件让它从“猜谜模式”进入“看图施工模式”。老宅还是那座老宅，但再也不会因为接错线而让整层楼跳闸。

全局声明语法

老宅里有些东西是“祖传公共设施”：比如每间房都能直接看到客厅的总闸，不需要先从一个模块里 import 进来。在 JS 里，这类挂在 window 或全局作用域下的库，就需要全局声明。它的语法核心是 declare 关键字——在图纸上写下“这里有一个总闸”，但不负责真的把闸装上去。

在 .d.ts 里，declare var 声明一个全局变量，declare function 声明一个全局函数，declare class 声明一个全局类，declare namespace 则像一个收纳盒，把一组相关的全局变量、函数都装进去。它们都只有类型签名，没有实现体。对编译器来说，declare 是一句承诺：“这个符号确实存在于运行环境中，请按此类型使用。”

用集合的语言描述，全局声明就是在全局命名空间中登记一个新符号：

老宅的总闸不是小陈画出来的，它本来就在那里；declare 只是把它的位置和规格告诉每一个后来施工的人。全局声明的价值，就是让那些“到处都是、随手可用”的 JS 全局变量，在 TypeScript 项目里也拥有姓名和类型。

模块声明语法

老宅之外还有一片新区，每栋房子都有门牌和单元号。当一个 JS 库通过 import 被引用时，它就像一个模块化的“单元房”，需要一张标好门牌号的图纸，告诉 TypeScript 这个包导出什么、忽略什么。声明文件里用 export 描述模块的对外导出，用 import 在类型世界中进行引用。

模块声明最常见的形态是给第三方包写“外部模块声明”：在 .d.ts 中写 declare module "some-lib" { ... }，把 some-lib 的导出项全部登记进去。如果项目里还有很多特殊后缀文件，比如 *.vue，也可以用通配符声明 declare module "*.vue"，相当于给一整类文件提前贴上通用门牌。

一个模块的声明，本质上是模块名到导出集合的映射：

小陈给新区施工时，只要先看一眼单元房的“户型图”，就知道卧室在哪、厨房在哪。模块声明提供的正是这种确定性：import 进来的每个名字，都能在图上一眼找到对应位置，再也不会“明明文档里写了，编辑器却一直报错”。

接口与类型声明

老宅装修时，插座面板是经常要换的部件：同一个面板形状，可以配两孔、三孔、USB 插口。interface 就像这样一个“面板模具”，它规定了一个对象必须有哪些字段、字段类型是什么；type 则像一个“缩略词”，把一段复杂的结构或联合类型起一个好记的名字。

接口还支持泛型，泛型就像给面板换上不同规格的插孔：Box<number> 装数字，Box<string> 装字符串。用泛型写一次，就能复用在多种数据类型上，减少了重复画图纸的时间。联合类型 A | B 表示“这个位置既可以接 A 也可以接 B”，交叉类型 A & B 表示“必须同时满足 A 和 B”。

从数学角度看，一个带泛型的接口就像一个参数化结构：

小陈在图纸上看到 Box<number>，就像看到“这个面板是两孔插座”；看到 Box<string>，则像是“这个面板是 Type-C 口”。接口和类型让复杂的图纸有了可复用的积木块，画起来省力，看起来也清晰。

DefinitelyTyped

老宅所在的社区有一个公共档案馆，叫 DefinitelyTyped。它收录了成千上万个流行 JS 库的声明文件，每个库对应一个 @types/包名 的 npm 包。比如 lodash 没有自带类型，社区就在 DefinitelyTyped 里维护了 @types/lodash；你只需要安装它，TS 就能立刻读懂 lodash。

安装方式很简单：npm install -D @types/lodash。因为 @types 只在开发阶段帮助编译器工作，运行时并不需要，所以通常放在 devDependencies（开发依赖）里，就像图纸只给施工队看，不塞进房子交付清单里。

公共档案馆的匹配规则可以形式化为：

小陈不用自己画所有图纸，公共档案馆已经保存了大部分成熟库的版本。他只需要按照 @types 命名规则去查、去装，就能让老宅项目立刻获得社区多年积累的类型经验。

编写声明文件

当公共档案馆也查不到某个内部老库时，小陈就得自己动手画图纸。第一步不是埋头写代码，而是“勘察现场”：分析这个 JS 库对外导出了哪些函数、类、变量，支持哪些参数，返回值长什么样。把这些接口面梳理成清单，声明文件才不会漏画关键线路。

画图时要多设计公共类型。如果某个函数参数是一个对象，不要直接写一团长长的匿名类型，而是先 interface 或 type 给它命名；这样项目其他代码也能复用，后续维护只改一个地方。写完之后还要“模拟施工”：用一个真实的 TS 文件去调用这些 API，或者用类型测试工具验证，确保图纸和实际房子对得上。

一段类型声明可以看作对源码 API 面的签名建模：

自己画图纸时，最忌讳“想当然”。小陈每画一条线，都要回到老宅实际确认一下线路走向。好的声明文件不是越厚越好，而是每一个导出项都有对应、每一个类型都尽可能具体，不多不少刚刚好。

发布与使用

图纸画完不能锁在抽屉里，得贴到房子门口，让每个需要的人都能看到。发布 npm 包时，声明文件要跟随包一起发布，并在 package.json 里告诉 TypeScript“入口图纸在哪里”——这就是 types 字段。它通常指向 index.d.ts 或构建产物里的类型入口文件。

同时，files 字段决定哪些文件会被打包进 npm 发布物。为了让 .d.ts 真正发布上去，必须把它列入 files 白名单，否则即使写了 types 字段，用户安装后也找不到图纸。发布后，项目里直接 import 这个库，TypeScript 就会按照 types 字段找到声明文件，完成类型检查。

发布配置的核心约束可以写作：

老宅装修完工后，小陈在门口钉了一个“管线示意图”信箱。路过的人不用敲开他家的门，也不用拆墙，就能知道线路布局。发布声明文件做的正是这件事：让你的库在 TypeScript 世界里成为一位“有图纸、可放心施工”的邻居。

AI 应用场景

Python 演示

# -*- coding: utf-8 -*-"""Generate a minimal .d.ts for a JSON-described API."""from typing import Any, Dict, List  def to_ts_type(t: str, aliases: Dict[str, str]) -> str:    aliases_map = aliases or {}    return aliases_map.get(t, t)  def render_params(params: List[Dict[str, str]], aliases: Dict[str, str]) -> str:    parts = []    for p in params:        name = p["name"]        optional = "?" if p.get("optional") else ""        ts_type = to_ts_type(p["type"], aliases)        parts.append(f"{name}{optional}: {ts_type}")    return ", ".join(parts)  def render_function(name: str, decl: Dict[str, Any], aliases: Dict[str, str]) -> str:    params = render_params(decl.get("params", []), aliases)    ret = to_ts_type(decl.get("returns", "void"), aliases)    return f"export function {name}({params}): {ret};"  def render_class(name: str, decl: Dict[str, Any], aliases: Dict[str, str]) -> str:    lines = [f"export class {name} {{"]    for method in decl.get("methods", []):        lines.append("  " + render_function(method["name"], method, aliases)[len("export "):])    for prop in decl.get("props", []):        pname = prop["name"]        ptype = to_ts_type(prop["type"], aliases)        lines.append(f"  {pname}: {ptype};")    lines.append("}")    return "\n".join(lines)  def build_declaration(schema: Dict[str, Any]) -> str:    aliases = schema.get("aliases", {})    out = ["// Generated by typemarker demo", "// 为无类型 JS 库生成声明文件骨架", ""]    for name, decl in schema.get("functions", {}).items():        out.append(render_function(name, decl, aliases))    for name, decl in schema.get("classes", {}).items():        out.append(render_class(name, decl, aliases))    for name, type_expr in schema.get("types", {}).items():        out.append(f"export type {name} = {type_expr};")    return "\n\n".join(out) + "\n"  if __name__ == "__main__":    schema = {        "aliases": {"Response": "{ status: number, data: unknown }"},        "functions": {            "get": {                "params": [                    {"name": "url", "type": "string"},                    {"name": "timeout", "type": "number", "optional": True}                ],                "returns": "Promise<Response>"            }        },        "classes": {            "EventBus": {                "methods": [                    {"name": "on", "params": [{"name": "event", "type": "string"}], "returns": "this"},                    {"name": "emit", "params": [{"name": "event", "type": "string"}], "returns": "void"}                ],                "props": [{"name": "version", "type": "string"}]            }        },        "types": {            "User": "{ id: number, name: string }"        }    }    print(build_declaration(schema))

1. def build_declaration(schema)把 JSON 格式的 API 描述翻译成 d.ts 文本。
2. aliases_map.get(t, t)支持把简写类型名替换成更完整的 TS 类型表达式。
3. parts.append(f"{name}{optional}: {ts_type}")拼出“参数名加问号加冒号加类型”的 TS 参数片段。
4. render_function(name, decl, aliases)为函数生成 export function ...; 签名。
5. render_class(name, decl, aliases)为类生成包含方法和属性的声明骨架。
6. out.append(f"export type {name} = {type_expr};")抽出公共类型，生成 type 别名。
7. schema = {...}模拟一个没有类型的 JS 库的 API 清单。
8. print(build_declaration(schema))在终端输出完整的声明文件初稿。

常见误区

面试题