簡(jiǎn)介

tsconfig.json是 TypeScript 項(xiàng)目的配置文件，放在項(xiàng)目的根目錄。反過(guò)來(lái)說(shuō)，如果一個(gè)目錄里面有tsconfig.json，TypeScript 就認(rèn)為這是項(xiàng)目的根目錄。

如果項(xiàng)目源碼是 JavaScript，但是想用 TypeScript 處理，那么配置文件的名字是jsconfig.json，它跟tsconfig的寫(xiě)法是一樣的。

tsconfig.json文件主要供tsc編譯器使用，它的命令行參數(shù)--project或-p可以指定tsconfig.json的位置（目錄或文件皆可）。

$ tsc -p ./dir

如果不指定配置文件的位置，tsc就會(huì)在當(dāng)前目錄下搜索tsconfig.json文件，如果不存在，就到上一級(jí)目錄搜索，直到找到為止。

tsconfig.json文件的格式，是一個(gè) JSON 對(duì)象，最簡(jiǎn)單的情況可以只放置一個(gè)空對(duì)象{}。下面是一個(gè)示例。

{
  "compilerOptions": {
    "outDir": "./built",
    "allowJs": true,
    "target": "es5"
  },
  "include": ["./src/**/*"]
}

本章后面會(huì)詳細(xì)介紹tsconfig.json的各個(gè)屬性，這里簡(jiǎn)單說(shuō)一下，上面示例的四個(gè)屬性的含義。

• include：指定哪些文件需要編譯。
• allowJs：指定源目錄的 JavaScript 文件是否原樣拷貝到編譯后的目錄。
• outDir：指定編譯產(chǎn)物存放的目錄。
• target：指定編譯產(chǎn)物的 JS 版本。

tsconfig.json文件可以不必手寫(xiě)，使用 tsc 命令的--init參數(shù)自動(dòng)生成。

$ tsc --init

上面命令生成的tsconfig.json文件，里面會(huì)有一些默認(rèn)配置。

你也可以使用別人預(yù)先寫(xiě)好的 tsconfig.json 文件，npm 的@tsconfig名稱(chēng)空間下面有很多模塊，都是寫(xiě)好的tsconfig.json樣本，比如 @tsconfig/recommended和@tsconfig/node16。

這些模塊需要安裝，以@tsconfig/deno為例。

$ npm install --save-dev @tsconfig/deno
# 或者
$ yarn add --dev @tsconfig/deno

安裝以后，就可以在tsconfig.json里面引用這個(gè)模塊，相當(dāng)于繼承它的設(shè)置，然后進(jìn)行擴(kuò)展。

{
  "extends": "@tsconfig/deno/tsconfig.json"
}

@tsconfig空間下包含的完整 tsconfig 文件目錄，可以查看 GitHub。

tsconfig.json的一級(jí)屬性并不多，只有很少幾個(gè)，但是compilerOptions屬性有很多二級(jí)屬性。下面先逐一介紹一級(jí)屬性，然后再介紹compilerOptions的二級(jí)屬性，按照首字母排序。

exclude

exclude屬性是一個(gè)數(shù)組，必須與include屬性一起使用，用來(lái)從編譯列表中去除指定的文件。它也支持使用與include屬性相同的通配符。

{
  "include": ["**/*"],
  "exclude": ["**/*.spec.ts"]
}

extends

tsconfig.json可以繼承另一個(gè)tsconfig.json文件的配置。如果一個(gè)項(xiàng)目有多個(gè)配置，可以把共同的配置寫(xiě)成tsconfig.base.json，其他的配置文件繼承該文件，這樣便于維護(hù)和修改。

extends屬性用來(lái)指定所要繼承的配置文件。它可以是本地文件。

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

如果extends屬性指定的路徑不是以./或../開(kāi)頭，那么編譯器將在node_modules目錄下查找指定的配置文件。

extends屬性也可以繼承已發(fā)布的 npm 模塊里面的 tsconfig 文件。

{
  "extends": "@tsconfig/node12/tsconfig.json"
}

extends指定的tsconfig.json會(huì)先加載，然后加載當(dāng)前的tsconfig.json。如果兩者有重名的屬性，后者會(huì)覆蓋前者。

files

files屬性指定編譯的文件列表，如果其中有一個(gè)文件不存在，就會(huì)報(bào)錯(cuò)。

它是一個(gè)數(shù)組，排在前面的文件先編譯。

{
  "files": ["a.ts", "b.ts"]
}

該屬性必須逐一列出文件，不支持文件匹配。如果文件較多，建議使用include和exclude屬性。

include

