TypeScript三斜线指令完全指南：为何不再需要它

1. TypeScript 三斜线指令详解：///

/// 指令包含四个核心属性：path、types、lib 和 no-default-lib。下面先从最具历史意义的 path 属性开始介绍。

1.1. path 属性：文件依赖的早期解决方案

/// 是 TypeScript 早期模块化的重要机制。在 JavaScript 尚未支持 import/export 时，TypeScript 通过三斜线指令解决文件间的依赖关系。该指令通常与 outFile 搭配使用，通过指定文件路径声明依赖关系，并控制多个文件合并为一个 JS 文件时的输出顺序。详细历史可参考 TypeScript 官方文档的旧版说明。

如今，这一方式已被 ESModule 完全取代。TypeScript 保留该指令主要是为了兼容老项目或遗留代码。在支持 ESModule 的环境中无需使用该指令，混用反而增加复杂度。

重要提醒：使用三斜线指令的文件不能混用 import/export 语法，否则指令会失效，被视为普通注释。

1.2. types 属性：引入第三方类型声明

types 属性用于在当前模块中引入第三方类型声明库（即 @types/）。默认加载索引文件 index.d.ts，若非索引文件，需指定具体文件名。

/// 
/// 

该指令仅在当前文件内生效（局部作用域）。若需全局生效，应在 tsconfig.json 中配置。

{
  // ...
  "compilerOptions": {
    // ...
    "types": ["vite/client"]   // 对应 @types/vite/client.d.ts
  }
}

1.3. lib 属性：指定 JavaScript 运行时环境

lib 属性用于引入 TypeScript 内置的类型声明库，告知编译器当前代码预期运行在何种 JavaScript 环境中，包括语言标准库版本及宿主 API。

不同环境（如 ES5、ES2020、浏览器 DOM、WebWorker）对应不同的内置类型集合，TypeScript 为此预置了相应的类型声明文件（例如 es2020、dom）。

需注意：lib 影响的是类型检查时可用的内置类型（如 Promise、document），但不影响编译输出的语法版本——后者由 target 控制。TypeScript 编译环境版本与 JavaScript 版本并非严格对应，通过 lib 来“模拟”特定环境的类型支持。

以下示例在单个文件中使用 lib 属性指定环境：

/// 
"foo".padStart(4);

通常，我们会在 tsconfig.json 中统一配置编译器版本与产物版本，全局生效，无需每个文件重复配置。

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "lib": [
      "ES2020", // Typescript 编译器版本
      "DOM", // 浏览器环境 DOM
      "DOM.Iterable"
    ]
  }
}

1.4. no-default-lib 属性：自定义默认库

该指令将当前文件标记为默认库。在 lib.d.ts 及其变体文件的顶部可以看到此注释。它告知编译器不要在编译中包含默认库（即 lib.d.ts），效果等价于命令行参数 --noLib。

TypeScript 官方使用该标记标识其内置库文件。

/// 
interface Array {
  // ... 类型定义
}

你可以自定义一个默认库，覆盖 TypeScript 内置类型。例如，以下代码完全覆盖内置的 Array，全局 Array 仅保留一个 first 方法：

// custom-lib.d.ts
/// 
interface Array {
  first: () => T // 修改内置的 Array
}

定义自定义库后，需在配置文件中指定该文件，使其作为全局默认库：

{
  "compilerOptions": {
    "lib": [],                    // 禁用内置库（或省略，因自定义库会覆盖）
    "noLib": false                // 保持默认
  },
  "files": [
    "custom-lib.d.ts",            // 必须放在最前面
    "main.ts"
  ]
}

此外，tsconfig.json 中 noLib 配置项会禁用所有内置库，导致所有类型报错。而本节的指令仅作用于当前文件，两者作用域不同。

{
  "compilerOptions": {
    "noLib": true   // 禁用所有内置默认库
  }
}

const arr = [1, 2, 3];     // 找不到名称 'Array'
console.log('hello');      // 找不到名称 'console'
const str = 'hello';       // 找不到名称 'String'

为提高性能，可在配置中设置 skipDefaultLibCheck 跳过自定义默认库的类型检查。

