右耳听风
0%

tsconfig.json文件解析

发表于

前言

TypeScript带来的类型系统以及强大的IDE支持，让前端开发也变得严谨而流畅。但TypeScript不是原生的Javascript代码，需要进行编译才能转换为Javascript代码。

tsconfig.json是编译TypeScript的配置文件，对书写TypeScript代码十分重要。接下来会介绍一些常用的编译选项和所有tsconfig.json选项的解释。

常用属性

1.experimentalDecorators

是否启用实验性的ES装饰器。 默认值：false, 官方解释

TypeScript 和 ES6 中引入了 Class 的概念，同时在 stage 2 proposal (opens new window)提出了 Java 等服务器端语言早就有的装饰器模式。通过引入装饰器模式，能极大简化书写代码，把一些通用逻辑封装到装饰器中。

2.strictPropertyInitialization

是否类的非undefined属性已经在构造函数里初始化。 默认值：false

1
2
3
export default class Home {
  id: string // 如果开启strictPropertyInitialization，则这里会报错，因为没有赋值默认值
}

3.noImplicitAny

有隐含的 any类型时是否报错。 默认值：false

ts 是有默认推导的，同时还有 any 类型，所以不是每个变量或参数定义需要明确告知类型是什么。如果开启该值，当有隐含 any 类型时，会报错。

1
2
3
// 当开启noImplicitAny时，需要隐含当any需要明确指出
arr.find((item) => item.name === name) // error
arr.find((item: any) => item.name === name) // ok

4.target

指定编译的ECMAScript目标版本。默认值: “ES3”官方解释
枚举值：”ES3”， “ES5”， “ES6”/ “ES2015”， “ES2016”， “ES2017”，”ES2018”，”ES2019”，”ES2020”，”ES2021”，”ES2022”，”ESNext”

target: “ESNext” 是指 tc39 最新的ECMAScript proposals

当编译 ts 代码时，可以把 ts 转为 ES5 或更早的 js 代码。所以需要选择一个编译的目标版本。

5.module

指定生成哪个模块系统代码 官方解释

枚举值：”None”， “CommonJS”， “AMD”， “System”， “UMD”， “ES6”， “ES2015”，”ES2020”, “ES2022”, “ESNext”, “node16”, “nodenext”,

默认值根据–target 选项不同而不同，当 target 设置为 ES6 时，默认 module 为“ES6”，否则为“commonjs”

6.lib

编译过程中需要引入的库文件的列表

string[]类型，可选的值有很多，常用的有 ES5，ES6，ESNext，DOM，DOM.Iterable、WebWorker、ScriptHost 等。

该值默认值是根据–target 选项不同而不同。
当 target 为 ES5 时，默认值为[‘DOM ‘, ‘ES5’, ‘ScriptHost’];
当 target 为 ES6 时，默认值为[‘DOM’, ‘ES6’, ‘DOM.Iterable’, ‘ScriptHost’]

7.moduleResolution

决定如何处理模块 官方解释

说直白点，也就是遇到 import { AAA } from ‘./aaa’该如何去找对应文件模块解析。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// 在源文件/root/src/A.ts中import { b } from "./moduleB"
// 两种解析方式查找文件方式不同

// classic模块解析方式
1. /root/src/moduleB.ts
2. /root/src/moduleB.d.ts

// node模块解析方式
1. /root/src/moduleB.ts
2. /root/src/moduleB.tsx
3. /root/src/moduleB.d.ts
4. /root/src/moduleB/package.json (if it specifies a "types" property)
5. /root/src/moduleB/index.ts
6. /root/src/moduleB/index.tsx
7. /root/src/moduleB/index.d.ts

8.paths

模块名或路径映射的列表

这是一个非常有用的选项，比如我们经常使用‘@/util/help’来代替’./src/util/help’，省的每次在不同层级文件 import 模块时,都纠结于是’./‘还是’../‘。该选项告诉编译器遇到匹配的值时，去映射的路径下加载模块。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
    "baseUrl": ".", // 注意：baseUrl不可少
    "paths": {
      // 映射列表
      "@/*": [
        "src/*"
      ],
      "moduleA": [
        "src/libs/moduleA"
      ]
    }
}

// in ts code
import Setting from '@/components/Setting.vue' // 模块实际位置: src/components/Setting.vue
import TestModule from 'moduleA/index.js' // 模块实际位置: src/libs/moduleA/index.js

9.strictNullChecks

是否启用严格的 null检查模式 默认值: false 建议开启该选项

未处理的 null 和 undefined 经常会导致 BUG 的产生，所以 TypeScript 包含了 strictNullChecks 选项来帮助我们减少对这种情况的担忧。当启用了 strictNullChecks，null 和 undefined 获得了它们自己各自的类型 null 和 undefined。开启该模式有助于发现并处理可能为 undefined 的赋值。

1
2
3
4
5
6
7
8
9
// 未开启strictNullChecks，number类型包含了null和undefined类型
let foo: number = 123
foo = null // Okay
foo = undefined // Okay

// 开启strictNullChecks
let foo: string[] | undefined = arr.find((key) => key === 'test')
// foo.push('1') // error - 'foo' is possibly 'undefined'
foo && foo.push('1') // okay

注意：启用 –strict 相当于启用 –noImplicitAny, –noImplicitThis, –alwaysStrict, –strictNullChecks, –strictFunctionTypes 和–strictPropertyInitialization

10.noUnusedLocals

有未使用的变量时，是否抛出错误 默认值: false

