tsconfig.json

简介

tsconfig.json是 TypeScript 项目的配置文件,放在项目的根目录。反过来说,如果一个目录里面有tsconfig.json,TypeScript 就认为这是项目的根目录。

如果项目源码是 JavaScript,但是想用 TypeScript 处理,那么配置文件的名字是jsconfig.json,它跟tsconfig的写法是一样的。

tsconfig.json文件主要供tsc编译器使用,它的命令行参数--project-p可以指定tsconfig.json的位置(目录或文件皆可)。

  1. $ tsc -p ./dir

如果不指定配置文件的位置,tsc就会在当前目录下搜索tsconfig.json文件,如果不存在,就到上一级目录搜索,直到找到为止。

tsconfig.json文件的格式,是一个 JSON 对象,最简单的情况可以只放置一个空对象{}。下面是一个示例。

  1. {
  2. "compilerOptions": {
  3. "outDir": "./built",
  4. "allowJs": true,
  5. "target": "es5"
  6. },
  7. "include": ["./src/**/*"]
  8. }

本章后面会详细介绍tsconfig.json的各个属性,这里简单说一下,上面示例的四个属性的含义。

  • include:指定哪些文件需要编译。
  • allowJs:指定源目录的 JavaScript 文件是否原样拷贝到编译后的目录。
  • outDir:指定编译产物存放的目录。
  • target:指定编译产物的 JS 版本。

tsconfig.json文件可以不必手写,使用 tsc 命令的--init参数自动生成。

  1. $ tsc --init

上面命令生成的tsconfig.json文件,里面会有一些默认配置。

你也可以使用别人预先写好的 tsconfig.json 文件,npm 的@tsconfig名称空间下面有很多模块,都是写好的tsconfig.json样本,比如 @tsconfig/recommended@tsconfig/node16

这些模块需要安装,以@tsconfig/deno为例。

  1. $ npm install --save-dev @tsconfig/deno
  2. # 或者
  3. $ yarn add --dev @tsconfig/deno

安装以后,就可以在tsconfig.json里面引用这个模块,相当于继承它的设置,然后进行扩展。

  1. {
  2. "extends": "@tsconfig/deno/tsconfig.json"
  3. }

@tsconfig空间下包含的完整 tsconfig 文件目录,可以查看 GitHub

tsconfig.json的一级属性并不多,只有很少几个,但是compilerOptions属性有很多二级属性。下面先逐一介绍一级属性,然后再介绍compilerOptions的二级属性,按照首字母排序。

exclude

exclude属性是一个数组,必须与include属性一起使用,用来从编译列表中去除指定的文件。它也支持使用与include属性相同的通配符。

  1. {
  2. "include": ["**/*"],
  3. "exclude": ["**/*.spec.ts"]
  4. }

extends

tsconfig.json可以继承另一个tsconfig.json文件的配置。如果一个项目有多个配置,可以把共同的配置写成tsconfig.base.json,其他的配置文件继承该文件,这样便于维护和修改。

extends属性用来指定所要继承的配置文件。它可以是本地文件。

  1. {
  2. "extends": "../tsconfig.base.json"
  3. }

如果extends属性指定的路径不是以./../开头,那么编译器将在node_modules目录下查找指定的配置文件。

extends属性也可以继承已发布的 npm 模块里面的 tsconfig 文件。

  1. {
  2. "extends": "@tsconfig/node12/tsconfig.json"
  3. }

extends指定的tsconfig.json会先加载,然后加载当前的tsconfig.json。如果两者有重名的属性,后者会覆盖前者。

files

files属性指定编译的文件列表,如果其中有一个文件不存在,就会报错。

它是一个数组,排在前面的文件先编译。

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

该属性必须逐一列出文件,不支持文件匹配。如果文件较多,建议使用includeexclude属性。

include

include属性指定所要编译的文件列表,既支持逐一列出文件,也支持通配符。文件位置相对于当前配置文件而定。

  1. {
  2. "include": ["src/**/*", "tests/**/*"]
  3. }

include属性支持三种通配符。

  • ?:指代单个字符
  • *:指代任意字符,不含路径分隔符
  • **:指定任意目录层级。

如果不指定文件后缀名,默认包括.ts.tsx.d.ts文件。如果打开了allowJs,那么还包括.js.jsx

references

