tsconfig常用配置全解

技术分享 2年前 (2022-07-20) 0 999+

基于typescript的项目的根目录下都会有一个文件(tsconfig.json), 这个文件主要用来控制typescript编译器(tsc, typescript compiler)的一些行为, 比如指定哪些文件需要让tsc来编译, 哪些文件不想让tsc进行编译之类的.

angular项目的tsconfig.json文件

tsconfig.json

/* To learn more about this file see: https://angular.io/config/tsconfig. */ {   "compileOnSave": false,   "compilerOptions": {     "baseUrl": "./",     "outDir": "./dist/out-tsc",     "sourceMap": true,     "declaration": false,     "downlevelIteration": true,     "experimentalDecorators": true,     "moduleResolution": "node",     "importHelpers": true,     "target": "es2015",     "module": "es2020",     "lib": [       "es2018",       "dom"     ]   },   "angularCompilerOptions": {     "enableI18nLegacyMessageIdFormat": false,     "strictTemplates": true   } }

这其中angularCompilerOptions顾名思义是angular专用的, 不在本文讨论范围.

include, exclude, files配置项

include: 指定要编译哪些文件, 比如只需要编译<project-dir>/src目录下的.ts源代码文件

{     "compilerOptions": {         ...     },     include: ["./src/**/*", "./demo/**/*.tsx?"] }

上面的include配置用到了两个通配符: **/, *

**/表示匹配任何子路径, 包括目录分隔符/也会被它匹配, 所以用来这个通配符后, 目录下有多少子目录都会被匹配到

*表示匹配除了目录分隔符(/)外的任何长度的字符串

?表示匹配一个除文件分隔符(/)外的任一字符

显然./src/**/*即表示匹配src文件夹下的任何子文件夹的任何文件; 而./demo/**/*.tsx?即表示匹配demo目录下任何子目录下的任意以.ts或.tsx结尾的文件

include其实就是一个白名单, 在这个白名单里被匹配到的文件才会被tsc处理编译

相对于include是作为白名单的配置, exclude选项就是一个黑名单了, 它的值和include一样是一个路径名字符串数组, 最常见的用处就是用来排除掉node_modules目录下的文件

{     "compilerOptions": {         ...     },     include: ["./src/**/*", "./demo/**/*.tsx?"],     exclude: ["node_modules/**/*"] }

当然也可以用exclude排除掉include里面包含到的文件

有些情况即使exclude了某些文件后, 编译后的代码中可能仍然包含被exclude了的内容, 比如通过import导入了被exclude了的node_modules文件夹, 此时tsc仍然会去处理被exclude了的文件, 这一点应该不难理解

files 配置的作用类似include, 也是一个白名单路径数组, 不同在于它不能使用通配符, 而必须使用精确的文件路径(可以是相对路径), 比如如果项目只有一个入口文件, 那么就可以使用在只用files配置这个文件的路径, 然后其他的文件都通过index.ts来import

tsconfig.json

