在 TypeScript 開發(fā)中，tsconfig.json 是個(gè)不可或缺的配置文件，它是我們在 TS 項(xiàng)目中最常見的配置文件，那么你真的了解這個(gè)文件嗎？它里面都有哪些優(yōu)秀配置？如何配置一個(gè)合理的 tsconfig.json 文件？本文將全面帶大家一起詳細(xì)了解 tsconfig.json 的各項(xiàng)配置。

本文將從以下幾個(gè)方面全面介紹 tsconfig.json 文件：

了不起的 tsconfig.json 指南.png

水平有限，歡迎各位大佬指點(diǎn)~~

一、tsconfig.json 簡介

1. 什么是 tsconfig.json

TypeScript 使用 tsconfig.json 文件作為其配置文件，當(dāng)一個(gè)目錄中存在 tsconfig.json 文件，則認(rèn)為該目錄為 TypeScript 項(xiàng)目的根目錄。

通常 tsconfig.json 文件主要包含兩部分內(nèi)容：指定待編譯文件和定義編譯選項(xiàng)。

從《TypeScript編譯器的配置文件的JSON模式》可知，目前 tsconfig.json 文件有以下幾個(gè)頂層屬性：

compileOnSave

compilerOptions

exclude

extends

files

include

references

typeAcquisition

文章后面會(huì)詳細(xì)介紹一些常用屬性配置。

2. 為什么使用 tsconfig.json

通常我們可以使用 tsc 命令來編譯少量 TypeScript 文件：

/*

 參數(shù)介紹：

 --outFile // 編譯后生成的文件名稱

 --target  // 指定ECMAScript目標(biāo)版本

 --module  // 指定生成哪個(gè)模塊系統(tǒng)代碼

 index.ts  // 源文件

*/

$ tsc --outFile leo.js --target es3 --module amd index.ts

但如果實(shí)際開發(fā)的項(xiàng)目，很少是只有單個(gè)文件，當(dāng)我們需要編譯整個(gè)項(xiàng)目時(shí)，就可以使用 tsconfig.json 文件，將需要使用到的配置都寫進(jìn) tsconfig.json 文件，這樣就不用每次編譯都手動(dòng)輸入配置，另外也方便團(tuán)隊(duì)協(xié)作開發(fā)。

二、使用 tsconfig.json

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

1. 初始化 tsconfig.json

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

手動(dòng)在項(xiàng)目根目錄（或其他）創(chuàng)建 tsconfig.json 文件并填寫配置；

通過 tsc --init 初始化 tsconfig.json 文件。

2. 指定需要編譯的目錄

在不指定輸入文件的情況下執(zhí)行 tsc 命令，默認(rèn)從當(dāng)前目錄開始編譯，編譯所有 .ts 文件，并且從當(dāng)前目錄開始查找 tsconfig.json 文件，并逐級(jí)向上級(jí)目錄搜索。

$ tsc

另外也可以為 tsc 命令指定參數(shù) --project 或 -p 指定需要編譯的目錄，該目錄需要包含一個(gè) tsconfig.json 文件，如：

/*

 文件目錄：

 ├─src/

 │  ├─index.ts

 │  └─tsconfig.json

 ├─package.json

*/

$ tsc --project src

注意，tsc 的命令行選項(xiàng)具有優(yōu)先級(jí)，會(huì)覆蓋 tsconfig.json 中的同名選項(xiàng)。

更多 tsc 編譯選項(xiàng)，可查看《編譯選項(xiàng)》章節(jié)。

三、使用示例

這個(gè)章節(jié)，我們將通過本地一個(gè)小項(xiàng)目 learnTsconfig 來學(xué)著實(shí)現(xiàn)一個(gè)簡單配置。

當(dāng)前開發(fā)環(huán)境：windows / node 10.15.1 / TypeScript3.9

1. 初始化 learnTsconfig 項(xiàng)目

