三斜杠指令

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

🌐 Triple-slash directives are single-line comments containing a single XML tag. The contents of the comment are used as compiler directives.

三斜杠指令仅在其所在文件的顶部有效。 三斜杠指令前只能是单行或多行注释，包括其他三斜杠指令。 如果它们出现在语句或声明之后，则会被视为普通单行注释，没有特殊含义。

🌐 Triple-slash directives are only valid at the top of their containing file. A triple-slash directive can only be preceded by single or multi-line comments, including other triple-slash directives. If they are encountered following a statement or a declaration they are treated as regular single-line comments, and hold no special meaning.

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

🌐 As of TypeScript 5.5, the compiler does not generate reference directives, and does not emit handwritten triple-slash directives to output files unless those directives are marked as preserve="true".

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

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

🌐 The /// <reference path="..." /> directive is the most common of this group. It serves as a declaration of dependency between files.

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

🌐 Triple-slash references instruct the compiler to include additional files in the compilation process.

它们还作为在使用 out 或 outFile 时对输出进行排序的一种方法。文件会按照预处理后的输入顺序输出到输出文件位置。

🌐 They also serve as a method to order the output when using out or outFile. Files are emitted to the output file location in the same order as the input after preprocessing pass.

预处理输入文件

🌐 Preprocessing input files

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

🌐 The compiler performs a preprocessing pass on input files to resolve all triple-slash reference directives. During this process, additional files are added to the compilation.

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

🌐 The process starts with a set of root files; these are the file names specified on the command-line or in the files list in the tsconfig.json file. These root files are preprocessed in the same order they are specified. Before a file is added to the list, all triple-slash references in it are processed, and their targets included. Triple-slash references are resolved in a depth-first manner, in the order they have been seen in the file.

如果使用相对路径，则相对于包含文件解析三斜杠引用路径。

🌐 A triple-slash reference path is resolved relative to the containing file, if a relative path is used.

错误

🌐 Errors

引用不存在的文件是错误的。 文件对自身有三斜杠引用是错误的。

🌐 It is an error to reference a file that does not exist. It is an error for a file to have a triple-slash reference to itself.

使用 --noResolve

🌐 Using --noResolve

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

🌐 If the compiler flag noResolve is specified, triple-slash references are ignored; they neither result in adding new files, nor change the order of the files provided.

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

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

🌐 Similar to a /// <reference path="..." /> directive, which serves as a declaration of dependency, a /// <reference types="..." /> directive declares a dependency on a package.

解析这些包名的过程类似于在 import 语句中解析模块名的过程。
将三斜杠引用类型指令（triple-slash-reference-types directives）看作声明包的 import 是一种简单的理解方式。

🌐 The process of resolving these package names is similar to the process of resolving module names in an import statement. An easy way to think of triple-slash-reference-types directives are as an import for declaration packages.

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

🌐 For example, including /// <reference types="node" /> in a declaration file declares that this file uses names declared in @types/node/index.d.ts; and thus, this package needs to be included in the compilation along with the declaration file.

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

🌐 For declaring a dependency on an @types package in a .ts file, use types on the command line or in your tsconfig.json instead. See using @types, typeRoots and types in tsconfig.json files for more details.

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

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

🌐 This directive allows a file to explicitly include an existing built-in lib file.

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

🌐 Built-in lib files are referenced in the same fashion as the lib compiler option in tsconfig.json (e.g. use lib="es2015" and not lib="lib.es2015.d.ts", etc.).

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

🌐 For declaration file authors who rely on built-in types, e.g. DOM APIs or built-in JS run-time constructors like Symbol or Iterable, triple-slash-reference lib directives are recommended. Previously these .d.ts files had to add forward/duplicate declarations of such types.

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

🌐 For example, adding /// <reference lib="es2017.string" /> to one of the files in a compilation is equivalent to compiling with --lib es2017.string.

ts
/// <reference lib="es2017.string" />
"foo".padStart(4);

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

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

🌐 This directive marks a file as a default library. You will see this comment at the top of lib.d.ts and its different variants.

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

🌐 This directive instructs the compiler to not include the default library (i.e. lib.d.ts) in the compilation. The impact here is similar to passing noLib on the command line.

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

🌐 Also note that when passing skipDefaultLibCheck, the compiler will only skip checking files with /// <reference no-default-lib="true"/>.

/// <amd-module />

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

🌐 By default AMD modules are generated anonymous. This can lead to problems when other tools are used to process the resulting modules, such as bundlers (e.g. r.js).

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

🌐 The amd-module directive allows passing an optional module name to the compiler:

amdModule.ts

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

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

🌐 Will result in assigning the name NamedModule to the module as part of calling the AMD define:

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 调用中注入的非 TypeScript 模块依赖。

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

🌐 The amd-dependency directive can also have an optional name property; this allows passing an optional name for an amd-dependency:

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

生成的 JS 代码：

🌐 Generated JS code:

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

preserve="true"

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

🌐 Triple-slash directives can be marked with preserve="true" to prevent the compiler from removing them from the output.

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

🌐 For example, these will be erased in the output:

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

但这些将被保留：

🌐 But these will be preserved:

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