{
  "compilerOptions": {
    "skipDefaultLibCheck": true,   // 跳过检查
  },
}

1.5. preserve 属性：保留三斜线指令

preserve="true" 属性告知编译器：不要从输出中删除三斜线指令。某些构建工具（如需要引用 sourcemap 等场景）要求输出文件中保留这些指令。

/// 
// 某些构建工具需要这些指令在输出文件中存在

/// 
// 输出后仍然保持对类型文件的引用

/// 
// 让生成的文件明确标识依赖关系

2. /// ：显式指定 AMD 模块名称

此指令专用于 AMD 模块编译场景，显式指定模块名称，解决匿名模块带来的问题。

前提：tsconfig.json 中 module 必须设为 amd，打包产物才为 AMD 格式。

{
  "compilerOptions": {
    "module": "amd",           // 必须设置为 AMD
    "outFile": "./dist/bundle.js",
    "target": "es5"
  }
}

默认情况下，编译出的 AMD 模块代码为匿名。例如文件 math.ts：

// math.ts
export function add(a: number, b: number) {
    return a + b;
}

编译后：

// math.js (AMD 格式)
define(["require", "exports"], function(require, exports) {
    function add(a, b) {
        return a + b;
    }
    exports.add = add;
});

添加 /// 后，编译结果将包含名称：

/// 
export function add(a: number, b: number) {
    return a + b;
}

// math.js (AMD 格式，有名称)
define("math", ["require", "exports"], function(require, exports) {
  function add(a, b) {
     return a + b;
  }
  exports.add = add;
});

3. /// （已弃用）

此指令已弃用，现在可直接使用 import "moduleName"; 语句。它曾作为 /// 的增强版，可额外指定依赖模块。

/// 
declare var moduleA: MyType;
moduleA.callStuff();

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

4. 忽略三斜线指令

如需禁用三斜线指令，可使用 --noResolve 参数编译文件，或在 tsconfig.json 中配置 noResolve: true（默认值为 false，即启用指令）。

// utils.ts
export function log(msg: string) {
  console.log(msg);
}// main.ts
/// 
log("Hello");  // 使用 utils.ts 中的函数

使用 --noResolve 编译：

# 编译成功，bundle.js 包含 utils.ts 的内容
tsc main.ts --outFile bundle.js
tsc main.ts --outFile bundle.js --noResolve
# 编译失败！因为找不到 log 函数（utils.ts 没有被包含）

也可在 tsconfig.json 中全局关闭：

{
  "compilerOptions": {
    "noResolve": true   // 关闭
  }
}

5. outFile 与 /// 的协作机制

编译器对输入文件进行预处理：从根文件开始（命令行指定的文件或 tsconfig.json 中的 files 列表），按根文件指定的顺序处理。遇到 /// 指令时，将目标文件加入编译，采用深度优先方式，按指令在文件中的出现顺序解析。最终，所有文件按照预处理后的顺序输出到 outFile 指定的单一文件中。

outFile 仅在 module 设置为 amd、system 或 none 时生效。若设置为 commonjs 或 es2015，会报错或忽略此选项。

{
  "compilerOptions": {
    "module": "amd",           // 必须为 'amd'、'system' 或 'none'
    "target": "es5",
    "outFile": "./dist/bundle.js"   // 合并输出的单一文件
  },
  "files": [
    "./src/main.ts"            // 入口文件，会递归处理其中的 reference 指令
  ]
}

如需明确顺序，可在 files 中直接指定：

{
  "compilerOptions": {
    "module": "none", 
    "outFile": "./dist/app.js"
  },
  "files": [
    "./src/utils.ts",    // 先输出
    "./src/models.ts",   // 再输出
    "./src/main.ts"      // 最后输出（依赖前两个）
  ]
}

在文件中使用三斜线指令声明依赖，编译器按指令顺序处理：

// main.ts
/// 
/// 
// 代码中使用 utils 和 models 的内容

在现代开发中，该方案已被打包工具（Webpack、Rollup、Vite）配合 ESModule 取代。但若需维护老项目，理解这一机制仍然很有必要。