references属性是一个数组,数组成员为对象,适合一个大项目由许多小项目构成的情况,用来设置需要引用的底层项目。

  1. {
  2. "references": [
  3. { "path": "../pkg1" },
  4. { "path": "../pkg2/tsconfig.json" }
  5. ]
  6. }

references数组成员对象的path属性,既可以是含有文件tsconfig.json的目录,也可以直接是该文件。

与此同时,引用的底层项目的tsconfig.json必须启用composite属性。

  1. {
  2. "compilerOptions": {
  3. "composite": true
  4. }
  5. }

compileOptions

compilerOptions属性用来定制编译行为。这个属性可以省略,这时编译器将使用默认设置。

allowJs

allowJs允许 TypeScript 项目加载 JS 脚本。编译时,也会将 JS 文件,一起拷贝到输出目录。

  1. {
  2. "compilerOptions": {
  3. "allowJs": true
  4. }
  5. }

alwaysStrict

alwaysStrict确保脚本以 ECMAScript 严格模式进行解析,因此脚本头部不用写"use strict"。它的值是一个布尔值,默认为true

allowSyntheticDefaultImports

allowSyntheticDefaultImports允许import命令默认加载没有default输出的模块。

比如,打开这个设置,就可以写import React from "react";,而不是import * as React from "react";

allowUnreachableCode

allowUnreachableCode设置是否允许存在不可能执行到的代码。它的值有三种可能。

  • undefined: 默认值,编辑器显示警告。
  • true:忽略不可能执行到的代码。
  • false:编译器报错。

allowUnusedLabels

allowUnusedLabels设置是否允许存在没有用到的代码标签(label)。它的值有三种可能。

  • undefined: 默认值,编辑器显示警告。
  • true:忽略没有用到的代码标签。
  • false:编译器报错。

baseUrl

baseUrl的值为字符串,指定 TypeScript 项目的基准目录。

由于默认是以 tsconfig.json 的位置作为基准目录,所以一般情况不需要使用该属性。

  1. {
  2. "compilerOptions": {
  3. "baseUrl": "./"
  4. }
  5. }

上面示例中,baseUrl为当前目录./。那么,当遇到下面的语句,TypeScript 将以./为起点,寻找hello/world.ts

  1. import { helloWorld } from "hello/world";

checkJs

checkJS设置对 JS 文件同样进行类型检查。打开这个属性,也会自动打开allowJs。它等同于在 JS 脚本的头部添加// @ts-check命令。

  1. {
  2. "compilerOptions":{
  3. "checkJs": true
  4. }
  5. }

composite

composite打开某些设置,使得 TypeScript 项目可以进行增量构建,往往跟incremental属性配合使用。

declaration

declaration设置编译时是否为每个脚本生成类型声明文件.d.ts

  1. {
  2. "compilerOptions": {
  3. "declaration": true
  4. }
  5. }

declarationDir

declarationDir设置生成的.d.ts文件所在的目录。

  1. {
  2. "compilerOptions": {
  3. "declaration": true,
  4. "declarationDir": "./types"
  5. }
  6. }

declarationMap

declarationMap设置生成.d.ts类型声明文件的同时,还会生成对应的 Source Map 文件。

  1. {
  2. "compilerOptions": {
  3. "declaration": true,
  4. "declarationMap": true
  5. }
  6. }

emitBOM

emitBOM设置是否在编译结果的文件头添加字节顺序标志 BOM,默认值是false

emitDeclarationOnly

emitDeclarationOnly设置编译后只生成.d.ts文件,不生成.js文件。

esModuleInterop

esModuleInterop修复了一些 CommonJS 和 ES6 模块之间的兼容性问题。

如果module属性为node16nodenext,则esModuleInterop默认为true,其他情况默认为false

打开这个属性,使用import命令加载 CommonJS 模块时,TypeScript 会严格检查兼容性问题是否存在。

  1. import * as moment from 'moment'
  2. moment(); // 报错

上面示例中,根据 ES6 规范,import * as moment里面的moment是一个对象,不能当作函数调用,所以第二行报错了。

解决方法就是改写上面的语句,改成加载默认接口。

  1. import moment from 'moment'
  2. moment(); // 不报错

打开esModuleInterop以后,如果将上面的代码编译成 CommonJS 模块格式,就会加入一些辅助函数,保证编译后的代码行为正确。

