TypeScript三斜线指令从入门到理解为何不再需要

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

/// 这个指令一共有四个属性：path、types、lib、no-default-lib。先说第一个，也是最有故事的一个。

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

lib 属性是用来引入 TypeScript 内置的类型声明库的。它告诉编译器：当前代码预期运行在哪种 JavaScript 环境里——包括语言标准库版本和宿主 API。

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

这里必须澄清一个容易混淆的地方：lib 影响的是类型检查时可用的内置类型（比如 Promise、document），但不影响编译输出的语法版本——那是 target 的事。而且 TypeScript 编译环境本身的版本与 JavaScript 版本并非严格一一对应，它通过 lib 来“模拟”对某个环境的类型支持。

在单文件中用 lib 属性指定环境的情况不多，比如下面这个例子，告诉编译器使用 es2017 版本的字符串类型来编译当前模块：

/// 
"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                // 保持默认，不需要设为 true
  },
  "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 参数

如果你不想让三斜线指令生效，可以使用 --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 取代了。但如果需要维护老项目，理解这个机制仍然很有必要。