Top Level

{
  "extends": "",
  "compilerOptions": {},
  "include": [],
  "exclude": [],
  "files": [],
  "references": [],
  "watchOptions": {},
  "typeAcquisition": {}
}

extends

extends 是一个继承其他配置文件的 String,也可以使用 Node.js style 进行解析.

解析规则:

• 首先会加载解析集成的文件,然后由配置文件中的配置覆盖.在配置文件中找到的所有相对路径都将相对于它们所在的配置文件进行解析。
• extends 不会继承 files,include,exclude.

compilerOptions

指定 typescript 的编译配置。

type checking

allowUnreachableCode

是否允许代码中包含用不执行的代码

• undefined(default) 向编辑器提供建议作为警告
• true 允许
• false 不允许，编辑器报错

example: "allowUnreachableCode": false

function fn(n: number) {
  if (n > 5) {
    return true
  } else {
    return false
  }
  return true
  // error: Unreachable code detected. 永远不会执行
}

allowUnusedLabels

是否允许未被使用的 labels。日常开发很少见到。

• undefined(default) 向编辑器提供建议作为警告
• true 允许
• false 不允许，编辑器报错

expample: "allowUnusedLabels": false

function verifyAge(age: number) {
  // Forgot 'return' statement
  if (age > 18) {
    verified: true;
    Unused label. // [!code error]
  }
}

alwaysStrict

确保文件在 ECMAScript 严格模式下解析，并对每个源文件添加use strict。

ECMAScript 严格模式是在 ES5 中引入的，它为 JavaScript 引擎的运行时提供行为调整以提高性能，并抛出一组错误，而不是默默地忽略它们。

exactOptionalPropertyTypes

启用了 exactOptionalPropertyTypes 后，TypeScript 对如何处理类型或接口上的属性采用了更严格的规则。

example:"exactOptionalPropertyTypes": true

interface Theme {
  colorThemeOverride?: 'dark' | 'light'
}

如果没有启用,colorThemeOverride可以是undefined,dark,light 如果启用,

const theme: Theme = {}

theme.colorThemeOverride = 'dark'
theme.colorThemeOverride = 'light'

theme.colorThemeOverride = undefined // [!code error]

noFallthroughCasesInSwitch

"noFallthroughCasesInSwitch":true 在 switch 语句中报告故障情况的错误。确保 switch 语句中的任何非空情况包括 break、return 或 throw。

noImplicitAny

在某些没有类型注解的情况下，当 TypeScript 无法推断变量的类型时，它会退回到 any 类型。 'noImplicitAny':true

function fn(s) {
  console.log(s.subtr(3))
  // Parameter 's' implicitly has an 'any' type. Error
}

noImplicitOverride

在 TypeScript 编译器中启用了 noImplicitOverride，就可以强制子类方法在覆盖父类方法时 显式声明 override

class Album {
  setup() {}
}

class MLAlbum extends Album {
  override setup() {}
}

class SharedAlbum extends Album {
  setup() {} // [!code error] 子类重写父方法时，必须显式声明 override,否则报错
}

noImplicitReturns

当启用时，TypeScript 会检查函数中的所有代码路径，以确保它们 return a value

noImplicitThis

对带有隐含‘ any ’类型的‘ this ’表达式引发错误。

noPropertyAccessFromIndexSignature

这个设置确保了通过（obj.key）语法和（obj["key"]）访问字段与在类型中声明属性的方式之间的一致性

example: "noPropertyAccessFromIndexSignature": flaseTypeScript 将允许你使用点语法来访问未定义的字段

interface GameSettings {
  // Known up-front properties
  speed: "fast" | "medium" | "slow";
  quality: "high" | "low";

  // Assume anything unknown to the interface
  // is a string.
  [key: string]: string;
}

const settings = getSettings();
settings.speed;

(property) GameSettings.speed: "fast" | "medium" | "slow"
settings.quality;

(property) GameSettings.quality: "high" | "low"

// Unknown key accessors are allowed on
// this object, and are `string`
//不报错
settings.username;

example: "noPropertyAccessFromIndexSignature": true打开该标志将引发错误，因为未知字段不允许使用（obj.key）点语法来访问未定义的字段,需要使用（obj['username']）索引签名访问。

const settings = getSettings()
settings.speed
settings.quality

// This would need to be settings["username"];
settings.username //报错

noUncheckedIndexedAccess

noUnusedLocals

报告未使用的局部变量错误.

noUnusedParameters

报告未使用的函数参数错误。

strict

开启 strict 支持广泛、严格的类型检查行为.开启此选项时，也会启用所有 strict 系列的配置。

strictBindCallApply

TypeScript 会检查调用 call、bind 和 apply 函数的内置方法时是否使用了底层函数的正确参数

strictFunctionTypes

strictNullChecks

当 strictNullChecks 为 false 时，语言会有效地忽略 null 和 undefined。这可能导致在运行时出现意外错误。

当 strictNullChecks 为 true 时，null 和 undefined 有自己不同的类型

strictPropertyInitialization

