三斜线指令

三斜线指令是包含单个 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），建议使用三斜线引用 lib 指令。以前，这些 .d.ts 文件必须添加此类类型的前向/重复声明。

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

ts
/// <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

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

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

amdModule.js

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" /> 通知编译器有关需要在生成的模块的 require 调用中注入的非 TS 模块依赖项。

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

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

生成的 JS 代码

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

preserve="true"

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

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

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

但这些将被保留

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