三斜杠指令

三斜杠指令是包含单个 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 语句中解析模块名的过程。将三斜杠引用类型指令视为声明包的 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"; 语句。

¥Note: this directive has been deprecated. Use import "moduleName"; statements instead.

/// <amd-dependency path="x" /> 通知编译器需要在生成的模块的 require 调用中注入非 TS 模块依赖。

¥/// <amd-dependency path="x" /> informs the compiler about a non-TS module dependency that needs to be injected in the resulting module’s require call.

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