'strictPropertyInitialization':true当一个类属性被声明但没有在构造函数中设置时报错。

class UserAccount {
  name: string
  accountType = 'user'

  email: string //报错
  //Property 'email' has no initializer and is not definitely assigned in the constructor.
  address: string | undefined

  constructor(name: string) {
    this.name = name
    // Note that this.email is not set
  }
}

useUnknownInCatchVariables

在 TypeScript 4.0 中，添加了允许将 catch 子句中的变量类型从 any 更改为 unknown 的支持

try {
  // ...
} catch (err: unknown) {
  // We have to verify err is an
  // error before using it as one.
  if (err instanceof Error) {
    console.log(err.message)
  }
}

modules

allowArbitraryExtensions

allowImportingTsExtensions

allowUmdGlobalAccess

当 allowUmdGlobalAccess 设置为 true 时，将允许你在模块文件中以全局变量的形式访问 UMD 的导出。 模块文件是具有或同时导入、导出的文件。当未设置这个选项时，使用 UMD 模块的导出需要首先导入声明。

一个典型场景是：在一个 Web 项目中， 您知道特定的库（如 jQuery 或 Lodash ）在运行时总是可用的，但您无法通过导入来使用他们。

baseUrl

可以让您设置解析非绝对路径模块名时的基准目录。

example: "baseUrl": "./"

• ex.ts
• helloword
  • world.ts
• tsconfig.json

TypeScript 将会从首先寻找与 tsconfig.json 处于相同目录的文件。

ex.ts

import { helloWorld } from 'hello/world'
console.log(helloWorld)

customConditions

module

设置程序的模块系统。可选值包括： none,commonjs(default),amd,umd,system,es6/es2015,es2020,es2022,esnext,node16,nodenext,preserve.用于指定生成的 JavaScript 文件中使用的 模块系统 的选项。module 决定 模块导入/导出 的形式（如 Node.js 的 require，或浏览器支持的 import/export）。

moduleResolution

moduleSuffixes

noResolve

noUncheckedSideEffectImports

paths

一些将模块导入重新映射到相对于 baseUrl 路径的配置。

paths 可以允许你声明 TypeScript 应该如何解析你的 require/import。

{
  "compilerOptions": {
    "baseUrl": ".", // this must be specified if "paths" is specified.
    "paths": {
      "jquery": ["node_modules/jquery/dist/jquery"] // this mapping is relative to "baseUrl"
    }
  }
}

resolveJsonModule

允许导入扩展名为.json 的模块，

resolvePackageJsonExports

resolvePackageJsonImports

rootDir

rootDirs

typeRoots

types

默认情况下，所有 可见 的 ”@types” 包都将包含在你的编译过程中。 在 node_modules/@types 中的任何包都被认为是 可见 的。 例如，这意味着包含 ./node_modules/@types/，../node_modules/@types/，../../node_modules/@types/ 中所有的包。。

当 types 被指定，则只有列出的包才会被包含在全局范围内。

{
  "compilerOptions": {
    "types": ["node", "jest", "express"]
  }
}

