tsconfig.json 完全使用指南

鹏展博

6713字约22分钟

typescript

2022-04-28

TSConfig 文件是用于表明其所在的目录是一个 typescript 或 javascript 项目的根目录。 TSConfig 文件可以是 tsconfig.json 或 jsconfig.json，它们的配置和行为相同。

官方文档

基础

使用 TSConfig 是一个很容易的事情，只需要在目录下创建一个 tsconfig.json 或 jsconfig.json 文件即可：

tsconfig.json

{}

jsconfig.json

{}

TSConfig 包含了默认配置。

TSConfig 主要包含了以下 top level 的配置字段：

{
  "extends": "",
  "compilerOptions": {},
  "files": [],
  "include": [],
  "exclude": [],
  "references": [],
  "watchOptions": {},
  "typeAcquisition": {}
}

`extends`

Type： string

extends 属性用于从另一个 TSConfig 文件继承配置。它的值是一个路径，或者是一个 Node.js 风格的路径。如果是一个相对路径，则相对于配置文件对路径进行解析，如果是一个 Node.js 风格的路径，则从 node_modules解析获取路径。

extends 不会继承配置文件中的 files, include, exclude 字段，同时，不允许配置文件之间循环引用。

example

tsconfig.base.json

{
  "compilerOptions": {
    "noImplicitAny": true,
    "strictNullChecks": true
  }
}

tsconfig.json

{
  "extends": "./tsconfig.base",
  "files": ["main.ts"]
}

tsconfig.noStrictNullChecks.json

{
  "extends": "./tsconfig",
  "compilerOptions": {
    "strictNullChecks": false
  }
}

名称	内容
ES5	ES3 和 ES5 的核心功能定义
ES2015	ES2015 中额外提供的 API (又被称为 ES6) —— array.find， Promise，Proxy，Symbol，Map，Set，Reflect 等。
ES6	ES2015 的别名。
ES2016	ES2016 中额外提供的 API —— array.include 等。
ES7	ES2016 的别名。
ES2017	ES2017 中额外提供的 API —— Object.entries，Object.values，Atomics，SharedArrayBuffer，date.formatToParts，typed arrays 等。
ES2018	ES2018 中额外提供的 API —— async iterables，promise.finally，Intl.PluralRules，rexexp.groups 等。
ES2019	ES2019 中额外提供的 API —— array.flat，array.flatMap，Object.fromEntries，string.trimStart，string.trimEnd 等。
ES2020	ES2020 中额外提供的 API —— string.matchAll 等。
ESNext	ESNext 中额外提供的 API —— 随着 JavaScript 的发展，这些会发生变化。
DOM	DOM 定义 —— window，document 等。
WebWorker	WebWorker 上下文中存在的 API。
ScriptHost	Windows Script Hosting System 的 API。

DOM.Iterable， ES2015.Core， ES2015.Collection， ES2015.Generator， ES2015.Iterable， ES2015.Promise， ES2015.Proxy， ES2015.Reflect， ES2015.Symbol， ES2015.Symbol.WellKnown， ES2016.Array.Include， ES2017.object， ES2017.Intl， ES2017.SharedMemory， ES2017.String， ES2017.TypedArrays， ES2018.Intl， ES2018.Promise， ES2018.RegExp， ES2019.Array， ES2019.Full， ES2019.Object， ES2019.String， ES2019.Symbol， ES2020.Full， ES2020.String， ES2020.Symbol.wellknown， ESNext.AsyncIterable， ESNext.Array， ESNext.Intl， ESNext.Symbol

moduleDetection

模块检查。

auto (default): typescript 会不仅检查 import 或 export 语句，还会检查 package.json 是否有 type 字段，且当配置文件中 module 值是否为 nodenext 或 node16时，type 字段值为 module。以及检查。当使用 jsx: react-jsx 配置时，当前文件是否是 jsx 文件。
legacy: 检查文件是否包含检查 import 或 export 语句。
force : 确保每个非声明文件都被视为是一个模块。

noLib

禁用自动包含任何库文件。如果设置了该选项，lib将被忽略。

reactNamespace

