TypeScript tsconfig.json 配置

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

如果一個目錄下存在一個 tsconfig.json 文件，那么它意味著這個目錄是 TypeScript 項目的根目錄，tsconfig.json 文件中指定了用來編譯這個項目的根文件和編譯選項。

1. 慕課解釋

一個項目可以通過以下方式之一來編譯：

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

當命令行上指定了輸入文件時，tsconfig.json 文件會被忽略。

2. tsconfig.json 主要配置項

一個 tsconfig.json 文件主要有以下配置項：

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

2.1 compilerOptions

compilerOptions：對象類型，用來設置編譯選項，若不設置則默認使用上節(jié)介紹的默認配置。

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

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

2.2 files，include 和 exclude

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

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

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

glob 通配符有:

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

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

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

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

如果沒有特殊指定，"exclude" 默認情況下會排除 node_modules，bower_components，jspm_packages 和 <outDir> 目錄。

任何被 "files" 或 "include" 指定的文件所引用的文件也會被包含進來。

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

2.3 extends

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

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

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

configs/base.json:

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

需要注意：

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

2.4 compileOnSave

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

2.5 typeAcquisition

typeAcquisition：對象類型，用以設置自動引入庫類型定義文件（.d.ts），該屬性下面有3個子屬性：

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

3. @types，typeRoots 和 types

默認情況下，node_modules/@types 文件夾下以及它們子文件夾下的所有包都會在編譯過程中被包含進來。

但是如果指定了 typeRoots，則只有 typeRoots 路徑下的包才會被包含進來：

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

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

如果指定了 types，只有被列出來的包才會被包含進來。比如：

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

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

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

注意，自動引入只在你使用了全局的聲明（相反于模塊）時是重要的。如果你使用 import "foo" 語句，TypeScript 仍然會查找 node_modules 和node_modules/@types 文件夾來獲取 foo 包。

4. 小結

本節(jié)介紹了 tsconfig.json 文件中的各配置項及其使用場景，尤其要熟悉一些常用的編譯選項，一份良好的配置項文件也是一個團隊規(guī)范的標準之一。