TypeScript 编译选项之tsconfig.json

TypeScript 编译选项之tsconfig.json

tsconfig.json是 ts编译器的配置文件， ts编译器是根据这个配置文件来进行编译代码的，一般我们会把 tsconfig.json这个文件，放在工程的根目录下，所以可以通过 tsconfig.json来界定根目录.

选项配置详解

tsconfig.json文件的顶层属性有这些：files,include,exclude,compileOnSave, extends,typeAcquisition,watchOptions,reference,虽然顶层属性有这7个，但是我们实际项目中，常用的，也就那么几个，下面会详细说说，常用选项

1. files

数组类型，指定被编译的文件列表，只有需要编译少量文件才会用到。

{
  //配置项内容是一个数组列表
  "files": ["index.ts","system.ts","utils.ts"]
}

2. include

数组类型，用来指定，哪些文件需要被编译

{
  //配置项内容是一个数组列表
  "include": ["./src/**/*"]
}

表示需要编译当前目录下的src下的任意文件目录和任意文件

• **表示任意目录
• *表示任意文件

上述配置，是可以精确到相应目录和文件，指定来编译，如果我们不需要指定特定的某文件时，可以直接指定其根目录进行编译，就不用那么麻烦，比如直接指定src就可以

{
  "include": ["src",'libs']
}

3. exclude

数组类型，用来指定不需要被编译的文件，默认排除node_modules,一般在项目中，我们有不少文件是不需要被编译的，比如node_modules,dist等

{
  //配置项内容是一个数组列表
  "exclude": ["node_modules","dist"]
}

同include一样，也是可以精确到相应目录和文件的，如果我们不需要编译工程文件中的./src/hello是可以如下这样配置的。

{
  //配置项内容是一个数组列表
  "exclude": ["./src/hello/**/*","dist"]
}

4. extends

字符串类型，用于指定另外的配置文件路径，来继承这个配置文件里的配置，原文件配置会先被加载，如果有指定继承文件，继承文件会重写原文件里同属性的配置。比如：我想抽离一个tsconfig.base.json这样一个基础配置文件，然后再引入。extends在实际开发中用到的比较少用，了解即可

{
  "extends": "./tsconfig.base.json"
}

5. compilerOptions

对象类型，设置编译的选项。里面包含非常多的配置，也是tsconfig.json中最核心的配置,是需要我们重点来理解的。

{
  "include": ["src"],
  "exclude": ["node_modules","dist"],
  "compilerOptions": {
    //这里配置编译选项
  }
}

下面我们来详细列举compilerOptions中有哪些配置，有哪些作用

5.1 target

字符串类型，用来指定ts编译的目标版本，默认是ES3,有如下几个目标版本可以选择 (其中ESNext 表示目前最新的ES版本)

'es3', 'es5', 'es6', 'es2015', 'es2016', 'es2017', 'es2018', 'es2019', 'es2020', 'es2021', 'es2022', 'esnext'.

示例：

"compilerOptions": {
  "target": "es5"
}

5.2 module

字符串类型，用来指定使用模块化规范的标准，关于模块化规范的理解可以参考这里,相关模块化标准有如下几个选项可以配置：

'none', 'commonjs', 'amd', 'system', 'umd', 'es6', 'es2015', 'es2020', 'es2022', 'esnext', 'node12', 'nodenext'

示例：

"compilerOptions": {
  "module": "commonjs"
}

5.3 lib

数组类型，用于指定项目中需要使用到的库，目前有可以引用的库有如下选择

'es5', 'es6', 'es2015', 'es7', 'es2016', 'es2017', 'es2018', 'es2019', 'es2020', 'es2021', 'es2022', 'esnext', 'dom', 'dom.iterable', 'webworker', 'webworker.importscripts', 'webworker.iterable', 'scripthost', '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.sharedmemory', 'es2017.string', 'es2017.intl', 'es2017.typedarrays', 'es2018.asyncgenerator', 'es2018.asynciterable', 'es2018.intl', 'es2018.promise', 'es2018.regexp', 'es2019.array', 'es2019.object', 'es2019.string', 'es2019.symbol', 'es2020.bigint', 'es2020.promise', 'es2020.sharedmemory', 'es2020.string', 'es2020.symbol.wellknown', 'es2020.intl', 'es2021.promise', 'es2021.string', 'es2021.weakref', 'es2021.intl', 'es2022.array', 'es2022.error', 'es2022.object', 'es2022.string', 'esnext.array', 'esnext.symbol', 'esnext.asynciterable', 'esnext.intl', 'esnext.bigint', 'esnext.string', 'esnext.promise', 'esnext.weakref'

说明一下，我们在浏览器端，如果要使用dom库,是需要引用dom库的.还有如需要使用es的高级版本特性，通常都需要配置，如es8的数组新特性需要引入ES2019.Array

示例：

"compilerOptions": {
  "lib": ["dom","ES2015","ES2019.Array"]
}

5.4 outDir

字符串类型，用于指定编译后的文件存放的目录位置，一般我们会指定为./dist

"compilerOptions": {
  "outDir": "./dist"
}

5.5 outFile

字符串类型，用于将编译后的代码合并成一个文件，比如设置为：./dist/app.js但是需要注意一点：这个配置，只有设置module为amd或system,才支持

设置outFile后，所有全局作用域中的代码，会合并到同一个文件中。这个配置，我们一般不常用，因为不灵活，如果我们要实现这个合并，还不如结合打包工具，比如webpack来使用，会方便很多

"compilerOptions": {
  "module": "system",
  "outFile": "./dist/app.js"
}