注意,打开esModuleInterop,将自动打开allowSyntheticDefaultImports

exactOptionalPropertyTypes

exactOptionalPropertyTypes设置可选属性不能赋值为undefined

  1. // 打开 exactOptionalPropertyTypes
  2. interface MyObj {
  3. foo?: 'A' | 'B';
  4. }
  5. let obj:MyObj = { foo: 'A' };
  6. obj.foo = undefined; // 报错

上面示例中,foo是可选属性,打开exactOptionalPropertyTypes以后,该属性就不能显式赋值为undefined

forceConsistentCasingInFileNames

forceConsistentCasingInFileNames设置文件名是否为大小写敏感,默认为true

incremental

incremental让 TypeScript 项目构建时产生文件tsbuildinfo,从而完成增量构建。

inlineSourceMap

inlineSourceMap设置将 SourceMap 文件写入编译后的 JS 文件中,否则会单独生成一个.js.map文件。

inlineSources

inlineSources设置将原始的.ts代码嵌入编译后的 JS 中。

它要求sourceMapinlineSourceMap至少打开一个。

isolatedModules

isolatedModules设置如果当前 TypeScript 脚本作为单个模块编译,是否会因为缺少其他脚本的类型信息而报错,主要便于非官方的编译工具(比如 Babel)正确编译单个脚本。

jsx

jsx设置如何处理.tsx文件。它一般以下三个值。

  • preserve:保持 jsx 语法不变,输出的文件名为 jsx。
  • react:将<div />编译成React.createElement("div"),输出的文件名为.js
  • react-native:保持 jsx 语法不变,输出的文件后缀名为.js
  1. {
  2. "compilerOptions": {
  3. "jsx": "preserve"
  4. }
  5. }

lib

lib值是一个数组,描述项目需要加载的 TypeScript 内置类型描述文件,跟三斜线指令/// <reference lib="" />作用相同。

  1. {
  2. "compilerOptions": {
  3. "lib": ["dom", "es2021"]
  4. }
  5. }

TypeScript 内置的类型描述文件,主要有以下一些,完整的清单可以参考 TypeScript 源码

  • ES5
  • ES2015
  • ES6
  • ES2016
  • ES7
  • ES2017
  • ES2018
  • ES2019
  • ES2020
  • ES2021
  • ES2022
  • ESNex
  • DOM
  • WebWorker
  • ScriptHost

listEmittedFiles

listEmittedFiles设置编译时在终端显示,生成了哪些文件。

  1. {
  2. "compilerOptions": {
  3. "listFiles": true
  4. }
  5. }

listFiles

listFiles设置编译时在终端显示,参与本次编译的文件列表。

  1. {
  2. "compilerOptions": {
  3. "listFiles": true
  4. }
  5. }

mapRoot

mapRoot指定 SourceMap 文件的位置,而不是默认的生成位置。

  1. {
  2. "compilerOptions": {
  3. "sourceMap": true,
  4. "mapRoot": "https://my-website.com/debug/sourcemaps/"
  5. }
  6. }

module

module指定编译产物的模块格式。它的默认值与target属性有关,如果targetES3ES5,它的默认值是commonjs,否则就是ES6/ES2015

  1. {
  2. "compilerOptions": {
  3. "module": "commonjs"
  4. }
  5. }

它可以取以下值:none、commonjs、amd、umd、system、es6/es2015、es2020、es2022、esnext、node16、nodenext。

moduleResolution

moduleResolution确定模块路径的算法,即如何查找模块。它可以取以下四种值。

  • node:采用 Node.js 的 CommonJS 模块算法。
  • node16nodenext:采用 Node.js 的 ECMAScript 模块算法,从 TypeScript 4.7 开始支持。
  • classic:TypeScript 1.6 之前的算法,新项目不建议使用。

它的默认值与module属性有关,如果moduleAMDUMDSystemES6/ES2015,默认值为classic;如果modulenode16nodenext,默认值为这两个值;其他情况下,默认值为Node

moduleSuffixes

moduleSuffixes指定模块的后缀名。

  1. {
  2. "compilerOptions": {
  3. "moduleSuffixes": [".ios", ".native", ""]
  4. }
  5. }

上面的设置使得 TypeScript 对于语句import * as foo from "./foo";,会搜索以下脚本./foo.ios.ts./foo.native.ts./foo.ts

