JavaScript / TypeScript / 系统课时
读取声明文件
读取声明文件
声明文件让 TypeScript 在不读取 JavaScript 实现细节的情况下理解一个 API。会读 .d.ts 后,你就能快速判断模块导出了什么、参数和返回值是什么、类型从哪里进入项目,并区分“类型检查通过”和“运行时真的存在实现”这两件事。
学习目标
- 区分 JavaScript 实现、TypeScript 源码与
.d.ts类型声明的职责 - 从导出、参数、可选属性和返回类型读取 API 契约
- 找到第三方包实际使用的声明入口并验证类型检查
把声明文件当作类型契约
.d.ts 只描述值和类型“长什么样”,不包含可执行实现,也不会单独生成 JavaScript。对于 TypeScript 库,编译器可以从 .ts 同时产出运行时 .js 和供使用者检查的 .d.ts;对于 JavaScript 库,也可以手写或额外生成声明文件来补充类型信息。

因此,看到一个库有完整自动补全,只能说明编辑器找到了类型契约;真正运行时,仍必须有对应 JavaScript 实现或其他运行时提供的值。
从导出入口读取 API
下面的 formatter.d.ts 是一个最小声明文件。它没有函数体,但已经足够让 TypeScript 检查调用方式。
export interface FormatOptions {
uppercase?: boolean;
prefix?: string;
}
export function format(
value: string,
options?: FormatOptions
): string;
export const version: string;阅读时先看顶层 export,它决定模块对外暴露哪些名字;再看函数参数和返回类型。options? 表示整个参数可省略,接口中的 uppercase? 与 prefix? 表示这些属性可选。version: string 只声明这个值存在且类型为字符串,并没有为它赋值。
如果声明文件中出现同名函数的多条签名,通常是在描述重载;如果出现 declare,含义是“这个值由别处提供实现”。判断一个名字能否直接导入,仍应以它是否位于模块导出结构中为准。
用消费端验证理解
把上面的声明保存为 formatter.d.ts,再创建一个只做类型检查的消费文件。这里导入 ./formatter.js,TypeScript 在解析时可以通过扩展名替换找到同名声明文件。
import { format, version } from "./formatter.js";
const message = format("hello", {
uppercase: true,
prefix: "TS"
});
console.log(version, message);执行类型检查:
npx tsc consumer.ts --noEmit --strict --module nodenext && echo "typecheck ok"预期输出:
typecheck ok这次验证只证明调用符合声明,不会执行 console.log,因为 --noEmit 不生成 JavaScript,而且示例没有提供 formatter.js 的运行时实现。若把 format("hello") 改成 format(42),编译器会在参数处报告类型不匹配,这正是声明文件提供的约束。
找到第三方库的声明入口
读取真实依赖时,不要从 node_modules 里随便挑一个 .d.ts。先从你实际写下的导入路径出发,再查看包的 package.json。库可能通过顶层 types 指向声明入口,也可能在 exports 的不同子路径中分别指定类型文件。
{
"name": "formatter",
"types": "./dist/index.d.ts",
"exports": {
".": {
"types": "./dist/index.d.ts",
"default": "./dist/index.js"
}
}
}这表示根入口的运行时代码与类型声明是两份不同文件。若库自身没有携带类型,常见做法是安装对应的 @types 包;TypeScript 还会自动加载标准 JavaScript 与所选运行环境相关的内置声明。
警惕声明与实现不一致
声明文件本质上是一份契约,因此它也可能写错。某个函数即使在 .d.ts 中存在,如果实际 .js 没有导出它,类型检查仍可能通过而运行时失败。排查第三方库问题时,应把“声明文件说什么”和“包实际导出什么”分开验证。
读声明文件时始终沿着“导入路径 → 包入口 → .d.ts 导出 → 具体签名”追踪,就能判断编辑器看到的类型来自哪里,也能在类型世界与运行时世界不一致时更快定位问题。