5.6 allowJs

布尔类型，表示是否对js文件进行编译，默认是false，也就是默认不编译js文件。在我们需要编译的工程目录下，有时候会出现js文件，默认情况下，是不会编译的，也就是不会输出到编译后的目录，会造成漏文件的情况。如果有需要，我们可以指定为true。

"compilerOptions": {
  "allowJs": true //默认为false
}

5.7 checkJs

布尔类型，表示是否对js代码进行语法规范的检查，默认为false。这个配置和上面的allowJs是一套的，用的话都用，也就是依赖allowJs为true时，配置才有意义。

"compilerOptions": {
  "allowJs": true //默认为false,
  "checkJs": true
}

5.8 removeComments

布尔类型，表示是否移除编译后的文件中的注释。默认为false，也就是不删注释。

"compilerOptions": {
  "removeComments": true //默认为false
}

5.9 noEmit

布尔类型，表示不生成编译文件，默认为false，也就是默认生成编译文件，一般很少用，用到的场景最多也就是：比如我只是需要检查代码是否能编译通过，不需要运行，可以直接设置true

"compilerOptions": {
  "noEmit": true //默认为false
}

5.10 noEmitOnError

布尔类型，表示发生错误时，不生成任何文件，默认为false。一般场景是：消除潜在的编译危险，比如编译错误了，就不生成编译文件

"compilerOptions": {
  "noEmitOnError": true //默认为false
}

5.11 alwaysStrict

布尔类型，表示编译后的文件，是否开启严格模式（use strict），默认为false

"compilerOptions": {
  "alwaysStrict": true //默认为false
}

5.12 noImplicitAny

布尔类型，表示不允许隐式的any出现，默认为false。会有潜在的风险，比如，如下代码：

function sum(a, b) {
  return a + b;
}

其中a和b的声明，没有指定类型，这里就是默认的隐式any，我这里明明是求和，后面如果传进来的有字符串，那么就是字符串相加，很明显就会出现问题，所以要避免这种情况，可以设置noImplicitAny：true

"compilerOptions": {
  "noImplicitAny": true //默认为false
}

5.13 strictNullChecks

布尔类型，表示不允许把null和undefined赋值给其他变量，也就是检测变量为空的情况,如果设置允许情况下，如下代码：

"compilerOptions": {
  "strictNullChecks": true //默认为false
}

let num = 1;
num = undefined;//Error 不能将类型“undefined”分配给类型“number”。

5.14 strict

布尔类型，表示是否启动所有的类型检查，一般在配置文件中，我们放在配置文件的顶端，因为它表示着，如果一旦开启，所有下面所有的严格模式下的检查，都会打开

{
  "compilerOptions": {
    "strict": true,
    "target": "es6",
    "allowJs": false,
    "checkJs": false,
    "removeComments": false,
    "noEmit": false,
    "noEmitOnError": false,
    "alwaysStrict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "noImplicitReturns": true 
}

5.15 sourceMap

布尔类型,表示是否生成sourceMap,默认为false, 在我们代码出错，进行代码调试时，开启这个属性可以直接导航到源码，而不是编译后的代码

"compilerOptions": {
  "sourceMap": true //默认为false
}

5.16 noUnusedParameters

布尔类型，用于检测在函数的形参是否存在未使用的情况

"compilerOptions": {
  "noUnusedParameters": true //默认为false
}

function show(name: string) { //'name' is declared but its value is never read.
  let num = 123;
}

5.17 noUnusedLocals

布尔类型，用于检测在函数内部（不包含函数的形参）是否存在未使用的参数

"compilerOptions": {
  "noUnusedLocals": true //默认为false
}

function show(name: string) {
  let num = 123;//'num' is declared but its value is never read.
}

开启后，如果没有检测到未使用的参数，编译时会报错，不过以上2种情况，我们一般会通过ESLint可以直接配合使用

5.18 experimentalDecorators

布尔类型，用于指定是否开启实验性（目前只是提案）的装饰器功能

export class UserInfo {
  @IsNumber()
  id: number
}

在ts项目中，我们经常会使用到装饰器功能，有了装饰器，会方便很多，但是如果不开启这属性，我们将无法在项目中使用装饰器，我们在使用的时候，需要和下面这个属性一起使用 emitDecoratorMetadata

5.19 emitDecoratorMetadata

布尔类型，用于指定是否为装饰器提供元数据支持，关于元数据，也是ES6的新标准，可以通过Reflect提供的静态方法获取元数据，如果需要使用Reflect的一些方法，需要引入ES2015.Reflect这个库

我们需要注意的是我们开启使用装饰器功能，最好是能把experimentalDecorators和emitDecoratorMetadata这两个属性同时开启，可以说是相互依赖的，要不然就算开启了可以使用装饰器，但是装饰器所需要的元数据支持没有开，照样还是无法使用

"compilerOptions": {
   "emitDecoratorMetadata": true,//同时设置为true,相互依赖
   "experimentalDecorators": true
 }

5.20 esModuleInterop

布尔类型，用于通过导入内容创建命名空间，实现CommonJS和ES6模块之间的互操作性，在我们项目中，难免会使用不同标准的模块化标准，特别是后端项目，要引入第三方库，模块化标准更不一样了，所以，开启这个属性，可以兼容CommonJS和ES6的模块化规范

"compilerOptions": {
   "esModuleInterop": true
}

tsconfig.json中的 编译选项还有很多，上面列举的一般都是常用的，后面工作中遇到了，我们还会遇到很多，这里就不一 一列举了。