26 | 配置tsconfig.json（1）：文件选项-TypeScript开发实战

当前位置:　首页>> 技术小册>> TypeScript开发实战

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

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

#### 引言

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

#### `tsconfig.json`基本结构

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

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

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

#### 文件选项详解

##### 1. `files`

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

**示例**：

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

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

##### 2. `include`

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

**示例**：

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

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

##### 3. `exclude`

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

**示例**：

```json
{
  "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`文件作为当前项目的引用，这些被引用的项目将首先被编译。

**示例**：

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

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

#### 小结

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

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

该分类下的相关小册推荐：

剑指TypeScript

TypeScript 全面进阶指南

TypeScript入门指南