newLine

newLine设置换行符为CRLF(Windows)还是LF(Linux)。

noEmit

noEmit设置是否产生编译结果。如果不生成,TypeScript 编译就纯粹作为类型检查了。

noEmitHelpers

noEmitHelpers设置在编译结果文件不插入 TypeScript 辅助函数,而是通过外部引入辅助函数来解决,比如 NPM 模块tslib

noEmitOnError

noEmitOnError指定一旦编译报错,就不生成编译产物,默认为false

noFallthroughCasesInSwitch

noFallthroughCasesInSwitch设置是否对没有break语句(或者returnthrow语句)的 switch 分支报错,即case代码里面必须有终结语句(比如break)。

noImplicitAny

noImplicitAny设置当一个表达式没有明确的类型描述、且编译器无法推断出具体类型时,是否允许将它推断为any类型。

它是一个布尔值,默认为true,即只要推断出any类型就报错。

noImplicitReturns

noImplicitReturns设置是否要求函数任何情况下都必须返回一个值,即函数必须有return语句。

noImplicitThis

noImplicitThis设置如果this被推断为any类型是否报错。

noUnusedLocals

noUnusedLocals设置是否允许未使用的局部变量。

noUnusedParameters

noUnusedParameters设置是否允许未使用的函数参数。

outDir

outDir指定编译产物的存放目录。如果不指定,编译出来的.js文件存放在对应的.ts文件的相同位置。

outFile

outFile设置将所有非模块的全局文件,编译在同一个文件里面。它只有在module属性为NoneSystemAMD时才生效,并且不能用来打包 CommonJS 或 ES6 模块。

paths

paths设置模块名和模块路径的映射,也就是 TypeScript 如何导入requireimports语句加载的模块。

paths基于baseUrl进行加载,所以必须同时设置后者。

  1. {
  2. "compilerOptions": {
  3. "baseUrl": "./",
  4. "paths": {
  5. "b": ["bar/b"]
  6. }
  7. }
  8. }

它还可以使用通配符“*”。

  1. {
  2. "compilerOptions": {
  3. "baseUrl": "./",
  4. "paths": {
  5. "@bar/*": ["bar/*"]
  6. }
  7. }
  8. }

preserveConstEnums

preserveConstEnumsconst enum结构保留下来,不替换成常量值。

  1. {
  2. "compilerOptions": {
  3. "preserveConstEnums": true
  4. }
  5. }

pretty

pretty设置美化输出终端的编译信息,默认为true

removeComments

removeComments移除 TypeScript 脚本里面的注释,默认为false

resolveJsonModule

resolveJsonModule允许 import 命令导入 JSON 文件。

rootDir

rootDir设置源码脚本所在的目录,主要跟编译后的脚本结构有关。rootDir对应目录下的所有脚本,会成为输出目录里面的顶层脚本。

rootDirs

rootDirs把多个不同目录,合并成一个目虚拟目录,便于模块定位。

  1. {
  2. "compilerOptions": {
  3. "rootDirs": ["bar", "foo"]
  4. }
  5. }

上面示例中,rootDirsbarfoo组成一个虚拟目录。

sourceMap

sourceMap设置编译时是否生成 SourceMap 文件。

sourceRoot

sourceRoot在 SourceMap 里面设置 TypeScript 源文件的位置。

  1. {
  2. "compilerOptions": {
  3. "sourceMap": true,
  4. "sourceRoot": "https://my-website.com/debug/source/"
  5. }
  6. }

strict

strict用来打开 TypeScript 的严格检查。它的值是一个布尔值,默认是关闭的。

  1. {
  2. "compilerOptions": {
  3. "strict": true
  4. }
  5. }

这个设置相当于同时打开以下的一系列设置。

  • alwaysStrict
  • strictNullChecks
  • strictBindCallApply
  • strictFunctionTypes
  • strictPropertyInitialization
  • noImplicitAny
  • noImplicitThis
  • useUnknownInCatchVaria

打开strict的时候,允许单独关闭其中一项。

  1. {
  2. "compilerOptions": {
  3. "strict": true,
  4. "alwaysStrict": false
  5. }
  6. }

strictBindCallApply

strictBindCallApply设置是否对函数的call()bind()apply()这三个方法进行类型检查。

