.d.ts 声明文件
最后更新：2026-10-22
.d.ts 声明文件
声明文件（.d.ts）只描述"一个库长什么样"，不含实现，让 TypeScript 能为纯 JS 库提供类型检查。类型有三个来源：库自带（最好）、社区 @types 包（npm i -D @types/xxx）、自己手写。手写的核心是 declare 关键字——声明"这个值/函数在别处已有实现"，编译器不为它生成任何代码。
| 分组 | 工程与实战 |
|---|---|
| 类型 | 配置 |
| 严格模式 | 不需要 |
ℹ️ 说明 编辑器将 TypeScript 转译为 JavaScript 后运行（不做类型检查）；类型检查结果见示例 Output。
📝 语法
// my-lib.d.ts —— 声明文件：只有类型，编译后消失
declare const APP_VERSION: string;
declare function log(msg: string): void;
interface Config {
host: string;
port: number;
debug?: boolean;
}
// 安装社区类型包：npm i -D @types/lodash⚙️ 参数
| declare const / let | 声明一个由宿主环境（库、CDN 全局变量等）提供的值，类型来自你的描述 |
|---|---|
| declare function | 声明一个已有实现的函数签名，只有类型没有函数体 |
| @types/* | 社区维护的声明包（DefinitelyTyped），装到 devDependencies 即自动生效，无需配置 |
返回值：无返回值——.d.ts 编译后不产出任何 JS，只在编译期向编译器提供类型信息。
▶ 示例
修改下面的代码，点击试一试查看转译运行结果：
输出：
info app booted
[10:24:00] OK db connected
（转译后运行输出；LogOptions 的形状由 .d.ts 提供——传入 { timestamps: "yes" } 会得到 error TS2322）💡 要点
ℹ️ 说明 类型的查找优先级：库的 package.json 里 types 字段指向的 .d.ts 优先，其次才找 @types 包，最后是项目里手写的声明。
💡 提示 手写声明时先用 console.log 实际跑一遍库，把真实形状记录成 interface，比凭文档猜类型靠谱得多；不确定的字段先标 optional。
⚠️ 注意 declare 声明的变量编译后没有对应 JS——运行时的值必须由宿主提供。声明了 LOG_LEVEL 却没人赋值，运行时拿到的是 undefined，且 TS 不会报错。
🏷️ 相关工程与实战
💡 相关案例
更多案例即将上线。
📚 相关教程
❓ 常见问题
Q npm i -D @types/xxx 装完还是没类型怎么办？
A 先确认包名（@types/ 后接原包名）和 tsconfig include 范围；DefinitelyTyped 上没有的库就需要自己手写：建一个 .d.ts，用 declare 描述用到的 API，放在编译范围内即可全局或按模块生效。
Q declare const 和普通 const 有什么区别？
A 普通 const 会编译成真实的 JS 变量；declare const 只是一个类型层面的"承诺"，告诉编译器"运行时会有这个名字"，编译产物里完全不存在。所以 declare 语句不能带初始化值。
Q declare module "xxx" 是干什么的？
A 环境模块声明：给一个 npm 包或非 TS 资源补类型。典型用途有二——给无类型的第三方包写 declare module "pkg" { ... }；以及 declare module "*.css" 让样式导入不再报"找不到模块"。
