tsconfig.json

Mr shen2025/8/19大约 12 分钟

tsconfig.json

简介

tsconfig.json是 TypeScript 项目的配置文件，放在项目的根目录。反过来说，如果一个目录里面有tsconfig.json，TypeScript 就认为这是项目的根目录。
tsconfig.json文件主要供tsc编译器使用，它的命令行参数--project或-p可以指定tsconfig.json的位置

tsc -p ./dir

基本结构

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

提示

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

npm

npm install --save-dev @tsconfig/deno

yarn

yarn add --dev @tsconfig/deno

compilerOptions

allowJs

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

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

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设置是否允许存在未使用的标签。它的值有三种可能

undefined：默认值，编辑器显示警告。
true：忽略未使用的标签。
false：编译器报错。

baseUrl

baseUrl的值为字符串，指定 TypeScript 项目的基准目录。
由于默认是以 tsconfig.json 的位置作为基准目录，所以一般情况不需要使用该属性。

{
  "compilerOptions": {
    "baseUrl": "./"
  }
}

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

checkJs

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

composite

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

declaration

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

declarationDir

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

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

declarationMap

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

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

diagnostics

显示诊断信息

disableSizeLimit

禁用JavaScript工程体积大小的限制

emitBOM

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

emitDecoratorMetadata[实验性]

给源码里的装饰器声明加上设计类型元数据。

experimentalDecorators[实验性]

启用实验性的ES装饰器。

emitDeclarationOnly

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

extendedDiagnostics

显示详细的诊断信息

esModuleInterop

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

如果module属性为node16或nodenext，则esModuleInterop默认为true，其他情况默认为false。

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

import * as moment from "moment";

moment(); // 报错

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

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

import moment from "moment";

moment(); // 不报错

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

提示

注意，打开esModuleInterop，将自动打开allowSyntheticDefaultImports。

exactOptionalPropertyTypes

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

// 打开 exactOptionalPropertyTypes
interface MyObj {
    foo?: "A" | "B";
}

let obj: MyObj = {foo: "A"};

obj.foo = undefined; // 报错

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

forceConsistentCasingInFileNames

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

incremental

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

inlineSourceMap

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

inlineSources

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

它要求sourceMap或inlineSourceMap至少打开一个。

isolatedModules

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

jsx

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

preserve：保留JSX语法，输出的文件名为 jsx。
react：将
编译成React.createElement("div")，输出的文件名为.js
react-native：将
编译成React.createElement("div")，输出的文件名为.js，支持JSX转换。

{
  "compilerOptions": {
    "jsx": "preserve"
  }
}

lib

lib值是一个数组，描述项目需要加载的 TypeScript 内置类型描述文件，跟三斜线指令/// <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。

moduleResolution

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

node：采用 Node.js 的 CommonJS 模块算法。
node16或nodenext：采用 Node.js 的 ECMAScript 模块算法，从 TypeScript 4.7 开始支持。
classic：TypeScript 1.6 之前的算法，新项目不建议使用。

它的默认值与module属性有关，如果module为AMD、UMD、System或ES6/ES2015，默认值为classic；如果module为node16或nodenext，默认值为这两个值；其他情况下,默认值为Node。

moduleSuffixes

moduleSuffixes指定模块的后缀名。

{
  "compilerOptions": {
    "moduleSuffixes": [
      ".ios",
      ".native",
      ""
    ]
  }
}

上面的设置使得 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。

onEmitOnError

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语句加载的模块。

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


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

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

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

preserveConstEnums

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

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

pretty

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

removeComments

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

resolveJsonModule

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

rootDir

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

rootDirs

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

{
  "compilerOptions": {
    "rootDirs": [
      "bar",
      "foo"
    ]
  }
}

上面示例中，rootDirs将bar和foo组成一个虚拟目录。

sourceMap

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

sourceRoot

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

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

strict

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

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

alwaysStrict
strictNullChecks
strictBindCallApply
strictFunctionTypes
strictPropertyInitialization
noImplicitAny
noImplicitThis
useUnknownInCatchVaria

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

{
  "compilerOptions": {
    "strict": true,
    "alwaysStrict": false
  }
}

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;

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;

提示

它可以理解成只要打开，就需要显式检查null或undefined。

function doSomething(x: string | null) {
    if (x === null) {
        // do nothing
    } else {
        console.log("Hello, " + x.toUpperCase());
    }
}

strictPropertyInitialization

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

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

注意

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

// strictPropertyInitialization：true
class User {
    // 报错，属性 username 没有初始化
    username: string;
}

// 解决方法一
class User {
    username = "张三";
}

// 解决方法二
class User {
    username: string | undefined;
}

// 解决方法三
class User {
    username: string;

    constructor(username: string) {
        this.username = username;
    }
}

// 或者
class User {
    constructor(public username: string) {
    }
}

// 解决方法四：赋值断言
class User {
    username!: string;

    constructor(username: string) {
        this.initialize(username);
    }

    private initialize(username: string) {
        this.username = username;
    }
}

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设置编译时，在终端输出模块解析的具体步骤。

{
  "compilerOptions": {
    "traceResolution": true
  }
}

typeRoots

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

{
  "compilerOptions": {
    "typeRoots": [
      "./typings",
      "./vendor/types"
    ]
  }
}

types

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

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

useUnknownInCatchVariables

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

try {
    someExternalFunction();
} catch (err) {
    err; // 类型 any
}

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

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

try {
    someExternalFunction();
} catch (err) {
    if (err instanceof Error) {
        console.log(err.message);
    }
}

exclude

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

include: 指定要包含在编译中的文件或目录，支持通配符
exclude: 指定要排除在编译之外的文件或目录，默认排除node_modules、dist等

{
  "include": [
    "src/**/*"
  ],
  "exclude": [
    "node_modules",
    "dist"
  ]
}

include

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

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

include属性支持三种通配符

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

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

extends

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

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

本地文件

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

npm模块

{
  "extends": "@tsconfig/node12/tsconfig.json"
}

references

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

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

files

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

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

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

注意

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