likes
comments
collection
share

TS都出了这么久了，你还看不懂它的配置文件吗

作者站长头像
站长
· 阅读数 6

前言

tsconfig.json是 TypeScript 项目的配置文件，放在项目的根目录。文件的格式，是一个 JSON 对象，最简单的情况可以只放置一个空对象{}。

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

这些我们都会在后面进行详细的讲解。

如果你也和我一样在为大厂冲刺的话，欢迎添加我的微信lx3122178991，这里有一群小伙伴有着和你同样的目标，欢迎来一起讨论，一同进步。

include

include属性指定所要编译的文件列表，文件位置相对于当前配置文件而定。

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

exclude

exclude属性是一个数组，必须与include属性一起使用，用来从编译列表中去除指定的文件。

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

extends

extends属性用来指定所要继承的配置文件。

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

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

files

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

它是一个数组，排在前面的文件先编译。但是files必须逐一列出文件，不支持文件匹配。建议还是使用include和exclude属性最好。

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

references

references属性是一个数组，数组成员为对象，用来设置需要引用的底层项目。

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

compilerOptions

compilerOptions属性用来定制编译行为。可以省略，省略后编译器将使用默认设置进行编译。

allowJs

allowJs允许TS项目加载JS脚本。

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

alwaysStrict

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

allowSyntheticDefaultImports

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

allowUnreachableCode

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

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

allowUnusedLabels

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

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

baseUrl

baseUrl的值为字符串，指定 TS项目的基准目录。

checkJs

checkJS设置对JS文件同样进行类型检查。打开这个属性，也会自动打开allowJs。

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

declaration

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

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

declarationDir

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

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

declarationMap

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

{
  "compilerOptions": {
    "declaration": true,
    "declarationMap": true
  }
}

forceConsistentCasingInFileNames

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

incremental

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

inlineSourceMap

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

inlineSources

inlineSources设置将原始的.ts代码嵌入编译后的 JS 中。它要求sourceMap或inlineSourceMap至少打开一个。

jsx

jsx设置如何处理.tsx文件。它可以取以下五个值。

  • preserve：保持 jsx 语法不变，输出的文件名为.jsx。
  • react：将<div />编译成React.createElement("div")，输出的文件名为.js。
  • react-native：保持 jsx 语法不变，输出的文件后缀名为.js。
  • react-jsx：将<div />编译成_jsx("div")，输出的文件名为.js。
  • react-jsxdev：跟react-jsx类似，但是为_jsx()加上更多的开发调试项，输出的文件名为.js。
{
  "compilerOptions": {
    "jsx": "preserve"
  }
}

lib

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

{
  "compilerOptions": {
    "lib": ["dom", "es2021"]
  }
}

listEmittedFiles

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

{
  "compilerOptions": {
    "listEmittedFiles": true
  }
}

listFiles

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

{
  "compilerOptions": {
    "listFiles": true
  }
}

mapRoot

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

{
  "compilerOptions": {
    "sourceMap": true,
    "mapRoot": "https://my-website.com/debug/sourcemaps/"
  }
}

module

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

{
  "compilerOptions": {
    "module": "commonjs"
  }
}

newLine

newLine设置换行符为CRLF（Windows）还是LF（Linux）。

noEmit

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

noEmitHelpers

noEmitHelpers设置在编译结果文件不插入TS辅助函数，而是通过外部引入辅助函数来解决。

noEmitOnError

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

noFallthroughCasesInSwitch

noFallthroughCasesInSwitch设置是否对没有break语句（或者return和throw语句）的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属性为None、System、AMD时才生效，并且不能用来打包 CommonJS 或 ES6 模块。

paths

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

{
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "b": ["bar/b"]
    }
  }
}

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

{
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "@bar/*": ["bar/*"]
    }
  }
}

preserveConstEnums

preserveConstEnums将const enum结构保留下来，不替换成常量值。

{
  "compilerOptions": {
    "preserveConstEnums": true
  }
}

pretty

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

removeComments

removeComments移除TS脚本里面的注释，默认为false。

resolveJsonModule

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

sourceMap

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

sourceRoot

sourceRoot设置TS源文件的位置。

{
  "compilerOptions": {
    "sourceMap": true,
    "sourceRoot": "https://my-website.com/debug/source/"
  }
}

strict

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

{
  "compilerOptions": {
    "strict": true
  }
}

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

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

strictBindCallApply

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

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

function fn(x: string) {
  return parseInt(x);
}

// strictBindCallApply:false
const n = fn.call(undefined, false);
// 以上不报错

strictFunctionTypes

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

function fn(x:string) {
  console.log('Hello, ' + x.toLowerCase());
}

type StringOrNumberFunc = (ns:string|number) => void;

// 打开 strictFunctionTypes，下面代码会报错
let func:StringOrNumberFunc = fn;

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

strictNullChecks

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

let value:string;

// strictNullChecks:false
// 下面语句不报错
value = null;

strictPropertyInitialization

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

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

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

suppressExcessPropertyErrors

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

target

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