在 TypeScript 中，Triple-Slash Directives（三斜线指令） 是一种特殊的单行注释语法，以 /// 开头，主要用于指示编译器在编译时如何处理依赖关系。虽然随着模块系统（如 ES Modules、CommonJS）的普及，它的使用频率有所下降，但在某些场景下，Triple-Slash 指令依然非常重要，特别是在定义文件（.d.ts）中。
一、什么是 Triple-Slash Directive？
Triple-Slash 指令的语法形式如下：
/// <指令名 path="..."/>
它和普通注释不同，会被 TypeScript 编译器识别并参与编译处理。这类指令通常只写在文件的顶部，必须出现在任何 import 或其他语句之前。
二、常见的 Triple-Slash 指令类型
1. /// <reference path="..." />
- 说明：告诉编译器包含一个额外的文件，这个文件中定义的类型或声明将参与当前文件的类型检查。
- 适用场景：非模块化开发或
.d.ts类型定义文件之间的依赖。
/// <reference path="./types/jquery.d.ts" />
这意味着当前文件会引入 jquery.d.ts 文件中的声明信息。
2. /// <reference types="..." />
- 说明：告诉编译器加载某个名字对应的类型定义包，等价于在
tsconfig.json中的types数组中添加。 - 常用于引用来自
@types命名空间下的类型定义，比如：
/// <reference types="node" />
这会引入 @types/node 的类型定义（前提是它已被安装）。
3. /// <reference lib="..." />
- 说明：引用 TypeScript 提供的内建库声明（如
dom,es2015等），等效于在tsconfig.json中配置lib选项。 - 示例：
/// <reference lib="es2015" />
这会引入 ES2015 标准库定义，比如 Map, Set, Promise 等。
4. /// <reference no-default-lib="true"/>
- 说明：用于阻止 TypeScript 加载默认的库（如
lib.d.ts）。 - 通常与
/// <reference lib="..."/>搭配使用，确保只加载指定库。
/// <reference no-default-lib="true"/>
/// <reference lib="es2015" />
5. /// <amd-module />（很少用）
- 用于 AMD 模块系统中定义模块名。使用场景非常少，一般只在构建工具需要自定义模块名称时才用。
/// <amd-module name="my-library" />
三、Triple-Slash 与 import 的区别
| 特性 | Triple-Slash reference | import 语句 |
|---|---|---|
| 用途 | 用于声明间接依赖 | 用于模块导入 |
| 模块化支持 | 否（适用于非模块文件） | 是 |
| 是否执行代码 | 否，仅用于类型系统 | 是，执行运行时代码 |
| 支持位置 | 只能放在文件开头 | 可以放在任意位置 |
在现代 TypeScript 开发中，推荐使用 import 和模块系统来组织代码。Triple-Slash 更多用于 .d.ts 类型定义文件之间的引用或库的显式类型引入。
四、使用建议与注意事项
- 只在文件顶部使用三斜线指令，且必须在任何
import或export语句之前。 - 在
.d.ts文件中定义复杂类型依赖时，推荐使用/// <reference path="..." />。 - 不建议在模块化项目中滥用
/// <reference path="..." />，这会导致维护复杂。 - 如果你不确定某个库是否需要
/// <reference types="..." />，可以通过查看它的@types包文档确定。
五、实用示例
示例1：引入 jQuery 类型定义（未使用模块）
/// <reference path="jquery.d.ts" />
function test($el: JQuery) {
$el.hide();
}
示例2：使用 Node 类型（模块化项目）
/// <reference types="node" />
import * as fs from "fs";
fs.readFileSync("README.md");
示例3：自定义只引入部分标准库
/// <reference no-default-lib="true"/>
/// <reference lib="es2015" />
/// <reference lib="dom" />
六、结语
虽然在现代模块化 TypeScript 项目中，Triple-Slash Directives 的使用逐渐减少，但在类型定义文件管理、多库融合、非模块化代码维护等场景中，它依然是一种高效且强大的工具。掌握它的原理和使用方式，可以帮助我们更灵活地控制 TypeScript 的编译行为，尤其是在处理第三方类型或维护大型库的声明文件时。