如果不打开strictBindCallApply编译选项,编译器不会对以三个方法进行类型检查,参数类型都是any,传入任何参数都不会产生编译错误。

  1. function fn(x: string) {
  2. return parseInt(x);
  3. }
  4. // strictBindCallApply:false
  5. const n = fn.call(undefined, false);
  6. // 以上不报错

strictFunctionTypes

strictFunctionTypes允许对函数更严格的参数检查。具体来说,如果函数 B 的参数是函数 A 参数的子类型,那么函数 B 不能替代函数 A。

  1. function fn(x:string) {
  2. console.log('Hello, ' + x.toLowerCase());
  3. }
  4. type StringOrNumberFunc = (ns:string|number) => void;
  5. // 打开 strictFunctionTypes,下面代码会报错
  6. let func:StringOrNumberFunc = fn;

上面示例中,函数fn()的参数是StringOrNumberFunc参数的子集,因此fn不能替代StringOrNumberFunc

strictNullChecks

strictNullChecks设置对nullundefined进行严格类型检查。如果打开strict属性,这一项就会自动设为true,否则为false

  1. let value:string;
  2. // strictNullChecks:false
  3. // 下面语句不报错
  4. value = null;

它可以理解成只要打开,就需要显式检查nullundefined

  1. function doSomething(x:string|null) {
  2. if (x === null) {
  3. // do nothing
  4. } else {
  5. console.log("Hello, " + x.toUpperCase());
  6. }
  7. }

strictPropertyInitialization

strictPropertyInitialization设置类的实例属性都必须初始化,包括以下几种情况。

  • 设为undefined类型
  • 显式初始化
  • 构造函数中赋值

注意,使用该属性的同时,必须打开strictNullChecks

  1. // strictPropertyInitialization:true
  2. class User {
  3. // 报错,属性 username 没有初始化
  4. username: string;
  5. }
  6. // 解决方法一
  7. class User {
  8. username = '张三';
  9. }
  10. // 解决方法二
  11. class User {
  12. username:string|undefined;
  13. }
  14. // 解决方法三
  15. class User {
  16. username:string;
  17. constructor(username:string) {
  18. this.username = username;
  19. }
  20. }
  21. // 或者
  22. class User {
  23. constructor(public username:string) {}
  24. }
  25. // 解决方法四:赋值断言
  26. class User {
  27. username!:string;
  28. constructor(username:string) {
  29. this.initialize(username);
  30. }
  31. private initialize(username:string) {
  32. this.username = username;
  33. }
  34. }

suppressExcessPropertyErrors

suppressExcessPropertyErrors关闭对象字面量的多余参数的报错。

target

target指定编译出来的 JavaScript 代码的 ECMAScript 版本,比如es2021,默认是es3

它可以取以下值。

  • es3
  • es5
  • es6/es2015
  • es2016
  • es2017
  • es2018
  • es2019
  • es2020
  • es2021
  • es2022
  • esnext

注意,如果编译的目标版本过老,比如"target": "es3",有些语法可能无法编译,tsc命令会报错。

traceResolution

traceResolution设置编译时,在终端输出模块解析的具体步骤。

  1. {
  2. "compilerOptions": {
  3. "traceResolution": true
  4. }
  5. }

typeRoots

typeRoots设置类型模块所在的目录,默认是node_modules/@types

  1. {
  2. "compilerOptions": {
  3. "typeRoots": ["./typings", "./vendor/types"]
  4. }
  5. }

types

types设置typeRoots目录下需要包括在编译之中的类型模块。默认情况下,该目录下的所有类型模块,都会自动包括在编译之中。

  1. {
  2. "compilerOptions": {
  3. "types": ["node", "jest", "express"]
  4. }
  5. }

useUnknownInCatchVariables

useUnknownInCatchVariables设置catch语句捕获的try抛出的返回值类型,从any变成unknown

  1. try {
  2. someExternalFunction();
  3. } catch (err) {
  4. err; // 类型 any
  5. }

上面示例中,默认情况下,catch语句的参数err类型是any,即可以是任何值。

打开useUnknownInCatchVariables以后,err的类型抛出的错误将是unknown类型。这带来的变化就是使用err之前,必须缩小它的类型,否则会报错。

  1. try {
  2. someExternalFunction();
  3. } catch (err) {
  4. if (err instanceof Error) {
  5. console.log(err.message);
  6. }
  7. }

参考链接