这个 tsconfig.json 文件将 只会 包含 ./node_modules/@types/node，./node_modules/@types/jest 和 ./node_modules/@types/express。 其他在 node_modules/@types/* 下的包将不会被包含。

emit

declaration

declarationDir

declarationMap

downlevelIteration

emitBOM

emitDeclarationOnly

importHelpers

inlineSourceMap

inlineSources

mapRoot

newLine

noEmit

noEmitHelpers

noEmitOnError

outDir

如果被指定，.js （以及 .d.ts, .js.map 等）将会被生成到这个目录下。 原始源文件的目录将会被保留.

outFile

preserveConstEnums

removeComments

当转换为 JavaScript 时，忽略所有 TypeScript 文件中的注释。默认为 false。

sourceMap

sourceRoot

stripInternal

javascript support

allowJs

允许 JavaScript 文件在你的工程中被引入，而不是仅仅允许 .ts 和 .tsx 文件。

checkJs

与 allowJs 配合使用，当 checkJs 被启用时，JavaScript 文件中会报告错误。也就是相当于在项目中所有 JavaScript 文件顶部包含 // @ts-check。

maxNodeModuleJsDepth

editor support

disableSizeLimit

plugins

interop constraints

allowSyntheticDefaultImports

esModuleInterop

forceConsistentCasingInFileNames

isolatedDeclarations

isolatedModules

preserveSymlinks

verbatimModuleSyntax

Backwards Compatibility

charset

importsNotUsedAsValues

keyofStringsOnly

noImplicitUseStrict

noStrictGenericChecks

out

preserveValueImports

suppressExcessPropertyErrors

suppressImplicitAnyIndexErrors

Language and Environment

emitDecoratorMetadata

experimentalDecorators

开启装饰器.

jsx

jsxFactory

jsxFragmentFactory

jsxImportSource

lib

TypeScript 包括一组默认的内建 JS 接口（例如 Math）的类型定义，以及在浏览器环境中存在的对象的类型定义（例如 document）。 TypeScript 还包括与你指定的 target 选项相匹配的较新的 JS 特性的 API。例如如果target 为 ES6 或更新的环境，那么 Map 的类型定义是可用的。

你可能出于某些原因改变这些：

1. 不运行在浏览器中，因此你不想要 "dom" 类型定义。

2. 你的运行时平台提供了某些 JavaScript API 对象，但还不支持某个 ECMAScript 版本的完整语法。

3.一些 （但不是全部）对于更高级别的 ECMAScript 版本的 polyfill 或本地实现。

名称	内容
ES5	ES3 和 ES5 的核心功能定义
ES2015	ES2015 中额外提供的 API (又被称为 ES6) —— array.find， Promise，Proxy，Symbol，Map，Set，Reflect 等。
ES6	ES2015 的别名。
ES2016	ES2016 中额外提供的 API —— array.include 等。
ES7	ES2016 的别名。
ES2017	ES2017 中额外提供的 API —— Object.entries，Object.values，Atomics，SharedArrayBuffer，date.formatToParts，typed arrays 等。
ES2018	ES2018 中额外提供的 API —— async iterables，promise.finally，Intl.PluralRules，rexexp.groups 等。
ES2019	ES2019 中额外提供的 API —— array.flat，array.flatMap，Object.fromEntries，string.trimStart，string.trimEnd 等。
ES2020	ES2020 中额外提供的 API —— string.matchAll 等。
ESNext	ESNext 中额外提供的 API —— 随着 JavaScript 的发展，这些会发生变化。
DOM	DOM 定义 —— window，document 等。
WebWorker	WebWorker 上下文中存在的 API。
ScriptHost	Windows Script Hosting System 的 API。

moduleDetection

noLib

reactNamespace

target

所有取值： es3、 es5(defalut)、 es6/es2015、 es2016、 es2017、 es2018、 es2019、 es2020、 es2021、 es2022、 es2023、 esnext、 现代浏览器支持全部 ES6 的功能，所以 ES6 是一个不错的选择。 如果代码部署在旧的环境中，可以选择设置一个更低的目标；如果代码保证会运行在新的环境中，可以选择一个更高的目标。

target 的配置将会改变哪些 JS 特性会被降级，而哪些会被完整保留 例如，如果 target 是 ES5 或更低版本，箭头函数 () => this 会被转换为等价的 函数 表达式。

改变 target 也会改变 lib 选项的默认值。 根据需要混搭 target 和 lib 的配置，为了方便只设置 target。

只使用 Node.js，这里推荐基于 Node 版本的 target：

名称	支持的变异目标
Node 8	ES2017
NODE 10	ES2018
NODE 12	ES2019
特殊的 ESNext 值代表你的 TypeScript 所支持的最高版本。这个配置应当被谨慎使用，因为它在不同的 TypeScript 版本之间的含义不同，并且会导致升级更难预测。

useDefineForClassFields

Compiler Diagnostics

diagnostics

explainFiles

extendedDiagnostics

generateCpuProfile

generateTrace

listEmittedFiles

listFiles

noCheck

traceResolution

Projects

composite

disableReferencedProjectLoad

disableSolutionSearching

disableSourceOfProjectReferenceRedirect

incremental

tsBuildInfoFile

Output Formatting

noErrorTruncation

preserveWatchOutput

pretty

Completeness

skipDefaultLibCheck

skipLibCheck

监听选项

assumeChangesOnlyAffectDirectDependencies

include

指定要编译的 ts 文件.

paterns

• '*' 匹配 0 个或多个字符
• ? 匹配任意一个字符
• **/ 匹配嵌套到任何级别的任何目录 如果模式中的最后一个路径段不包含文件扩展名或通配符，则将其视为目录，并且包含该目录中支持扩展名的文件（例如:ts, .tsx 和.d.ts）。如果 allowJs 设置为 true，还可以使用.js 和.jsx。

exclude

指定解析 include 时应跳过的文件名或模式数组。

重要: exclude 仅排除已包含在 include 设置中的文件。但有时候即使排除了某个文件,在代码中使用了 import,types 或者通过///<reference 引入,ts 仍然会进行编译.它不是一种阻止文件被包含在代码库中的机制——它只是改变包含设置找到的内容。

files

references

项目引用是一种将TypeScript程序组织成小块的方法。使用Project References可以极大地改善构建和编辑器交互时间，强制组件之间的逻辑分离，并以新的和改进的方式组织代码。 每个引用的path属性可以指向一个包含tsconfig.Json文件。

{
    "compilerOptions": {
        // The usual
    },
    "references": [
        { "app": "app.tsconfig.json" }
    ]
}

watchOptions

配置 ts 编译器监听文件和目录的行为,主要用于性能调优,不多讨论.

typeAcquisition

类型获取只对 JavaScript 项目很重要。它主要在 非直接使用 TypeScript 的场景中发挥作用，比如用纯 JavaScript 开发时，TypeScript 编译器可以通过它为项目自动获取类型定义文件，从而提供更好的类型推导和补全体验。不多讨论.

提示

TypeScript Configuration 官网