include屬性指定所要編譯的文件列表，既支持逐一列出文件，也支持通配符。文件位置相對(duì)于當(dāng)前配置文件而定。

{
  "include": ["src/**/*", "tests/**/*"]
}

include屬性支持三種通配符。

• ?：指代單個(gè)字符
• *：指代任意字符，不含路徑分隔符
• **：指定任意目錄層級(jí)。

如果不指定文件后綴名，默認(rèn)包括.ts、.tsx和.d.ts文件。如果打開(kāi)了allowJs，那么還包括.js和.jsx。

references

references屬性是一個(gè)數(shù)組，數(shù)組成員為對(duì)象，適合一個(gè)大項(xiàng)目由許多小項(xiàng)目構(gòu)成的情況，用來(lái)設(shè)置需要引用的底層項(xiàng)目。

{
  "references": [
    { "path": "../pkg1" },
    { "path": "../pkg2/tsconfig.json" }
  ]
}

references數(shù)組成員對(duì)象的path屬性，既可以是含有文件tsconfig.json的目錄，也可以直接是該文件。

與此同時(shí)，引用的底層項(xiàng)目的tsconfig.json必須啟用composite屬性。

{
  "compilerOptions": {
    "composite": true
  }
}

compileOptions

compilerOptions屬性用來(lái)定制編譯行為。這個(gè)屬性可以省略，這時(shí)編譯器將使用默認(rèn)設(shè)置。

allowJs

allowJs允許 TypeScript 項(xiàng)目加載 JS 腳本。編譯時(shí)，也會(huì)將 JS 文件，一起拷貝到輸出目錄。

{
  "compilerOptions": {
    "allowJs": true
  }
}

alwaysStrict

alwaysStrict確保腳本以 ECMAScript 嚴(yán)格模式進(jìn)行解析，因此腳本頭部不用寫(xiě)"use strict"。它的值是一個(gè)布爾值，默認(rèn)為true。

allowSyntheticDefaultImports

allowSyntheticDefaultImports允許import命令默認(rèn)加載沒(méi)有default輸出的模塊。

比如，打開(kāi)這個(gè)設(shè)置，就可以寫(xiě)import React from "react";，而不是import * as React from "react";。

allowUnreachableCode

allowUnreachableCode設(shè)置是否允許存在不可能執(zhí)行到的代碼。它的值有三種可能。

• undefined： 默認(rèn)值，編輯器顯示警告。
• true：忽略不可能執(zhí)行到的代碼。
• false：編譯器報(bào)錯(cuò)。

allowUnusedLabels

allowUnusedLabels設(shè)置是否允許存在沒(méi)有用到的代碼標(biāo)簽（label）。它的值有三種可能。

• undefined： 默認(rèn)值，編輯器顯示警告。
• true：忽略沒(méi)有用到的代碼標(biāo)簽。
• false：編譯器報(bào)錯(cuò)。

baseUrl

baseUrl的值為字符串，指定 TypeScript 項(xiàng)目的基準(zhǔn)目錄。

由于默認(rèn)是以 tsconfig.json 的位置作為基準(zhǔn)目錄，所以一般情況不需要使用該屬性。

{
  "compilerOptions": {
    "baseUrl": "./"
  }
}

上面示例中，baseUrl為當(dāng)前目錄./。那么，當(dāng)遇到下面的語(yǔ)句，TypeScript 將以./為起點(diǎn)，尋找hello/world.ts。

import { helloWorld } from "hello/world";

checkJs

checkJS設(shè)置對(duì) JS 文件同樣進(jìn)行類(lèi)型檢查。打開(kāi)這個(gè)屬性，也會(huì)自動(dòng)打開(kāi)allowJs。它等同于在 JS 腳本的頭部添加// @ts-check命令。

{
  "compilerOptions":{
    "checkJs": true
  }
}

composite

composite打開(kāi)某些設(shè)置，使得 TypeScript 項(xiàng)目可以進(jìn)行增量構(gòu)建，往往跟incremental屬性配合使用。

declaration

declaration設(shè)置編譯時(shí)是否為每個(gè)腳本生成類(lèi)型聲明文件.d.ts。

{
  "compilerOptions": {
    "declaration": true
  }
}

declarationDir

declarationDir設(shè)置生成的.d.ts文件所在的目錄。

{
  "compilerOptions": {
    "declaration": true,
    "declarationDir": "./types"
  }
}

declarationMap

declarationMap設(shè)置生成.d.ts類(lèi)型聲明文件的同時(shí)，還會(huì)生成對(duì)應(yīng)的 Source Map 文件。