執(zhí)行下面命令：

$ mkdir learnTsconfig

$ cd .\learnTsconfig\

$ mkdir src

$ new-item index.ts

并且我們?yōu)?index.ts 文件寫一些簡單代碼：

// 返回當(dāng)前版本號(hào)

function getVersion(version:string = "1.0.0"): string{

   return version;

}

console.log(getVersion("1.0.1"))

我們將獲得這么一個(gè)目錄結(jié)構(gòu)：

 └─src/

    └─index.ts

2. 初始化 tsconfig.json 文件

在 learnTsconfig 根目錄執(zhí)行：

$ tsc --init

3. 修改 tsconfig.json 文件

我們設(shè)置幾個(gè)常見配置項(xiàng)：

{

 "compilerOptions": {

   "target": "ES5",             // 目標(biāo)語言的版本

   "module": "commonjs",        // 指定生成代碼的模板標(biāo)準(zhǔn)

   "noImplicitAny": true,       // 不允許隱式的 any 類型

   "removeComments": true,      // 刪除注釋

   "preserveConstEnums": true,  // 保留 const 和 enum 聲明

   "sourceMap": true            // 生成目標(biāo)文件的sourceMap文件

 },

 "files": [   // 指定待編譯文件

   "./src/index.ts"  

 ]

}

其中需要注意一點(diǎn)：

files 配置項(xiàng)值是一個(gè)數(shù)組，用來指定了待編譯文件，即入口文件。

當(dāng)入口文件依賴其他文件時(shí)，不需要將被依賴文件也指定到 files 中，因?yàn)榫幾g器會(huì)自動(dòng)將所有的依賴文件歸納為編譯對(duì)象，即 index.ts 依賴 user.ts 時(shí)，不需要在 files 中指定 user.ts ， user.ts 會(huì)自動(dòng)納入待編譯文件。

4. 執(zhí)行編譯

配置完成后，我們可以在命令行執(zhí)行 tsc 命令，執(zhí)行編譯完成后，我們可以得到一個(gè) index.js 文件和一個(gè) index.js.map 文件，證明我們編譯成功，其中 index.js 文件內(nèi)容如下：

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 配置生效了，將我們添加的注釋代碼移除了。

到這一步，就完成了這個(gè)簡單的示例，接下來會(huì)基于這個(gè)示例代碼，講解《七、常見配置示例》。

四、tsconfig.json 文件結(jié)構(gòu)介紹

1. 按頂層屬性分類

在 tsconfig.json 文件中按照頂層屬性，分為以下幾類：

tsconfig.json 文件結(jié)構(gòu)（頂層屬性）.png

了不起的 tsconfig.json 指南.png

2. 按功能分類

tsconfig.json 文件結(jié)構(gòu)（功能）.png

五、tsconfig.json 配置介紹

1. compileOnSave

compileOnSave 屬性作用是設(shè)置保存文件的時(shí)候自動(dòng)編譯，但需要編譯器支持。

{

   // ...

 "compileOnSave": false,

}

2. compilerOptions

compilerOptions 屬性作用是配置編譯選項(xiàng)。

若 compilerOptions 屬性被忽略，則編譯器會(huì)使用默認(rèn)值，可以查看《官方完整的編譯選項(xiàng)列表》。

編譯選項(xiàng)配置非常繁雜，有很多配置，這里只列出常用的配置。

