三斜线指令

三斜线指令是放在文件最顶部的注释，长得像 XML 标签，但它们不是普通的注释——TypeScript 编译器会解析它们，把它们当成编译指令来执行。格式只有一种：单行注释里包含一个 XML 标签。

/// <reference path="./Validation.ts" />

三斜线指令只能放在文件最顶部，前面只能有其他注释（包括别的三斜线指令）。如果写在代码语句后面，它就成了普通注释，什么效果都没有。

/// <reference path="" />

这个指令告诉 TypeScript：“编译时把这个文件也纳进来”。它声明了文件之间的依赖关系。

// main.ts
/// <reference path="./types.d.ts" />
/// <reference path="./utils.ts" />

const result = doSomething(); // doSomething 定义在 utils.ts 里

当 TypeScript 处理 main.ts 时，会按深度优先的顺序把 types.d.ts 和 utils.ts 也加入编译列表。这个顺序也很关键——如果用 outFile 合并输出，文件会按引用顺序拼接。

相对路径的 path 是相对于当前文件，不是相对于项目根目录。这一点经常被忽略。

// src/core/main.ts
/// <reference path="../types/validation.d.ts" />
// 指向 src/types/validation.d.ts

reference path 有几个规则：引用的文件必须存在，报错如果不存在；文件不能引用自己；如果编译器开了 noResolve，三斜线指令全被忽略。

/// <reference types="" />

reference types 声明了一个包级别的依赖——类似于 “为声明文件写的 import”。

/// <reference types="node" />

这行告诉 TypeScript：“我需要 @types/node 这个包的类型”。编译器会像解析 import "node" 一样去 node_modules/@types/node 目录找对应的 .d.ts 文件。

这个指令的出现场景很典型：你写了一个 .d.ts 声明文件，里面用了 Node.js 内置类型（比如 Buffer、process），但 .d.ts 文件里不能写 import 语句（写了就变成模块文件了）。这时候用 reference types 声明依赖，既拿到了类型信息，又保持文件是脚本模式。

// my-declarations.d.ts
/// <reference types="node" />

declare function readConfig(path: string): Buffer;
// Buffer 来自 @types/node

/// <reference lib="" />

这个指令让当前文件显式引入一个内置标准库的声明。

/// <reference lib="es2017.string" />

"hello".padStart(10, " ");
// padStart 是 ES2017 字符串新方法，不引入这个 lib 的话这段代码报错

lib 的值和 tsconfig.json 里 compilerOptions.lib 的写法一样——写 "es2017.string"，不是 "lib.es2017.string.d.ts"。

它的主要用户也是 .d.ts 声明文件作者。如果你写的声明文件用了 Symbol、Iterable 这些”不属于默认 lib”的全局类型，以前的做法是自己再声明一遍，现在用 reference lib 一行搞定。

现代替代：tsconfig.json

大多数三斜线指令可以被 tsconfig.json 的配置替代。官方文档也在引导开发者减少对三斜线指令的依赖：

三斜线指令	tsconfig 替代
/// <reference path="./foo.ts" />	compilerOptions.files: ["./foo.ts"] 或直接用 import
/// <reference types="node" />	compilerOptions.types: ["node"]
/// <reference lib="es2017" />	compilerOptions.lib: ["es2017"]

tsconfig.json 的写法有什么好处？

集中管理。 所有依赖在一处说清楚，不需要翻几十个文件找三斜线指令。

工具链友好。 编辑器、CI、代码审查工具都认 tsconfig.json，三斜线指令容易被当成注释忽略。

避免”螃蟹式依赖”。 reference path 是手动维护的依赖图，文件一多就容易漏引用或重复引用。import 语句和 tsconfig 的 include/exclude 是自动维护的。

所以结论很简单：如果你的项目有 tsconfig.json（现在还有谁没有呢），就别在 .ts 源文件里写三斜线指令了。用 import 声明代码依赖，用 tsconfig 配置类型和标准库的引入。

还保留的特殊情况

三斜线指令没有完全作废。以下场景它仍然合理：

1. .d.ts 声明文件需要内置 lib 类型。 这时候 reference lib 比在 tsconfig 里加全局 lib 更精确——只有这个声明文件需要这个 lib，其他文件不需要。

2. 一些旧的 DefinitelyTyped 类型包。 社区维护的 @types/* 包里偶尔还能看到 reference types 和 reference path。这是历史遗留，不影响你使用。

3. TS 5.5 起不会把三斜线指令写到编译输出里。 如果你手写了 /// <reference path="" />，不加 “ 的话，输出文件里不会出现这行。

/// <reference path="./utils.ts"  />

小结

三斜线指令是 TypeScript 早期的编译指令机制。reference path 声明文件依赖，reference types 声明包依赖，reference lib 引入标准库声明。到了 2026 年，它们的绝大多数功能已经被 import 语句和 tsconfig.json 替代。除非你在写 .d.ts 声明文件，否则让三斜线指令安静地待在历史文档里就好。