tsconfig.json 中 references属性的用法

在 TypeScript 的项目配置文件 tsconfig.json 中，references 选项用于设置项目之间的依赖关系，特别是在使用项目引用（Project References）的上下文中。项目引用是 TypeScript 3.0 引入的一个功能，旨在提高大型项目的编译效率和结构化管理。

项目引用的主要用途

1. 组织大型代码库：项目引用允许将大型代码库拆分成较小的、更易于管理的部分（子项目），每个部分可以独立编译，并且可以重用编译结果。
2. 增量编译：通过项目引用，TypeScript 可以进行增量编译，即只重新编译依赖关系中发生更改的部分，从而加快编译过程。
3. 代码隔离：项目引用有助于隔离代码，确保代码更改不会影响到不相关的部分，从而提高代码的稳定性和可维护性。

references 配置示例

references 选项是一个数组，其中的每个元素都指定了一个路径，这个路径指向项目所依赖的另一个 TypeScript 项目的 tsconfig.json 文件。

{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "outDir": "./lib",
    "baseUrl": "./",
    "paths": {
      "*": ["*", "./lib/*"]
    }
  },
  "include": ["src/**/*"],
  "references": [
    { "path": "../core" },
    { "path": "../utils" }
  ]
}

在这个例子中，当前项目依赖于同一代码库中的两个其他项目：core 和 utils。这些项目的目录相对于当前项目的 tsconfig.json 文件进行了配置。

使用场景

假设你有一个大型应用，它被分成了几个部分，比如核心功能库（core）、工具库（utils）和一个或多个应用层（app）。你可以为每部分创建一个单独的 tsconfig.json 文件，然后在应用层的配置中通过 references 指定对核心库和工具库的依赖。这样，当你开发应用层时，TypeScript 编译器可以利用已经编译好的核心库和工具库，加快编译速度。

注意事项

• 使用项目引用时，每个被引用的项目应在其 tsconfig.json 中设置 composite 选项为 true。这个选项使得 TypeScript 编译器可以处理项目之间的依赖关系。
• 项目引用的结构需要仔细规划，以确保依赖关系清晰且合理，避免循环依赖的问题。
• 在使用项目引用的多项目结构中，使用命令行工具如 tsc -b （构建模式）可以有效管理项目的编译过程。

通过合理使用 tsconfig.json 中的 references 选项，你可以更好地管理和编译大型 TypeScript 项目，提高开发效率和代码的可维护性。