三斜线指令

三斜线指令是包含单个 XML 标签的单行注释。 注释的内容用作编译器指令。

三斜线指令仅在其所在文件的顶部有效。 三斜线指令前面只能有单行或多行注释，包括其他三斜线指令。 如果在语句或声明之后遇到它们，它们将被视为普通的单行注释，不具有特殊含义。

从 TypeScript 5.5 开始，编译器不再生成引用指令，并且不会将手写的三斜线指令输出到文件中，除非这些指令被标记为 preserve="true"。

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

/// <reference path="..." /> 指令是这组中最常见的。 它用作文件之间的依赖声明。

三斜线引用指示编译器在编译过程中包含其他文件。

在使用 out 或 outFile 时，它们也用作对输出进行排序的方法。 文件在经过预处理后，将按照输入的顺序输出到输出文件位置。

预处理输入文件

编译器对输入文件执行预处理，以解析所有三斜线引用指令。 在此过程中，会将其他文件添加到编译中。

该过程从一组根文件开始； 这些是在命令行或 tsconfig.json 文件的 files 列表中指定的文件名。 这些根文件按照指定的顺序进行预处理。 在将文件添加到列表之前，会处理其中的所有三斜线引用，并包含其目标。 三斜线引用以深度优先的方式解析，按照它们在文件中出现的顺序。

如果使用相对路径，三斜线引用路径将相对于包含文件进行解析。

错误

引用不存在的文件是错误的。 文件包含对自身的三斜线引用也是错误的。

使用 --noResolve

如果指定了编译器标志 noResolve，则会忽略三斜线引用；它们既不会导致添加新文件，也不会改变所提供文件的顺序。

/// <reference types="..." />

与用作依赖声明的 /// <reference path="..." /> 指令类似，/// <reference types="..." /> 指令声明了对某个包的依赖。

解析这些包名的过程类似于解析 import 语句中的模块名的过程。 将三斜线引用类型指令视为声明包的 import 是一种简单的方式。

例如，在声明文件中包含 /// <reference types="node" /> 声明该文件使用了在 @types/node/index.d.ts 中声明的名称； 因此，该包需要与声明文件一起包含在编译中。

要在 .ts 文件中声明对 @types 包的依赖，请在命令行或 tsconfig.json 中使用 types。更多详情请参阅在 tsconfig.json 文件中使用 @types、typeRoots 和 types。

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

此指令允许文件显式包含现有的内置 lib 文件。

内置 lib 文件的引用方式与 tsconfig.json 中的 lib 编译器选项相同（例如使用 lib="es2015"，而不是 lib="lib.es2015.d.ts" 等）。

对于依赖内置类型（例如 DOM API 或内置 JS 运行时构造函数如 Symbol 或 Iterable）的声明文件作者，建议使用三斜线引用库指令。以前，这些 .d.ts 文件不得不添加此类类型的前向/重复声明。

例如，将 /// <reference lib="es2017.string" /> 添加到编译中的一个文件等同于使用 --lib es2017.string 进行编译。

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

"foo".padStart(4);

/// <reference no-default-lib="true"/>

此指令将文件标记为默认库。 你会在 lib.d.ts 及其不同变体的顶部看到此注释。

此指令指示编译器不将默认库（即 lib.d.ts）包含在编译中。 其影响类似于在命令行中传递 noLib。

另请注意，当传递 skipDefaultLibCheck 时，编译器将仅跳过检查带有 /// <reference no-default-lib="true"/> 的文件。

/// <amd-module />

默认情况下，AMD 模块是匿名生成的。 当使用其他工具处理生成的模块（如打包器，例如 r.js）时，这可能会导致问题。

amd-module 指令允许向编译器传递一个可选的模块名称：

amdModule.ts

/// <amd-module name="NamedModule"/>
export class C {}

这将导致在调用 AMD define 时将名称 NamedModule 分配给模块：

amdModule.js

define("NamedModule", ["require", "exports"], function (require, exports) {
  var C = (function () {
    function C() {}
    return C;
  })();
  exports.C = C;
});

/// <amd-dependency />

注意：此指令已弃用。请改用 import "moduleName"; 语句。

/// <amd-dependency path="x" /> 告知编译器存在一个非 TS 模块依赖，需要将其注入到生成的模块的 require 调用中。

amd-dependency 指令还可以有一个可选的 name 属性；这允许为 amd-dependency 传递一个可选的名称：

/// <amd-dependency path="legacy/moduleA" name="moduleA"/>
declare var moduleA: MyType;
moduleA.callStuff();

生成的 JS 代码：

define(["require", "exports", "legacy/moduleA"], function (
  require,
  exports,
  moduleA
) {
  moduleA.callStuff();
});

preserve="true"

三斜线指令可以用 preserve="true" 标记，以防止编译器将其从输出中移除。

例如，这些将在输出中被擦除：

/// <reference path="..." />
/// <reference types="..." />
/// <reference lib="..." />

但这些将被保留：

/// <reference path="..." preserve="true" />
/// <reference types="..." preserve="true" />
/// <reference lib="..." preserve="true" />