{

 // ...

 "compilerOptions": {

   "incremental": true, // TS編譯器在第一次編譯之后會(huì)生成一個(gè)存儲(chǔ)編譯信息的文件，第二次編譯會(huì)在第一次的基礎(chǔ)上進(jìn)行增量編譯，可以提高編譯的速度

   "tsBuildInfoFile": "./buildFile", // 增量編譯文件的存儲(chǔ)位置

   "diagnostics": true, // 打印診斷信息

   "target": "ES5", // 目標(biāo)語言的版本

   "module": "CommonJS", // 生成代碼的模板標(biāo)準(zhǔn)

   "outFile": "./app.js", // 將多個(gè)相互依賴的文件生成一個(gè)文件，可以用在AMD模塊中，即開啟時(shí)應(yīng)設(shè)置"module": "AMD",

   "lib": ["DOM", "ES2015", "ScriptHost", "ES2019.Array"], // TS需要引用的庫，即聲明文件，es5 默認(rèn)引用dom、es5、scripthost,如需要使用es的高級(jí)版本特性，通常都需要配置，如es8的數(shù)組新特性需要引入"ES2019.Array",

   "allowJS": true, // 允許編譯器編譯JS，JSX文件

   "checkJs": true, // 允許在JS文件中報(bào)錯(cuò)，通常與allowJS一起使用

   "outDir": "./dist", // 指定輸出目錄

   "rootDir": "./", // 指定輸出文件目錄(用于輸出)，用于控制輸出目錄結(jié)構(gòu)

   "declaration": true, // 生成聲明文件，開啟后會(huì)自動(dòng)生成聲明文件

   "declarationDir": "./file", // 指定生成聲明文件存放目錄

   "emitDeclarationOnly": true, // 只生成聲明文件，而不會(huì)生成js文件

   "sourceMap": true, // 生成目標(biāo)文件的sourceMap文件

   "inlineSourceMap": true, // 生成目標(biāo)文件的inline SourceMap，inline SourceMap會(huì)包含在生成的js文件中

   "declarationMap": true, // 為聲明文件生成sourceMap

   "typeRoots": [], // 聲明文件目錄，默認(rèn)時(shí)node_modules/@types

   "types": [], // 加載的聲明文件包

   "removeComments":true, // 刪除注釋

   "noEmit": true, // 不輸出文件,即編譯后不會(huì)生成任何js文件

   "noEmitOnError": true, // 發(fā)送錯(cuò)誤時(shí)不輸出任何文件

   "noEmitHelpers": true, // 不生成helper函數(shù)，減小體積，需要額外安裝，常配合importHelpers一起使用

   "importHelpers": true, // 通過tslib引入helper函數(shù)，文件必須是模塊

   "downlevelIteration": true, // 降級(jí)遍歷器實(shí)現(xiàn)，如果目標(biāo)源是es3/5，那么遍歷器會(huì)有降級(jí)的實(shí)現(xiàn)

   "strict": true, // 開啟所有嚴(yán)格的類型檢查

   "alwaysStrict": true, // 在代碼中注入'use strict'

   "noImplicitAny": true, // 不允許隱式的any類型

   "strictNullChecks": true, // 不允許把null、undefined賦值給其他類型的變量

   "strictFunctionTypes": true, // 不允許函數(shù)參數(shù)雙向協(xié)變

   "strictPropertyInitialization": true, // 類的實(shí)例屬性必須初始化

   "strictBindCallApply": true, // 嚴(yán)格的bind/call/apply檢查

   "noImplicitThis": true, // 不允許this有隱式的any類型

   "noUnusedLocals": true, // 檢查只聲明、未使用的局部變量(只提示不報(bào)錯(cuò))

   "noUnusedParameters": true, // 檢查未使用的函數(shù)參數(shù)(只提示不報(bào)錯(cuò))

   "noFallthroughCasesInSwitch": true, // 防止switch語句貫穿(即如果沒有break語句后面不會(huì)執(zhí)行)

   "noImplicitReturns": true, //每個(gè)分支都會(huì)有返回值

   "esModuleInterop": true, // 允許export=導(dǎo)出，由import from 導(dǎo)入

   "allowUmdGlobalAccess": true, // 允許在模塊中全局變量的方式訪問umd模塊

   "moduleResolution": "node", // 模塊解析策略，ts默認(rèn)用node的解析策略，即相對(duì)的方式導(dǎo)入

   "baseUrl": "./", // 解析非相對(duì)模塊的基地址，默認(rèn)是當(dāng)前目錄

   "paths": { // 路徑映射，相對(duì)于baseUrl

     // 如使用jq時(shí)不想使用默認(rèn)版本，而需要手動(dòng)指定版本，可進(jìn)行如下配置

     "jquery": ["node_modules/jquery/dist/jquery.min.js"]

   },

   "rootDirs": ["src","out"], // 將多個(gè)目錄放在一個(gè)虛擬目錄下，用于運(yùn)行時(shí)，即編譯后引入文件的位置可能發(fā)生變化，這也設(shè)置可以虛擬src和out在同一個(gè)目錄下，不用再去改變路徑也不會(huì)報(bào)錯(cuò)

   "listEmittedFiles": true, // 打印輸出文件

   "listFiles": true// 打印編譯的文件(包括引用的聲明文件)

 }

}

