了不起的tsconfig.json指南
在 TypeScript 開發(fā)中,tsconfig.json 是個(gè)不可或缺的配置文件,它是我們?cè)?TS 項(xiàng)目中最常見的配置文件,那么你真的了解這個(gè)文件嗎?它里面都有哪些優(yōu)秀配置?如何配置一個(gè)合理的 tsconfig.json 文件?本文將全面帶大家一起詳細(xì)了解 tsconfig.json 的各項(xiàng)配置。
本文將從以下幾個(gè)方面全面介紹 tsconfig.json 文件:
水平有限,歡迎各位大佬指點(diǎn)~~
一、tsconfig.json 簡(jiǎn)介
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 命令來(lái)編譯少量 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 文件并填寫配置;
- 通過(guò) 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é),我們將通過(guò)本地一個(gè)小項(xiàng)目 learnTsconfig 來(lái)學(xué)著實(shí)現(xiàn)一個(gè)簡(jiǎn)單配置。
當(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 文件寫一些簡(jiǎn)單代碼:
- // 返回當(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 文件
我們?cè)O(shè)置幾個(gè)常見配置項(xiàng):
- {
- "compilerOptions": {
- "target": "ES5", // 目標(biāo)語(yǔ)言的版本
- "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ù)組,用來(lái)指定了待編譯文件,即入口文件。
當(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è)簡(jiǎn)單的示例,接下來(lái)會(huì)基于這個(gè)示例代碼,講解《七、常見配置示例》。
四、tsconfig.json 文件結(jié)構(gòu)介紹
1. 按頂層屬性分類
在 tsconfig.json 文件中按照頂層屬性,分為以下幾類:
2. 按功能分類
五、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)語(yǔ)言的版本
- "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需要引用的庫(kù),即聲明文件,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, // 通過(guò)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語(yǔ)句貫穿(即如果沒有break語(yǔ)句后面不會(huì)執(zhí)行)
- "noImplicitReturns": true, //每個(gè)分支都會(huì)有返回值
- "esModuleInterop": true, // 允許export=導(dǎo)出,由import from 導(dǎo)入
- "allowUmdGlobalAccess": true, // 允許在模塊中全局變量的方式訪問(wèn)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)引入庫(kù)類型定義文件(.d.ts)相關(guān)。
包含 3 個(gè)子屬性:
- enable : 布爾類型,是否開啟自動(dòng)引入庫(kù)類型定義文件(.d.ts),默認(rèn)為 false;
- include : 數(shù)組類型,允許自動(dòng)引入的庫(kù)名,如:["jquery", "lodash"];
- exculde : 數(shù)組類型,排除的庫(kù)名。
- {
- // ...
- "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檢測(cè)
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ù)用
通過(guò) 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 類型注解提示
通過(guò)下面代碼編譯后會(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ì)。
2. 使用 --noImplicitThis 配置項(xiàng):
在 TS2.0 還增加一個(gè)新的編譯選項(xiàng): --noImplicitThis,表示當(dāng) this 表達(dá)式值為 any 類型時(shí)生成一個(gè)錯(cuò)誤信息。我們?cè)O(shè)置為 true 后就能正常編譯。
- {
- "compilerOptions": {
- "noImplicitThis": true
- }
- }
七、Webpack/React 中使用示例
1. 配置編譯 ES6 代碼,JSX 文件
創(chuàng)建測(cè)試項(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 文件。
文中通過(guò)一個(gè)簡(jiǎn)單 learnTsconfig 項(xiàng)目,讓大家知道項(xiàng)目中如何使用 tsconfig.json 文件。在后續(xù)文章中,我們將這么多的配置項(xiàng)進(jìn)行分類學(xué)習(xí)。最后通過(guò)幾個(gè)常見配置示例,解決我們開發(fā)中遇到的幾個(gè)常見問(wèn)題。
當(dāng)然,本文篇幅有限,無(wú)法針對(duì)每個(gè)屬性進(jìn)行深入介紹,這就需要大家在實(shí)際開發(fā)中,多去嘗試和使用啦~