26 | 配置tsconfig.json（1）：文件选项

在TypeScript的开发旅程中，tsconfig.json文件扮演着至关重要的角色。它是TypeScript编译器的配置文件，通过定义一系列编译选项，指导编译器如何处理和转换.ts（TypeScript）文件。这些选项涵盖了从文件处理、编译目标、类型检查到代码优化等多个方面。本章节将深入探讨tsconfig.json中的文件相关选项，帮助读者更好地理解和应用这些配置，以优化TypeScript项目的开发和构建过程。

引言

tsconfig.json文件位于项目的根目录下，是TypeScript项目的核心配置文件。它基于JSON格式，包含了编译器在编译项目时需要遵循的一系列指令。这些指令覆盖了代码的编译范围、输出格式、模块系统、类型检查严格程度等多个维度。在探讨文件选项之前，理解tsconfig.json的基本结构和工作原理是必要的。

tsconfig.json基本结构

一个基本的tsconfig.json文件可能看起来像这样：

{
  "compilerOptions": {
    // 编译器选项
  },
  "include": [],
  "exclude": [],
  "files": [],
  "references": [],
  "extends": "",
  "compileOnSave": false,
  "typeAcquisition": {
    // 类型获取选项
  },
  // 其他高级选项...
}

其中，与文件直接相关的选项主要包括files、include、exclude和references。这些选项定义了哪些文件应该被TypeScript编译器包含或排除在编译过程中。

文件选项详解

1. files

files选项允许你明确指定需要编译的TypeScript文件列表。当使用files选项时，只有列出的文件会被编译。如果同时使用了include和files，files中的文件列表将覆盖include指定的文件集。这在处理小型项目或需要精确控制编译哪些文件时非常有用。

示例：

{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs"
  },
  "files": [
    "src/main.ts",
    "src/utils/helper.ts"
  ]
}

在这个例子中，只有main.ts和helper.ts两个文件会被编译。

2. include

include选项允许你通过模式匹配来指定哪些文件应该被TypeScript编译器包含。这个选项通常与通配符（如*、?、**/*）结合使用，以匹配特定路径下的文件或文件夹。与files不同，include提供了一种更灵活的方式来指定编译范围，特别适用于大型项目。

示例：

{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs"
  },
  "include": [
    "src/**/*", // 包含src目录下的所有文件
    "tests/**/*.ts" // 包含tests目录下所有的TypeScript文件
  ]
}

在这个例子中，src目录下的所有文件以及tests目录下所有以.ts结尾的文件都会被编译。

3. exclude

尽管include选项提供了强大的文件包含机制，但有时候我们还需要排除某些文件或目录。这时，exclude选项就派上了用场。exclude选项同样支持模式匹配，用于指定哪些文件或目录应该被TypeScript编译器忽略。需要注意的是，exclude选项不会排除通过files选项明确指定的文件。

示例：

{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs"
  },
  "include": [
    "src/**/*"
  ],
  "exclude": [
    "src/node_modules/**/*", // 排除src目录下的node_modules文件夹
    "src/tests/**/*" // 假设你不想在编译过程中包含测试文件
  ]
}

然而，在实际项目中，通常不需要手动排除node_modules目录，因为TypeScript编译器默认会忽略它。此示例主要是为了说明exclude的用法。

4. references

随着项目规模的扩大，可能需要将项目拆分成多个独立的模块或包，并通过TypeScript的项目引用（Project References）功能来管理它们之间的依赖关系。references选项正是为了支持这一功能而设计的。它允许你指定一个或多个tsconfig.json文件作为当前项目的引用，这些被引用的项目将首先被编译。

示例：

{
  "references": [
    { "path": "../lib" },
    { "path": "../utils" }
  ]
}

在这个例子中，当前项目依赖于位于上一级目录中的lib和utils项目。TypeScript编译器会先编译这两个项目，然后再编译当前项目，从而确保依赖的正确性。

小结

tsconfig.json中的文件选项（files、include、exclude、references）为TypeScript项目提供了灵活而强大的文件管理能力。通过合理配置这些选项，开发者可以精确控制哪些文件应该被编译，哪些文件应该被忽略，以及如何处理项目间的依赖关系。这不仅有助于提升项目的可维护性，还能优化编译性能，加快开发迭代速度。

在实际开发中，建议根据项目规模和需求合理选择和使用这些选项。对于小型项目，可能只需简单配置files或include即可；而对于大型项目，则可能需要充分利用include、exclude以及references等选项来构建复杂的项目结构和依赖关系。无论项目大小，深入理解并掌握这些文件选项都将对TypeScript项目的开发产生积极影响。