3. exclude

exclude 屬性作用是指定編譯器需要排除的文件或文件夾。

默認(rèn)排除 node_modules 文件夾下文件。

{

   // ...

 "exclude": [

   "src/lib" // 排除src目錄下的lib文件夾下的文件不會(huì)編譯

 ]

}

和 include 屬性一樣，支持 glob 通配符：

* 匹配0或多個(gè)字符（不包括目錄分隔符）

? 匹配一個(gè)任意字符（不包括目錄分隔符）

**/ 遞歸匹配任意子目錄

4. extends

extends 屬性作用是引入其他配置文件，繼承配置。

默認(rèn)包含當(dāng)前目錄和子目錄下所有 TypeScript 文件。

{

   // ...

 // 把基礎(chǔ)配置抽離成tsconfig.base.json文件，然后引入

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

}

5. files

files 屬性作用是指定需要編譯的單個(gè)文件列表。

默認(rèn)包含當(dāng)前目錄和子目錄下所有 TypeScript 文件。

{

   // ...

 "files": [

   // 指定編譯文件是src目錄下的leo.ts文件

   "scr/leo.ts"

 ]

}

6. include

include 屬性作用是指定編譯需要編譯的文件或目錄。

{

   // ...

 "include": [

   // "scr" // 會(huì)編譯src目錄下的所有文件，包括子目錄

   // "scr/*" // 只會(huì)編譯scr一級(jí)目錄下的文件

   "scr/*/*" // 只會(huì)編譯scr二級(jí)目錄下的文件

 ]

}

7. references

references 屬性作用是指定工程引用依賴。

在項(xiàng)目開發(fā)中，有時(shí)候我們?yōu)榱朔奖銓⑶岸隧?xiàng)目和后端node項(xiàng)目放在同一個(gè)目錄下開發(fā)，兩個(gè)項(xiàng)目依賴同一個(gè)配置文件和通用文件，但我們希望前后端項(xiàng)目進(jìn)行靈活的分別打包，那么我們可以進(jìn)行如下配置：

{

   // ...

 "references": [ // 指定依賴的工程

    {"path": "./common"}

 ]

}

8. typeAcquisition

typeAcquisition 屬性作用是設(shè)置自動(dòng)引入庫類型定義文件(.d.ts)相關(guān)。

包含 3 個(gè)子屬性：

enable  : 布爾類型，是否開啟自動(dòng)引入庫類型定義文件(.d.ts)，默認(rèn)為 false；

include  : 數(shù)組類型，允許自動(dòng)引入的庫名，如：["jquery", "lodash"]；

exculde  : 數(shù)組類型，排除的庫名。

{

   // ...

 "typeAcquisition": {

   "enable": false,

   "exclude": ["jquery"],

   "include": ["jest"]

 }

}

六、常見配置示例

本部分內(nèi)容中，我們找了幾個(gè)實(shí)際開發(fā)中比較常見的配置，當(dāng)然，還有很多配置需要自己摸索喲~~

