了不起的 tsconfig.json 指南

在 TypeScript 开发中，tsconfig.json 是个不可或缺的配置文件，它是我们在 TS 项目中最常见的配置文件，那么你真的了解这个文件吗？它里面都有哪些优秀配置？如何配置一个合理的 tsconfig.json 文件？本文将全面带大家一起详细了解 tsconfig.json 的各项配置。


本文将从以下几个方面全面介绍 tsconfig.json 文件：



水平有限，欢迎各位大佬指点~~

一、tsconfig.json 简介

1. 什么是 tsconfig.json

TypeScript 使用 tsconfig.json 文件作为其配置文件，当一个目录中存在 tsconfig.json 文件，则认为该目录为 TypeScript 项目的根目录。
通常 tsconfig.json 文件主要包含两部分内容：指定待编译文件和定义编译选项。


从《TypeScript编译器的配置文件的JSON模式》可知，目前 tsconfig.json 文件有以下几个顶层属性：

• compileOnSave
• compilerOptions
• exclude
• extends
• files
• include
• references
• typeAcquisition

文章后面会详细介绍一些常用属性配置。

2. 为什么使用 tsconfig.json

通常我们可以使用 tsc 命令来编译少量 TypeScript 文件：

/*
  参数介绍：
  --outFile // 编译后生成的文件名称
  --target  // 指定ECMAScript目标版本
  --module  // 指定生成哪个模块系统代码
  index.ts  // 源文件
*/
$ tsc --outFile leo.js --target es3 --module amd index.ts

但如果实际开发的项目，很少是只有单个文件，当我们需要编译整个项目时，就可以使用 tsconfig.json 文件，将需要使用到的配置都写进 tsconfig.json 文件，这样就不用每次编译都手动输入配置，另外也方便团队协作开发。

二、使用 tsconfig.json

目前使用 tsconfig.json 有2种操作：

1. 初始化 tsconfig.json

在初始化操作，也有 2 种方式：

1. 手动在项目根目录（或其他）创建 tsconfig.json 文件并填写配置；
2. 通过 tsc --init 初始化 tsconfig.json 文件。

2. 指定需要编译的目录

在不指定输入文件的情况下执行 tsc 命令，默认从当前目录开始编译，编译所有 .ts 文件，并且从当前目录开始查找 tsconfig.json 文件，并逐级向上级目录搜索。

$ tsc

另外也可以为 tsc 命令指定参数 --project 或 -p 指定需要编译的目录，该目录需要包含一个 tsconfig.json 文件，如：

/*
  文件目录：
  ├─src/
  │  ├─index.ts
  │  └─tsconfig.json
  ├─package.json
*/
$ tsc --project src

注意，tsc 的命令行选项具有优先级，会覆盖 tsconfig.json 中的同名选项。


更多 tsc 编译选项，可查看《编译选项》章节。

三、使用示例

这个章节，我们将通过本地一个小项目 learnTsconfig 来学着实现一个简单配置。
当前开发环境：windows / node 10.15.1 / TypeScript3.9

1. 初始化 learnTsconfig 项目

执行下面命令：

$ mkdir learnTsconfig
$ cd .\learnTsconfig\
$ mkdir src
$ new-item index.ts

并且我们为 index.ts 文件写一些简单代码：

// 返回当前版本号
function getVersion(version:string = "1.0.0"): string{
    return version;
}

console.log(getVersion("1.0.1"))

我们将获得这么一个目录结构：

  └─src/
     └─index.ts

2. 初始化 tsconfig.json 文件

在 learnTsconfig 根目录执行：

$ tsc --init

3. 修改 tsconfig.json 文件

我们设置几个常见配置项：

{
   
  "compilerOptions": {
   
    "target": "ES5",             // 目标语言的版本
    "module": "commonjs",        // 指定生成代码的模板标准
    "noImplicitAny": true,       // 不允许隐式的 any 类型
    "removeComments": true,      // 删除注释 
    "preserveConstEnums": true,  // 保留 const 和 enum 声明
    "sourceMap": true            // 生成目标文件的sourceMap文件
  },
  "files": [   // 指定待编译文件
    "./src/index.ts"  
  ]
}

其中需要注意一点：
 files 配置项值是一个数组，用来指定了待编译文件，即入口文件。
当入口文件依赖其他文件时，不需要将被依赖文件也指定到 files 中，因为编译器会自动将所有的依赖文件归纳为编译对象，即 index.ts 依赖 user.ts 时，不需要在 files 中指定 user.ts ， user.ts 会自动纳入待编译文件。

4. 执行编译

配置完成后，我们可以在命令行执行 tsc 命令，执行编译完成后，我们可以得到一个 index.js 文件和一个 index.js.map 文件，证明我们编译成功，其中 index.js 文件内容如下：

function getVersion(version) {
   
    if (version === void 0) {
    version = "1.0.0"; }
    return version;
}
console.log(getVersion("1.0.1"));
//# sourceMappingURL=index.js.map

可以看出，tsconfig.json 中的 removeComments 配置生效了，将我们添加的注释代码移除了。


到这一步，就完成了这个简单的示例，接下来会基于这个示例代码，讲解《七、常见配置示例》。

四、tsconfig.json 文件结构介绍

1. 按顶层属性分类

在 tsconfig.json 文件中按照顶层属性，分为以下几类：

2. 按功能分类

五、tsconfig.json 配置介绍

1. compileOnSave

compileOnSave 属性作用是设置保存文件的时候自动编译，但需要编译器支持。

{
   
	// ...
  "compileOnSave": false,</