tsconfig.json 详解

Question

一、简介

tsconfig.json 是 TypeScript 编译器的配置文件，用于指定编译 TypeScript 代码时的编译选项和编译目标等信息。通过修改该文件，可以定制 TypeScript 编译器的行为，例如指定编译目标、启用或禁用特定的语言特性、设置代码检查规则等。

1.1 与 jsconfig.json 的关系

jsconfig.json 源自 tsconfig.json，默认启用了一些与 JavaScript 相关的编译选项，常用于 JavaScript 项目。可以简单理解为设置了 allowJs 为 true 的 tsconfig.json。

比如，当我们使用 Webpack Alias 时，可以往 jsconfig.json 里添加 baseUrl、paths 配置以获得路径智能提示，提高开发体验。

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

1.2 创建 tsconfig.json

方式有二。一是利用 tsc --init 命令添加（详见）。

$ cd /path/to/project
$ npm init -y
$ npm i typescript -D
$ npx tsc --init

Created a new tsconfig.json with:                                                       
  target: es2016
  module: commonjs
  strict: true
  esModuleInterop: true
  skipLibCheck: true
  forceConsistentCasingInFileNames: true


You can learn more at https://aka.ms/tsconfig

二是手动添加，然后参考 TSConfig bases，借鉴各种框架的配置示例，也可直接安装对应 @tsconfig/xxx 包并使用 extends 继承配置。

1.3 选择编译配置

通常，若目录下存在 tsconfig.json 文件，则表示该目录是 TypeScript 项目的根目录。尽管如此，在用法上还是要注意。

# 1️⃣
$ tsc

# 2️⃣
$ tsc index.ts

# 3️⃣
$ tsc --project /path/to/your_tsconfig.json

以上三种方式，编译时的配置稍有不同：

• 1️⃣ 无输入文件的情况下调用 tsc，编译器会从当前目录开始并逐级向上检索 tsconfig.json 文件作为其编译配置。若一直找不到，则使用默认配置。
• 2️⃣ 有输入文件的情况下调用 tsc，编辑器将会使用默认配置。
• 3️⃣ 指定 --project 或 -p 参数情况下调用 tsc，编译器将会使用该路径下的配置文件。

如果你是刚接触，可参考 TSConfig bases 选择适合你所用框架的配置。

1.4 配置优先级

CLI Options > 项目 tsconfig.json 配置 > 默认配置

二、配置选项

tsconfig.json 里配置选项很多，超过 100 个。

2.1 顶级选项（Root Fields）

顶级选项有这几个：

{
  "compileOnSave": true,
  "vueCompilerOptions": {},
  "compilerOptions": {},
  "watchOptions": {},
  "include": [],
  "exclude": [],
  "files": [],
  "typeAcquisition": {},
  "references": [],
  "extends": [],
  "buildOptions": {},
  "ts-node": {}
}

还包括 Vue.js 中会用到的 vueCompilerOptions 选项等。

2.1.1 compileOnSave

启用该选项，可以让 IDE/Editor 在保存文件时自动编译。

请注意，它（目前）并没有得到 Visual Studio Code 的支持。仅在 Visual Studio 2015 和安装了 atom-typescript 插件的 Atom 中得到了支持。而该插件和 Atom 均已停止维护。

2.1.2 compileerOptions

该选项是 TypeScript 配置的重头戏，下文再详细介绍。

2.1.3 files

该选项用于指定待编译的文件，接受一个字符串数组，可以是相对路径或绝对路径，但不能是 Glob 模式。

注意点：

• 如果指定了 files 选项，则只有指定的文件才会被编译，其他文件会被忽略；
• 如果 files 内指定的文件引用了其他模块，这些模块也会被编译。
• 当使用了 files 选项，通常还会指定 compilerOptions.outFile 或 compilerOptions.outDir 选项以便编译器将编译结果输出到指定文件中。
• 如果指定了 files，include 的默认值为 []，否则为 ["**"]。

2.1.4 include

该选项类似于 files 字段，同样用于指定编译器应该包含哪些文件进行编译，未指定时默认编译根目录下所有 TypeScript 文件。区别在于，include 支持 Glob 模式来指定文件路径。

include 和 exclude 支持 Glob 模式如下：

* 匹配零个或多个字符（除了路径分隔符 /）。
? 匹配一个字符（除了路径分隔符 /）。
**/ 匹配零个或多个目录及其子目录。

若 Glob 模式未指定文件扩展名时，默认支持 .ts、.tsx 和 .d.ts。若 allowJs 为 true，还包括 .js 和 .jsx。

2.1.5 exclude

该选项用于指定 include 里面需要忽略的文件。exclude 的默认值为 ["node_modules", "bower_components", "jspm_packages"]，但排除文件还包括 outDir 指定值。

以下示例将会忽略的文件为 ["node_modules", "bower_components", "jspm_packages", "dist"]。

{
  "compilerOptions": {
    "outDir": "dist"
  },
  "exclude": []
}

请注意，exclude 字段只影响由 include 字段指定的文件和目录中包含哪些文件，而不会完全排除在 exclude 中列出的文件。也就是说，如果一个文件在 exclude 中列出，但是它被代码中的 import 语句、/// <reference 或者在 files、types 字段中的文件中引用，那么这个文件仍然会被编译。

Related Link

• What is jsconfig.json?
• What is a tsconfig.json?
• TSConfig Reference
• tsc CLI Options