1. 移除代碼中注釋

tsconfig.json：

{

 "compilerOptions": {

   "removeComments": true,

 }

}

編譯前：

// 返回當(dāng)前版本號(hào)

function getVersion(version:string = "1.0.0"): string{

   return version;

}

console.log(getVersion("1.0.1"))

編譯結(jié)果：

function getVersion(version) {

   if (version === void 0) { version = "1.0.0"; }

   return version;

}

console.log(getVersion("1.0.1"));

2. 開啟null、undefined檢測

tsconfig.json：

{

   "compilerOptions": {

       "strictNullChecks": true

   },

}

修改 index.ts 文件內(nèi)容：

const leo;

leo = new Pingan('leo','hello');

這時(shí)候編輯器也會(huì)提示錯(cuò)誤信息，執(zhí)行 tsc 后，控制臺(tái)報(bào)錯(cuò)：

src/index.ts:9:11 - error TS2304: Cannot find name 'Pingan'.

9 leo = new Pingan('leo','hello');

Found 1 error.

3. 配置復(fù)用

通過 extends 屬性實(shí)現(xiàn)配置復(fù)用，即一個(gè)配置文件可以繼承另一個(gè)文件的配置屬性。

比如，建立一個(gè)基礎(chǔ)的配置文件 configs/base.json ：

{

 "compilerOptions": {

   "noImplicitAny": true,

   "strictNullChecks": true

 }

}

在tsconfig.json 就可以引用這個(gè)文件的配置了：

{

 "extends": "./configs/base",

 "files": [

   "main.ts",

   "supplemental.ts"

 ]

}

4. 生成枚舉的映射代碼

在默認(rèn)情況下，使用 const 修飾符后，枚舉不會(huì)生成映射代碼。

如下，我們可以看出：使用 const 修飾符后，編譯器不會(huì)生成任何 RequestMethod 枚舉的任何映射代碼，在其他地方使用時(shí)，內(nèi)聯(lián)每個(gè)成員的值，節(jié)省很大開銷。

const enum RequestMethod {

 Get,

 Post,

 Put,

 Delete

}

let methods = [

 RequestMethod.Get,

 RequestMethod.Post

]

編譯結(jié)果：

"use strict";

let methods = [

   0 /* Get */,

   1 /* Post */

];

當(dāng)然，我們希望生成映射代碼時(shí)，也可以設(shè)置 tsconfig.json 中的配置，設(shè)置 preserveConstEnums 編譯器選項(xiàng)為 true ：

{

 "compilerOptions": {

   "target": "es5",

   "preserveConstEnums": true

 }

}

最后編譯結(jié)果變成：

"use strict";

var RequestMethod;

(function (RequestMethod) {

   RequestMethod[RequestMethod["Get"] = 0] = "Get";

   RequestMethod[RequestMethod["Post"] = 1] = "Post";

   RequestMethod[RequestMethod["Put"] = 2] = "Put";

   RequestMethod[RequestMethod["Delete"] = 3] = "Delete";

})(RequestMethod || (RequestMethod = {}));

let methods = [

   0 /* Get */,

   1 /* Post */

];

5. 關(guān)閉 this 類型注解提示

通過下面代碼編譯后會(huì)報(bào)錯(cuò)：

const button = document.querySelector("button");

button?.addEventListener("click", handleClick);

function handleClick(this) {

console.log("Clicked!");

this.removeEventListener("click", handleClick);

}

報(bào)錯(cuò)內(nèi)容：

src/index.ts:10:22 - error TS7006: Parameter 'this' implicitly has an 'any' type.

10 function handleClick(this) {

Found 1 error.

這是因?yàn)?this 隱式具有 any 類型，如果沒有指定類型注解，編譯器會(huì)提示“"this" 隱式具有類型 "any"，因?yàn)樗鼪]有類型注釋?！?。

解決方法有2種：