当发现变量定义但没有使用时，编译不报错。eslint 的 rule 中也有该条，建议正式项目将该选项开启，设置为 true，使得代码干净整洁

11.noUnusedParameters

有未使用的参数时，是否抛出错误 默认值: false

建议开启，理由同上。

12.allowJs

是否允许编译javascript文件 默认值: false

如果设置为 true，js 后缀的文件也会被 typescript 进行编译。

13.typeRoots 和 types

默认所有可见的”@types”包会在编译过程中被包含进来。如果指定了 typeRoots，只有 typeRoots 下面的包才会被包含进来。如果指定了 types，只有被列出来的 npm 包才会被包含进来。详细解释

可以指定”types”: []来禁用自动引入@types 包#14. files、include 和 exclude

14.files、include 和 exclude

编译文件包含哪些文件以及排除哪些文件

未设置 include 时，编译器默认包含当前目录和子目录下所有的 TypeScript 文件（.ts, .d.ts 和 .tsx）。如果 allowJs 被设置成 true，JS 文件（.js 和.jsx）也被包含进来。exclude 排除那些不需要编译的文件或文件夹。

1
2
3
4
5
6
7
8
9
10
{
    "compilerOptions": {},
    "include": [
        "src/**/*"
    ],
    "exclude": [
        "node_modules",
        "**/*.spec.ts"
    ]
}

全解析

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
{
  "compilerOptions": {
    /* 基本选项 */
    "target": "es5",                       // 指定 ECMAScript 目标版本: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', or 'ESNEXT'（"ESNext"表示最新的ES语法，包括还处在stage X阶段）
    "module": "commonjs",                  // 指定使用模块: 'commonjs', 'amd', 'system', 'umd' or 'es2015'
    "lib": [],                             // 指定要包含在编译中的库文件
    "allowJs": true,                       // 允许编译 javascript 文件
    "checkJs": true,                       // 报告 javascript 文件中的错误
    "jsx": "preserve",                     // 指定 jsx 代码的生成: 'preserve', 'react-native', or 'react'
    "declaration": true,                   // 生成相应的 '.d.ts' 文件
    "sourceMap": true,                     // 生成相应的 '.map' 文件
    "outFile": "./",                       // 将输出文件合并为一个文件
    "outDir": "./",                        // 指定输出目录
    "rootDir": "./",                       // 用来控制输出目录结构 --outDir.
    "removeComments": true,                // 删除编译后的所有的注释
    "noEmit": true,                        // 不生成输出文件
    "importHelpers": true,                 // 从 tslib 导入辅助工具函数
    "isolatedModules": true,               // 将每个文件做为单独的模块 （与 'ts.transpileModule' 类似）.

    /* 严格的类型检查选项 */
    "strict": true,                        // 启用所有严格类型检查选项
    "noImplicitAny": true,                 // 在表达式和声明上有隐含的 any类型时报错
    "strictNullChecks": true,              // 启用严格的 null 检查
    "noImplicitThis": true,                // 当 this 表达式值为 any 类型的时候，生成一个错误
    "alwaysStrict": true,                  // 以严格模式检查每个模块，并在每个文件里加入 'use strict'

    /* 额外的检查 */
    "noUnusedLocals": true,                // 有未使用的变量时，抛出错误
    "noUnusedParameters": true,            // 有未使用的参数时，抛出错误
    "noImplicitReturns": true,             // 并不是所有函数里的代码都有返回值时，抛出错误
    "noFallthroughCasesInSwitch": true,    // 报告 switch 语句的 fallthrough 错误。（即，不允许 switch 的 case 语句贯穿）

    /* 模块解析选项 */
    "moduleResolution": "node",            // 选择模块解析策略： 'node' (Node.js) or 'classic' (TypeScript pre-1.6)。默认是classic
    "baseUrl": "./",                       // 用于解析非相对模块名称的基目录
    "paths": {},                           // 模块名到基于 baseUrl 的路径映射的列表
    "rootDirs": [],                        // 根文件夹列表，其组合内容表示项目运行时的结构内容
    "typeRoots": [],                       // 包含类型声明的文件列表
    "types": [],                           // 需要包含的类型声明文件名列表
    "allowSyntheticDefaultImports": true,  // 允许从没有设置默认导出的模块中默认导入。

    /* Source Map Options */
    "sourceRoot": "./",                    // 指定调试器应该找到 TypeScript 文件而不是源文件的位置
    "mapRoot": "./",                       // 指定调试器应该找到映射文件而不是生成文件的位置
    "inlineSourceMap": true,               // 生成单个 soucemaps 文件，而不是将 sourcemaps 生成不同的文件
    "inlineSources": true,                 // 将代码与 sourcemaps 生成到一个文件中，要求同时设置了 --inlineSourceMap 或 --sourceMap 属性

    /* 其他选项 */
    "experimentalDecorators": true,        // 启用装饰器
    "emitDecoratorMetadata": true,         // 为装饰器提供元数据的支持
    "strictFunctionTypes": false           // 禁用函数参数双向协变检查。
  },
  /* 指定编译文件或排除指定编译文件 */
  "include": [
      "src/**/*"
  ],
  "exclude": [
      "node_modules",
      "**/*.spec.ts"
  ],
  "files": [
    "core.ts",
    "sys.ts"
  ],
  // 从另一个配置文件里继承配置
  "extends": "./config/base",
  // 让IDE在保存文件的时候根据tsconfig.json重新生成文件
  "compileOnSave": true // 支持这个特性需要Visual Studio 2015， TypeScript1.8.4以上并且安装atom-typescript插件
}