TypeScript tsconfig.json 配置

本節(jié)將詳細(xì)介紹 tsconfig.json 文件中各配置項(xiàng)的含義，這將對(duì)我們搭建一個(gè) TypeScript 工程項(xiàng)目很有幫助。

如果一個(gè)目錄下存在一個(gè) tsconfig.json 文件，那么它意味著這個(gè)目錄是 TypeScript 項(xiàng)目的根目錄，tsconfig.json 文件中指定了用來(lái)編譯這個(gè)項(xiàng)目的根文件和編譯選項(xiàng)。

1. 慕課解釋

一個(gè)項(xiàng)目可以通過(guò)以下方式之一來(lái)編譯：

• 不帶任何輸入文件的情況下調(diào)用 tsc 命令，編譯器會(huì)從當(dāng)前目錄開始去查找 tsconfig.json 文件，逐級(jí)向上搜索父目錄。
• 不帶任何輸入文件的情況下調(diào)用 tsc 命令，且使用命令行參數(shù) --project（或 -p ）指定一個(gè)包含 tsconfig.json 文件的目錄。

當(dāng)命令行上指定了輸入文件時(shí)，tsconfig.json 文件會(huì)被忽略。

2. tsconfig.json 主要配置項(xiàng)

一個(gè) tsconfig.json 文件主要有以下配置項(xiàng)：

{
  "compilerOptions": {},
  "files": [],
  "include": [],
  "exclude": [],
  "extends": "",
  "compileOnSave": false,
  "typeAcquisition": {}
}

2.1 compilerOptions

compilerOptions：對(duì)象類型，用來(lái)設(shè)置編譯選項(xiàng)，若不設(shè)置則默認(rèn)使用上節(jié)介紹的默認(rèn)配置。

下面是一份梳理的常用 compilerOptions 屬性配置：

{
  "compilerOptions": {
    "target": "esnext", /* 指定編譯之后的版本目標(biāo): 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', 'ES2018', 'ES2019' or 'ESNEXT'. */
    "module": "esnext", /* 指定要使用的模塊標(biāo)準(zhǔn): 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', or 'ESNext'. */
    "noImplicitAny": false, /* 是否默認(rèn)禁用 any */
    "removeComments": true, /* 是否移除注釋 */
    "declaration": true, /* 是否自動(dòng)創(chuàng)建類型聲明文件 */
    "strict": true, /* 啟動(dòng)所有類型檢查 */
    "jsx": "preserve", /* 指定jsx代碼用于的開發(fā)環(huán)境 */
    "importHelpers": true, /* 引入tslib里的輔助工具函數(shù)*/
    "moduleResolution": "node", /* 選擇模塊解析策略，有'node'和'classic'兩種類型 */
    "experimentalDecorators": true, /* 啟用實(shí)驗(yàn)性的裝飾器特性 */
    "esModuleInterop": true,  /* 通過(guò)為導(dǎo)入內(nèi)容創(chuàng)建命名空間，實(shí)現(xiàn)CommonJS和ES模塊之間的互操作性 */
    "allowSyntheticDefaultImports": true, /* 允許從沒(méi)有默認(rèn)導(dǎo)出的模塊中默認(rèn)導(dǎo)入 */
    "sourceMap": true, /* 是否生成map文件 */
    "baseUrl": ".", /* 工作根目錄 */
    "types": [ /* 指定引入的類型聲明文件，默認(rèn)是自動(dòng)引入所有聲明文件，一旦指定該選項(xiàng)，則會(huì)禁用自動(dòng)引入，改為只引入指定的類型聲明文件，如果指定空數(shù)組[]則不引用任何文件 */
      "webpack-env",
      "jest"
    ],
    "paths": { /* 指定模塊的路徑，和 baseUrl有關(guān)聯(lián)，和 webpack 中 resolve.alias 配置一樣 */
      "@/*": [
        "src/*"
      ]
    },
    "lib": [ /* 譯過(guò)程中需要引入的庫(kù)文件的列表 */
      "esnext",
      "dom",
      "dom.iterable",
      "scripthost"
    ]
  }
}

2.2 files，include 和 exclude

• files 是一個(gè)數(shù)組列表，寫入待編譯文件的相對(duì)或絕對(duì)路徑，不支持 glob 匹配模式。

