三斜線指令

三斜線指令是包含單個 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" />