已弃用，改用 `jsxFactory

target

编译目标

现代浏览器支持全部 ES6 的功能，所以 ES6 是一个不错的选择。如果你的代码部署在旧的环境中，你可以选择设置一个更低的目标；如果你的代码保证会运行在新的环境中，你可以选择一个更高的目标。

target 的配置将会改变哪些 JS 特性会被降级，而哪些会被完整保留例如，如果 target 是 ES5 或更低版本，箭头函数 () => this 会被转换为等价的函数表达式。

改变 target 也会改变 lib 选项的默认值。你可以根据需要混搭 target 和 lib 的配置，你也可以为了方便只设置 target。

特殊的 ESNext 值代表你的 TypeScript 所支持的最高版本。这个配置应当被谨慎使用，因为它在不同的 TypeScript 版本之间的含义不同，并且会导致升级更难预测。

可选值： es3 (default)， es5， es6/es2015， es2016， es2017， es2018， es2019， es2020， es2021， es2022， esnext

useDefineForClassFields

diagnostics

explainFiles

extendedDiagnostics

generateCpuProfile

listEmittedFiles

listFiles

traceResolution

composite

composite 选项会强制执行某些约束，使得构建工具（包括在 --build 模式下的 TypeScript 本身）可以快速确定一个工程是否已经建立。

当此设置开启时：

如果没有明确指定 rootDir，则默认为包含 tsconfig.json 文件的目录。
所有实现的文件必须由 include 来匹配，或在 files 数组中指定。如果违反了这一约束，tsc 将告诉你哪些文件没有被指定。
declaration 默认为 true。

disableReferencedProjectLoad

disableSolutionSearching

disableSourceOfProjectReferenceRedirect

incremental

使 TypeScript 将上次编译的工程图信息保存到磁盘上的文件中。这将会在您编译输出的同一文件夹中创建一系列 .tsbuildinfo 文件。它们不会再运行时被您的 JavaScript 使用，并且可以被安全的删除。

tsBuildInfoFile

这个选项可以让您指定一个文件来存储增量编译信息，以作为复合工程的一部分，从而可以更快的构建更大的 TypeScript 代码库。

这个选项提供了一种方法，可以配置 TypeScript 追踪它存储在磁盘上的文件的位置，用来指示项目的构建状态。—— 默认情况下，它们与你生成的 JavaScript 在同一个文件夹中。

noErrorTruncation

启用时，错误信息不会被截断。

preserveWatchOutput

是否在控制台保留历史监听信息，而不是清空它们。

pretty

是否使用颜色和样式格式化输出信息。

skipDefaultLibCheck

使用 skipLibCheck 此配置。

skipLibCheck

跳过声明文件的类型检查。

这可以在编译期间节省时间，但代价是类型系统的准确性。例如，两个库可以以不一致的方式定义同一类型的两个副本。TypeScript不会对所有d.ts文件进行全面检查，而是会对你在应用源代码中特别引用的代码进行类型检查。

assumeChangesOnlyAffectDirectDependencies

当这个选项被启用时，TypeScript将避免重新检查/重建所有可能真正受影响的文件，只检查/重建已经更改的文件以及直接导入这些文件的文件。

这可以被认为是监视算法的“快速和松散”实现，它可以大幅减少增量重建时间，代价是不得不偶尔运行完整的构建以获得所有编译器错误消息。

`files`

Types： string[]

显式的指定需要编译的文件列表。

如果列表中的文件不存在，则会发生错误。

example

{
  "files": ["main.ts", "core.ts", "shared.ts", "utils.ts"]
}

`include`

Type: string[]

指定需要编译的文件列表，可以是目录，文件，也可以是模式匹配。这些文件路径是相对于包含tsconfig.json的目录进行解析。

example

{
  "include": ["src/**/*.ts", "test/**/*.ts"]
}

它将会匹配：

.
├── scripts                ⨯
│   ├── lint.ts            ⨯
│   ├── update_deps.ts     ⨯
│   └── utils.ts           ⨯
├── src                    ✓
│   ├── client             ✓
│   │    ├── index.ts      ✓
│   │    └── utils.ts      ✓
│   ├── server             ✓
│   │    └── index.ts      ✓
├── tests                  ✓
│   ├── app.test.ts        ✓
│   ├── utils.ts           ✓
│   └── tests.d.ts         ✓
├── package.json
├── tsconfig.json
└── yarn.lock

patterns

include 和 exclude 支持使用通配符模式匹配：

* 匹配零个到多个字符（不包含目录分隔符）
? 匹配任意一个字符（不包含目录分隔符）
**/ 匹配任意嵌套深度的目录

`exclude`

Type: string[]

指定在解析 include 包含的文件时，应该跳过的文件列表，可以是目录，文件，也可以是模式匹配。

example

{
  "exclude": ["src/**/*.spec.ts"]
}

提示： exclude 仅排除已包含在 include 设置中的文件。但有时候即使exclude 已配置了排除某个文件，但在代码中仍然使用import 语句引入该文件，或在 types 中包含该文件，或通过 /// <reference 引入， typescript 仍然会编译它。

exclude 并不是一个阻止文件被包含代码组织里的机制，它只是作用于 include 查找文件时排除文件。

`references`

Type： { path: string }[]

项目引用是一种将TypeScript项目解构为更小片段的方法。使用项目引用可以大大提高构建和编辑器交互时间，加强组件之间的逻辑分离，并以新方式改进代码组织。

`watchOptions`

配置typescript编译器监听文件和目录的行为。

当使用命令行 --watch 启用编译器编译器会使用 fs.watch 和 fs.watchFile 对文件和目录进行监听，但两种方式各有利弊。

fs.watch 使用 file system events 通知文件和目录的变更。但它依赖于操作系统，并且通知并不可靠，在许多操作系统上并不能正常工作。此外，它还限制了创建监听数量，在一些操作系统上如 linux，我们可能会因为包含很多文件的大型项目而很快耗尽它。但由于它是使用的 file system events，它不会消耗过多的 CPU cycle 。在typescript编译器中，使用fs.watch用于监听允许精度缺失的目录变更（配置文件的 include，或者模块解析失败的目录）。

但只有 Windows 和 OSX 支持递归监听，这意味着在其他系统上需要通过其它方式来支持递归监听。

fa.watchFile 通过轮询的方式实现监听，因此需要消耗比较多的 CPU cycle 。但是 fs.watchFile 是获取 目录/文件 状态更新的最可靠的方式。编译器使用 fs.watchFile 监听源文件、配置文件和缺失文件引用。

{
  "watchOptions": {
    "watchFile": "",
    "watchDirectory": "",
    "fallbackPolling": "",
    "synchronousWatchDirectory": true,
    "excludeDirectories": [],
    "excludeFiles": []
  }
}

`watchFile`

配置监听单个文件的策略。支持以下可选值：

	描述
`fixedPollingInterval`	每秒钟以固定时间间隔多次检查文件变更
`priorityPollingInterval`	使用 `fs.watchFile` 轮询检查文件变更。但对源文件、配置文件、和缺失文件使用不同的时间间隔
`dynamicPriorityPolling`	使用动态队列的方式轮询检查文件变更。对于频繁变更的文件使用较短的时间间隔检查，对于低频变更的文件使用较长的时间间隔检查
`useFsEvents` default	使用 `fs.watch`(file system events) 监听文件变更（但在某些操作系统上可能不能正常监听变更）, 当超过了系统允许创建的监听数量限制时使用 `fs.watchFile`替代
`useFsEventsOnParentDirectory`	使用 `fs.watch`(file system events) 监听文件的父目录的变更，精度较低

`watchDirectory`

配置在缺失递归文件监听功能的系统上，监听整个目录的策略。支持以下可选值：

	描述
`fixedPollingInterval`	每秒钟以固定时间间隔多次检查所有目录变更
`dynamicPriorityPolling`	使用动态队列的方式轮询检查目录变更。对于频繁变更的目录使用较短的时间间隔检查，对于低频变更的目录使用较长的时间间隔检查
`useFsEvents` default	使用 `fs.watch`(file system events) 监听目录变更（但在某些操作系统上可能不能正常监听变更）

`fallbackPolling`

在使用文件系统事件时，此选项指定在系统耗尽本机文件监视器和/或不支持本机文件监视器时使用的轮询策略。

	描述
`fixedPollingInterval`	每秒钟以固定时间间隔多次检查文件变更
`priorityPollingInterval`	使用 `fs.watchFile` 轮询检查文件变更。但对源文件、配置文件、和缺失文件使用不同的时间间隔
`dynamicPriorityPolling`	使用动态队列的方式轮询检查文件变更。对于频繁变更的文件使用较短的时间间隔检查，对于低频变更的文件使用较长的时间间隔检查
`synchronousWatchDirectory`	禁用目录的延迟监视。当大量文件更改可能同时发生时(例如，运行npm install导致node_modules发生更改)，延迟监视是有用的，但在一些不太常见的设置中，你可能想用这个标志禁用它。

`synchronousWatchDirectory`

在不支持本地递归监听的平台上同步调用回调并更新目录监听器的状态。而不是给一个小的超时，以允许在一个文件上可能发生多次编辑。

{
  "watchOptions": {
    "synchronousWatchDirectory": true
  }
}

`excludeDirectories`

Type: string[]

配置不需要被监听的目录。此配置可以减少需要被监听的文件数量。

`excludeFiles`

Type: string[]

配置不需要被监听的文件。此配置可以减少需要被监听的文件数量。

`typeAcquisition`

指向项目类型获取的行为。

类型获取只有在 javascript 中有重要作用。在 javascript 项目中， typescript 工具会在后台或者 node_modules外部下载模块的类型声明。

而在 typescript 项目中，你需要显式的在项目中指定包含的类型。

{
  "typeAcquisition": {
    "enable": true,
    "include": [],
    "exclude": [],
    "disableFilenameBasedTypeAcquisition": true
  }
}

`enable`

指定是否在 javascript 项目中是否启用类型获取。

`include`

显式的声明需要包含的依赖类型。用于在 javascript项目中帮助typescript工具理解依赖跟踪，或者 disableFilenameBasedTypeAcquisition 设置为true时需要手动添加依赖。

example

  "typeAcquisition": {
    "include": ["lodash"],
  }
}

`exclude`

禁用某些模块的类型获取，这对于在测试基础设施中包含主应用程序不需要的其他库的项目非常有用。

example

  "typeAcquisition": {
    "exclude": ["jest", "mocha"],
  }
}

`disableFilenameBasedTypeAcquisition`

TypeScript的类型获取可以根据项目中的文件名推断应该添加什么类型。这意味着在你的项目中有一个像 JQuery 这样的文件会自动从 DefinitelyTyped 下载JQuery的类型。