• include 是一個(gè)數(shù)組列表，寫入待編譯文件的路徑，支持 glob 匹配模式。

• exclude 也是一個(gè)數(shù)組列表，寫入排除某些文件路徑，這些文件排除于待編譯列表，支持 glob 匹配模式。

glob 通配符有:

• * 匹配 0 或多個(gè)字符（不包括目錄分隔符）
• ? 匹配一個(gè)任意字符（不包括目錄分隔符）
• **/ 遞歸匹配任意子目錄

如果 "files" 和 "include" 都沒(méi)有被指定，編譯器默認(rèn)包含當(dāng)前目錄和子目錄下所有的 TypeScript 文件（.ts, .d.ts 和 .tsx），排除在"exclude" 里指定的文件。

如果開啟了 allowJs 選項(xiàng)，那 .js 和 .jsx 文件也屬于編譯器包含范圍。

{
  "files": [
  "core.ts",
  "index.ts",
  "types.ts"
  ],
  "exclude": [
    "node_modules", 
    "lib", 
    "**/*.test.ts"
  ],
  "include": [
    "src/**/*"
  ],
}

如果沒(méi)有特殊指定，"exclude" 默認(rèn)情況下會(huì)排除 node_modules，bower_components，jspm_packages 和 <outDir> 目錄。

任何被 "files" 或 "include" 指定的文件所引用的文件也會(huì)被包含進(jìn)來(lái)。

優(yōu)先級(jí)：命令行配置 > files > exclude > include

2.3 extends

extends：字符串類型，指向另一個(gè)要繼承文件的路徑。例如：

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

這個(gè)配置項(xiàng)的意思就是我們可以借助 "extends" 屬性引入路徑為 "config/base.json" 的配置文件中的配置選項(xiàng)。

configs/base.json:

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

需要注意：

• 如果有同名配置，繼承文件里的配置會(huì)覆蓋源文件里的配置

2.4 compileOnSave

compileOnSave 是一個(gè)布爾類型的屬性，當(dāng)值為 true 時(shí)，設(shè)置 compileOnSave 屬性到 IDE，以便 tsconfig.ts 文件在保存時(shí)能夠重新生成文件。

2.5 typeAcquisition

typeAcquisition：對(duì)象類型，用以設(shè)置自動(dòng)引入庫(kù)類型定義文件（.d.ts），該屬性下面有3個(gè)子屬性：

• enable: 布爾類型，用以設(shè)置是否開啟自動(dòng)引入庫(kù)類型定義文件
• include: 數(shù)組類型，允許自動(dòng)引入的庫(kù)名列表，如 ["jquery", "kendo-ui"]
• exclude: 數(shù)組類型，排除的庫(kù)名列表

3. @types，typeRoots 和 types

默認(rèn)情況下，node_modules/@types 文件夾下以及它們子文件夾下的所有包都會(huì)在編譯過(guò)程中被包含進(jìn)來(lái)。

但是如果指定了 typeRoots，則只有 typeRoots 路徑下的包才會(huì)被包含進(jìn)來(lái)：

{
  "compilerOptions": {
    "typeRoots" : ["./typings"]
  }
}

這個(gè)配置文件會(huì)包含所有 ./typings 下面的包，而不包含 ./node_modules/@types 里面的包。

如果指定了 types，只有被列出來(lái)的包才會(huì)被包含進(jìn)來(lái)。比如：

{
  "compilerOptions": {
    "types": ["node", "lodash", "express"]
  }
}

如果 types 設(shè)置為空數(shù)組，則禁止自動(dòng)引入 @types 包：

{
  "compilerOptions": {
    "types": []
  }
}

注意，自動(dòng)引入只在你使用了全局的聲明（相反于模塊）時(shí)是重要的。如果你使用 import "foo" 語(yǔ)句，TypeScript 仍然會(huì)查找 node_modules 和node_modules/@types 文件夾來(lái)獲取 foo 包。

4. 小結(jié)

本節(jié)介紹了 tsconfig.json 文件中的各配置項(xiàng)及其使用場(chǎng)景，尤其要熟悉一些常用的編譯選項(xiàng)，一份良好的配置項(xiàng)文件也是一個(gè)團(tuán)隊(duì)規(guī)范的標(biāo)準(zhǔn)之一。