指定 this 類型，如本代碼中為 HTMLElement 類型：

HTMLElement 接口表示所有的 HTML 元素。一些HTML元素直接實(shí)現(xiàn)了 HTMLElement 接口，其它的間接實(shí)現(xiàn)HTMLElement接口。

關(guān)于 HTMLElement 可查看詳細(xì)。

使用 --noImplicitThis 配置項(xiàng)：

在 TS2.0 還增加一個(gè)新的編譯選項(xiàng)： --noImplicitThis，表示當(dāng) this 表達(dá)式值為 any 類型時(shí)生成一個(gè)錯(cuò)誤信息。我們設(shè)置為 true 后就能正常編譯。

{

 "compilerOptions": {

   "noImplicitThis": true

 }

}

七、Webpack/React 中使用示例

1. 配置編譯 ES6 代碼，JSX 文件

創(chuàng)建測試項(xiàng)目 webpack-demo，結(jié)構(gòu)如下：

webpack-demo/

 |- package.json

 |- tsconfig.json

 |- webpack.config.js

 |- /dist

   |- bundle.js

   |- index.html

 |- /src

   |- index.js

   |- index.ts

 |- /node_modules

安裝 TypeScript 和 ts-loader：

$ npm install --save-dev typescript ts-loader

配置 tsconfig.json，支持 JSX，并將 TypeScript 編譯為 ES5：

{

 "compilerOptions": {

   "outDir": "./dist/",

   "noImplicitAny": true,

+   "module": "es6",

+   "target": "es5",

+   "jsx": "react",

   "allowJs": true

 }

}

還需要配置 webpack.config.js，使其能夠處理 TypeScript 代碼，這里主要在 rules 中添加 ts-loader ：

const path = require('path');

module.exports = {

 entry: './src/index.ts',

 module: {

   rules: [

     {

       test: /\.tsx?$/,

       use: 'ts-loader',

       exclude: /node_modules/

     }

   ]

 },

 resolve: {

   extensions: [ '.tsx', '.ts', '.js' ]

 },

 output: {

   filename: 'bundle.js',

   path: path.resolve(__dirname, 'dist')

 }

};

2. 配置 source map

想要啟用 source map，我們必須配置 TypeScript，以將內(nèi)聯(lián)的 source map 輸出到編譯后的 JavaScript 文件中。

只需要在 tsconfig.json 中配置 sourceMap 屬性：

 {

   "compilerOptions": {

     "outDir": "./dist/",

+     "sourceMap": true,

     "noImplicitAny": true,

     "module": "commonjs",

     "target": "es5",

     "jsx": "react",

     "allowJs": true

   }

 }

然后配置 webpack.config.js 文件，讓 webpack 提取 source map，并內(nèi)聯(lián)到最終的 bundle 中：

 const path = require('path');

 module.exports = {

   entry: './src/index.ts',

+   devtool: 'inline-source-map',

   module: {

     rules: [

       {

         test: /\.tsx?$/,

         use: 'ts-loader',

         exclude: /node_modules/

       }

     ]

   },

   resolve: {

     extensions: [ '.tsx', '.ts', '.js' ]

   },

   output: {

     filename: 'bundle.js',

     path: path.resolve(__dirname, 'dist')

   }

 };

八、總結(jié)

本文較全面介紹了 tsconfig.json 文件的知識(shí)，從“什么是 tsconfig.js 文件”開始，一步步帶領(lǐng)大家全面認(rèn)識(shí) tsconfig.json 文件。

文中通過一個(gè)簡單 learnTsconfig 項(xiàng)目，讓大家知道項(xiàng)目中如何使用 tsconfig.json 文件。在后續(xù)文章中，我們將這么多的配置項(xiàng)進(jìn)行分類學(xué)習(xí)。最后通過幾個(gè)常見配置示例，解決我們開發(fā)中遇到的幾個(gè)常見問題。