{     "compilerOptions": {         ...     },     // include: ["./src/**/*", "./demo/**/*.tsx?"],     // exclude: ["node_modules/**/*"]     files: ['./src/index.ts'] }

extends配置

extends 用于在一个tsconfig.json文件中扩展其他tsconfig.json文件, 比如angular项目中有三个tsconfig配置文件: tsconfig.json, tsconfig.spec.json, tsconfig.app.json

tsconfig.json

/* To learn more about this file see: https://angular.io/config/tsconfig. */ {   "compileOnSave": false,   "compilerOptions": {     "baseUrl": "./",     "outDir": "./dist/out-tsc",     "sourceMap": true,     "declaration": false,     "downlevelIteration": true,     "experimentalDecorators": true,     "moduleResolution": "node",     "importHelpers": true,     "target": "es2015",     "module": "es2020",     "lib": [       "es2018",       "dom"     ]   },   ... }

tsconfig.app.json

{   "extends": "./tsconfig.json",   "compilerOptions": {     "outDir": "./out-tsc/app",     "types": []   },   "files": [     "src/main.ts",     "src/polyfills.ts"   ],   "include": [     "src/**/*.d.ts"   ] }

tsconfig.spec.json

/* To learn more about this file see: https://angular.io/config/tsconfig. */ {   "extends": "./tsconfig.json",   ...   "files": [     "src/test.ts",     "src/polyfills.ts"   ],   "include": [     "src/**/*.spec.ts",     "src/**/*.d.ts"   ] }

从命名和文件内容上即可看出之所以这么做是为了针对测试文件.spec.ts和普通.ts文件在使用不同的配置时又能共享他们相同部分的配置, 达到避免重复的目的

compilerOptions下的配置

compilerOptions.allowUnreachableCode

表示是否允许代码中出现永远无法被执行到的代码, 可选值是undefined, false, true

{     "compilerOptions": {         "allowUnreachableCode": false         ...     },     ... }

什么是"永远无法被执行到的代码"?

const foo = () => {     return 0;      console.log('aaa'); // 这一行代码就是永远被执行到的代码 }

配置为undefined时, 遇到这种情况会给出warning, 配置false则直接编译时抛出错误无法成功编译, 配置为true既没有警告也没有错误

compilerOptions.allowUnusedLabels

这个选项是针对标签(label)语法的, 这个语法很罕见, 我也是看到了这个配置才知道有这个原来js还有Label语法, label语法有点像其他语言里的goto, 真是场景中几乎不用

compilerOptions.allowUnusedLabels表示是否允许未使用到的标签

可选项:

undefined: 这是默认值, 碰到未使用的标签给出warning警告
false: 碰到未使用的标签抛出错误, 编译失败
true: 碰到未使用的标签编译通过, 且不给出异常

function bar() {     console.log('loafing...');      loop: for (let i = 0; i < 3; i++) {         for (let j = 0; j < 3; j++) {             if (i === 2) {                 // break loop;             }             console.log(i, j, i + j);         }     } }

compilerOptions.alwaysStrict

默认值是true, 开启这个选项保证输出的js代码处于ECMAScript标准的严格模式下, 也就是js文件里的use strict

compilerOptions.exactOptionalProperties

这是typescript4.4中才加入的一个选项, 默认处于不开启状态; 开启此选项, typescript会对可空属性执行更严格的类型检查, 可空属性只有在初始化时可以留空为undefined, 但是不能被手动设置为undefined

例如有一个IFoo接口

interface IFoo {   foo?: string; }

在compilerOptions.exactOptionalProperties = false情况下

const obj: IFoo = {}; obj.foo = '1111'; console.log(obj.foo); obj.foo = undefined; console.log(obj.foo);

这段代码可以正常编译通过

但如果开启compilerOptions.exactOptionalProperties选项后情况就不同了

const obj: IFoo = {}; obj.foo = '1111'; console.log(obj.foo);  // 编译器会报: Type 'undefined' is not assignable to type 'string' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the type of the target. obj.foo = undefined; console.log(obj.foo);  // 这一行会报: Type '{ foo: undefined; }' is not assignable to type 'IFoo' with 'exactOptionalPropertyTypes: true'.  const obj2: IFoo = {   foo: undefined }

compilerOptions.downlevelIteration

先解释下什么是Downleveling? Downleveling是Typescript中的一个术语, 它表示将typescript代码转译为相对更低版本的javascript

这个标志位模式是不开启的.

开启这个标志位typescript会生成一个帮助方法来对es6中的for of和数组展开([...arr])语法进行转译, 以兼容es3/es5

下面的示例用for of循环并输出一个包含符号表情的字符串:

const text = `(😜)`; for (const c of text) {   console.log(c); }

如果配置typescript的compilerOptions.target选项为es6及以上, 那么不管有没有开启compilerOptions.downlevelIteration, 输出都是:

( 😜 )

现在把compilerOptions.target设置为es5并关闭compilerOptions.downlevelIteration, 输出:

控制台中一共有四行, 中间两行是两个乱码, 这跟我们的预期的就不一样了, 我们预期应该只有三行输出, 实际结果确是符号表情被分成了两个乱码字符输出了;

这是因为没开启compilerOptions.downlevelIteration, typescript处理for of时会直接转译成经典的索引迭代(for (var _i = 0, text_1 = text; _i < text_1.length; _i++)), 而符号表情实际上占了2个字节的存储, 所以自然就会将符号表情分成两个乱码字符输出了

现在再开启compilerOptions.downlevelIteration, 此时typescript处理for...of时会通过辅助方法调用数组对象的Symbol.iterator属性做一些额外的检查和处理, 就能正常输出了

此时生成的js代码:

"use strict"; var __values = (this && this.__values) || function(o) {     var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;     if (m) return m.call(o);     if (o && typeof o.length === "number") return {         next: function () {             if (o && i >= o.length) o = void 0;             return { value: o && o[i++], done: !o };         }     };     throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined."); }; var e_1, _a; var text = "(uD83DuDE1C)"; try {     for (var text_1 = __values(text), text_1_1 = text_1.next(); !text_1_1.done; text_1_1 = text_1.next()) {         var c = text_1_1.value;         console.log(c);     } } catch (e_1_1) { e_1 = { error: e_1_1 }; } finally {     try {         if (text_1_1 && !text_1_1.done && (_a = text_1.return)) _a.call(text_1);     }     finally { if (e_1) throw e_1.error; } }

更具体的说明看官网: https://www.typescriptlang.org/tsconfig#downlevelIteration

compilerOptions.importHelpers

上面介绍了compilerOptions.downlevelIteration选项, 开启后会对for...of之类的迭代语法糖进行downleveling; typescript进行downleveling时, 会生成一些辅助方法, 默认情况下, 这些辅助代码是会直接插入到文件中对应的位置的, 这会生成的javascript存在重复的辅助方法从而造成代码文件体积过大的问题.

开启compilerOptions.importHelpers后, 不在插入具体的辅助方法的代码到对应的位置, 而是通过模块导入来引用typescript的辅助方法

看这段typescript

export const foo = () => {   const text = `(😜)`    for (const c of text) {     console.log(c)   } }

没开启compilerOptions.importHelpers时, 生成的javascript:

var __values = (this && this.__values) || function(o) {     var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;     if (m) return m.call(o);     if (o && typeof o.length === "number") return {         next: function () {             if (o && i >= o.length) o = void 0;             return { value: o && o[i++], done: !o };         }     };     throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined."); }; export var foo = function () {     var e_1, _a;     var text = "(uD83DuDE1C)";     try {         for (var text_1 = __values(text), text_1_1 = text_1.next(); !text_1_1.done; text_1_1 = text_1.next()) {             var c = text_1_1.value;             console.log(c);         }     }     catch (e_1_1) { e_1 = { error: e_1_1 }; }     finally {         try {             if (text_1_1 && !text_1_1.done && (_a = text_1.return)) _a.call(text_1);         }         finally { if (e_1) throw e_1.error; }     } };

开启compilerOptions.importHelpers后, 生成的javascript:

import { __values } from "tslib"; export var foo = function () {     var e_1, _a;     var text = "(uD83DuDE1C)";     try {         for (var text_1 = __values(text), text_1_1 = text_1.next(); !text_1_1.done; text_1_1 = text_1.next()) {             var c = text_1_1.value;             console.log(c);         }     }     catch (e_1_1) { e_1 = { error: e_1_1 }; }     finally {         try {             if (text_1_1 && !text_1_1.done && (_a = text_1.return)) _a.call(text_1);         }         finally { if (e_1) throw e_1.error; }     } };

compilerOptions.strict

这个strict相关标志位的一个总开关, 设置为true会启用全部compilerOptions.strict开头的选项和其他相关的选项, 如compilerOptions.strictNullChecks, compilerOptions.strictPropertyInitialization, compilerOptions.noImplicitAny ...

开启此选项后, 依然可以单独关闭某个具体的以compilerOptions.strict开头的选项

compilerOptions.strictBindCallApply

开启此选项后, 调用函数对象的bind call和apply方法时typescript会执行参数类型检查确保参数类型兼容

const foo = (a: string, b: number) => {   console.log(a, b); }  // 开启 strictBindCallApply 后，会报错 // Argument of type 'number' is not assignable to parameter of type 'string'. foo.call(undefined, 1, 2)

compilerOptions.strictFunctionTypes

开启此选项会启用严格的函数类型检查, 直接看示例:

const foo = (a: string) => {   console.log(a); }  interface Bar {   (a: string | string[]): void; }  // 开启 compilerOptions.strictFunctionTypes, 报错 // Type '(a: string) => void' is not assignable to type 'Bar'. const bar:Bar = foo;

修改成:

const foo = (a: string) => {   console.log(a); }  interface Bar {   (a: string): void; }  const bar:Bar = foo;

才能通过编译

compilerOptions.strictNullChecks

开启此选项让typescript执行严格的null检查

const foo: string|null|undefined = undefined;  // 不开启 compilerOptions.strictNullChecks ，不会有编译时错误，但是运行时会出现异常（Cannot read properties of undefined ） // 开启 compilerOptions.strictNullChecks，会出现编译时错误（Object is possibly 'undefined'） console.log(foo.length)

compilerOptions.strictPropertyInitialization

开启此选项让typescript严格的对象属性初始化检查

开启后这段代码会出现编译时错误:

class Foo {   // Property 'foo' has no initializer and is not definitely assigned in the constructor.   foo: string; }

改成

class Foo {   foo = 'foo'; }

或者

class Foo {   foo: string;    constructor() {     this.foo = '';       } }

或者在属性后加感叹号进行非空断言(non-null assertion)

class Foo {   foo!: string; }

方能编译通过

compilerOptions.noImplicitAny

这个配置还是比较好理解的, 就是开启此选项后, 如果你声明一个没有标注类型的变量, 编译器会会给你一个编译时错误(Parameter 'arg' implicitly has an 'any' type.)

给foo函数参数arg标注一个string类型可以消除这个错误

const foo = (arg: string) => { console.log(arg) };  foo('hello');

另外要注意如果开启了compilerOptions.strict选项, 那么这个选项默认就会处于开启状态, 除非手动将这个选项配置为false

compilerOptions.noImplicitOverride

typescript 4.3中才引入的配置

这个选项从名字上也是比较好理解的; 开启此选项保证子类重写基类的方法时, 必须在方法前加上override关键词

class BillBuilder {     build() {} }  class MonthBillBuilder extends BillBuilder {     // 开启 compilerOptions.noImplicitOverride 后，重写 build 方法必须显示加上 override 关键词，否则编译器会报错：     // This member must have an 'override' modifier because it overrides a member in the base class 'BillBuilder'.     build() {         console.log('Monthly bill')     } }

正确的写法:

class BillBuilder {     build() {} }  class MonthBillBuilder extends BillBuilder {     override build() {         console.log('Monthly bill')     } }

compilerOptions.noImplicitReturns

开启这个选项保证编译时所有条件分支都返回一致的类型, 比如说一个if分支下返回了一个string类型, 但是其他分支没有进行return, 那么tsc会给出一个编译时错误(Not all code paths return a value.(7030) )

正确的写法1:

const hello = (log = false) => {     if (log) {         const text = 'hello';         console.log(text);         return text     }      return ''; }

正确的写法2:

const hello = (log = false): string | void => {     if (log) {         const text = 'hello';         console.log(text);         return text     } }

compilerOptions.noImplicitThis

开启这个选项后, typescript将禁止调用any类型的this

错误示例:

function Color() {     // 开启了ompilerOptions.noImplicitThis的情况下，下面的三行代码会出现编译时错误     // 'this' implicitly has type 'any' because it does not have a type annotation.     this.r = 255;     this.g = 255;     this.b = 255; }  // 如果开启了 compilerOptions.noImplicitAny , 那么这一行也是会报编译时错误的: // 'new' expression, whose target lacks a construct signature, implicitly has an 'any' type. const c = new Color();  console.log(c.r, c.r, c.b);

正确的写法:

class Color {     r = 255;     g = 255;     b = 255; }  const c = new Color();  console.log(c.r, c.r, c.b);

compilerOptions.noPropertyAccessFromIndexSignature

这个配置选项typescript4.2中才引入

从名称入手来理解这个配置, no property access from index signature, 就是说开启后禁止通过访问常规属性的方法来访问index signature声明的属性

常规属性通过在对象后加一个.即可访问如obj.title

什么是index signature? 直译过来是索引签名, 索引签名语法一般用来声明接口或类中的未知属性的, index signature的示例:

// 标注为IFoo类型的对象可以添加任意的字符串键值对 interface IFoo {   [key: string]: string; }  const foo: IFoo = {   bar: '1' }  console.log(foo['bar']); // 输出: 1

开启compilerOptions.noPropertyAccessFromIndexSignature后的一个错误示例:

class Color {     r = 255;     g = 255;     b = 255;      [key: string]: string | number; }  const c = new Color();  console.log(c.r, c.g, c.b);  // 开启 compilerOptions.noPropertyAccessFromIndexSignature 的情况下，会有编译时错误： // Property 'foo' comes from an index signature, so it must be accessed with ['foo']. console.log(c.foo);

正确的方式应该是通过c['foo']访问Color对象c上的foo属性

这个选项的动机是什么?

不开启compilerOptions.noPropertyAccessFromIndexSignature直接通过传统的.符号来访问索引签名属性, 一不小心非常容易造成运行时出现经典的read property of undefined异常, 比如上面的示例如果直接调用c.foo.toString(), 即使开启了compilerOptions.strictNullChecks编译仍能通过, 但是运行就会发生异常; 当然也可以显示标注索引签名属性为可空类型配置compilerOptions.strictNullChecks来达到相同的目的

class Color {     r = 255;     g = 255;     b = 255;      [key: string]: string | number | undefined; }  const c = new Color();  console.log(c.r, c.g, c.b);  // 关闭 compilerOptions.noPropertyAccessFromIndexSignature，开启 compilerOptions.strictNullChecks // 仍然可以获得编译时的对象属性可能为空的错误： // Object is possibly 'undefined'. console.log(c.foo.toString());

compilerOptions.noUncheckedIndexedAccess

这个配置选项typescript4.1中才引入

开启这个选项, typescript自动给索引签名语法声明的属性补上一个undefined类型; 上面介绍compilerOptions.noPropertyAccessFromIndexSignature时提到可以自己手动给索引签名语法声明的属性加上undefined类型标注达到和开启compilerOptions.noPropertyAccessFromIndexSignature相同的目的

看上面的图片中虽然没有显示给索引签名属性标注undefined, 但是鼠标悬浮到c.foo上时typescript自动给它加上了undefined

compilerOptions.noUnusedLocals

又是一个很好理解的配置选项, 开启这个选项, 当typescript发现未使用的局部变量时, 会给出一个编译时错误('<propertyName>' is declared but its value is never read.(6133))

const sayHello = () => {     // 开启 compilerOptions.noUnusedLocals 后，typescript编译时会报错     // 'text' is declared but its value is never read.     const text = 'hello';     console.log('hello'); }

✅正确的做法:

const sayHello = () => {     const text = 'hello';     console.log(text); }

compilerOptions.noUnusedParameters

和上面的compilerOptions.noUnusedLocals, 不同之处在于局部变量变成了函数参数

❌错误示例:

// 开启 compilerOptions.noUnusedParameters 后，typescript编译时会报错 // 'text' is declared but its value is never read. const sayHello = (text: string) => {     console.log('hello'); }

✅正确的写法:

// 开启 compilerOptions.noUnusedParameters 后，typescript编译时会报错 // 'text' is declared but its value is never read. const sayHello = (text: string) => {     console.log(text); }

compilerOptions.useUnknownInCatchVariables

这个配置选项typescript4.4中才引入

开启这个选项typescript会将catch语法块中的err变量当做unknown来处理, 不开启此选项时, err变量是被当做any类型来处理的, 这很容易造成经典的read property of undefined运行时异常

一个简单的示例, 不开启compilerOptions.useUnknownInCatchVariables选项运行时才能发布异常

开启了compilerOptions.useUnknownInCatchVariables选项, 编译时立即发现问题

小结

本文主要介绍了typescript中类型检查相关的配置, typescript还有其他不少配置的, 官网都有详细的文档

我对typescript一些看法

我是18年大二阶段开始接触前端相关的编程语言的, 那个时候typescript还没有这么流行, 接触使用学习时还是以js为主的; 此前主主要使用的语言的是C/C++ C#这些强类型语言, 对js存在强烈的抵触甚至厌恶, 然后接触到angular时发现它的整个生态都是构建在typescript之上的, 终于遇到了救星; 虽然那个时候刚刚接触, angular用起来也是一知半解的, 常常被typescript中如何使用js库之类的小白问题支配, 但是相比要我写没有类型注解的javascript, 那时的我依然选择慢慢摸索解决typescript中如何使用js库这样的小白问题, 解决这些问题过程中, 我对js也有了更深入的理解, 慢慢的我甚至可以脱离typescript学会写javascript了😂typescript的定位是javascript的超集, 与我而言, typescript确实我在javascript上的老师, 没有typescript, 那个时候的我可能已经放弃学习javascript了, 就像叫不醒一个装睡的人一样, 我们永远也学不会一门自己不想学设置讨厌的的编程语言; 也不是说没有typescript就永远都不会对javascript产生兴趣, 而是产生兴趣的时间会延后到不知何时;

typescript是一个良师益友, 不敢想象没有typescript的世界将会是怎样😇或许也并不会怎样, 只不过少了一个爱写前端的靓仔而已🌚

发表评论