tsconfig.json

原文: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html

概述

某个目录下存在文件tsconfig.json，那么就表明该目录是某个TypeScript项目的根目录。tsconfig.json文件指定了有哪些根文件，以及需要哪些编译器选项来对该项目进行编译。项目是以以下方式之一进行编译的：

`tsconfig.json`的运用

通过不带有文件的方式调用 tsc命令，此时编译器从当前目录开始，进而沿父目录链往上搜索tsconfig.json文件（by invoking tsc with no input files, in which case the compiler searches for the tsconfig.json file starting in the current directory and continuing up the parent directory chain）。
通过不带有文件，但提供用于指定包含了tsconfig.json文件的目录路径，或指向某个包含了配置的有效的.json文件的--project（或仅-p）的命令行选项方式，来调用tsc命令。

当有在命令行上指定了文件时，tsconfig.json文件就会被忽略。

示例

tsconfig.json的一些示例文件：

使用files属性

{
    "compilerOptions": {
        "module": "commonjs",
        "noImplicitAny": true,
        "removeComments": true,
        "preserveConstEnums": true,
        "sourceMap": true
    },
    "files": [
        "core.ts",
        "sys.ts",
        "types.ts",
        "scanner.ts",
        "parser.ts",
        "utilities.ts",
        "binder.ts",
        "checker.ts",
        "emitter.ts",
        "program.ts",
        "commandLineParser.ts",
        "tsc.ts",
        "diagnosticInformationMap.generated.ts"
    ]
}

使用include与exclude属性

{
    "compilerOptions": {
        "module": "system",
        "noImplicitAny": true,
        "removeComments": true,
        "preserveConstEnums": true,
        "outFile": "../../built/local/tsc.js",
        "sourceMap": true
    },
    "include": [
        "src/**/*"
    ],
    "exclude": [
        "node_modules",
        "**/*.spec.ts"
    ]
}

详解（Details）

属性compilerOptions是可以省略的，在省略了该属性时，编辑器将使用默认选项。请参考完整的编译器选项清单。

files属性取的是一个相对或绝对文件路径的清单。而include与exclude属性，则取的是类似于glob的文件模式清单（请参考 Glob_(programming), Wikipedia，glob介绍）。支持以下glob通配符：

* 匹配零个或更多字符（不包含目录分隔符，* matches zero or more characters(excluding directory separators)）
? 匹配任意的一个字符（不包含目录分隔符，? matches any one character(excluding directory separators)）
**/ 递归地匹配所有子目录（**/ recursively matches any subdirectory）

在某个glob模式片段中仅包含了 * 或 .* 时，那么只有那些扩展被支持的文件才被包含进来（也就是.ts、.tsx与.d.ts，而在allowJs被设置为true的情况下，也包含.js与.jsx）。

而在files与include都没有指定时，编译器将默认包含其所在目录及子目录下的所有TypeScript文件（.ts、.d.ts与tsx），除了那些使用exclude属性所排除的文件。同时若allowJS被设置为true，那么JavaScript文集（.js与.jsx）也将包含进来。若有指定files与include属性，则编译器将包含由这两个属性所包含的文件联合（the union of the files included by those two properties）。在未指定exclude属性时，使用编译器选项outDir所指定的目录中的文件是排除在外的（Files in the directory specified using the outDir compiler option are excluded as long as exclude property is not specified）。

使用include所包含的文件，可使用exclude属性对其进行过滤。但使用files属性显式包含的文件，则不会受到exclude的影响而总是会包含进来。在莫有指定exclude属性时，就默认排除了node_modules、bower_components、jspm_packages以及<outDir>这些目录。

那些被files或include属性包含进来的文件引用到的文件，也将被包含进来。同样，如某个文件B.ts被另一个文件A.ts引用了，那么除非文件A.ts在exclude清单中有指明，否则文件B.ts也不能被排除在外。

请注意编译器不会将那些可能是输出的文件包含进去；比如在输入中包含了index.ts时，那么index.d.ts与index.js就会被排除在外。总体来说，让多个文件只是在扩展名上有所不同，是不好的做法。

tsconfig.json文件可以是空的，那将对默认包含的所有文件，以默认的编译器选项进行编译（跟前面讲到的一样）。

在命令行指定的编译器选项，将覆盖在tsconfig.json文件中所指定的那些选项。

`@types`、`typeRoots`与`types`

默认所有可见的 @types 包在编译中都被包含进去了。任何闭合文件夹的 node_modules/@types 里的包，都被视为可见的（Packages in node_modules/@types of any enclosing folder are considered visible）；具体来说，那意味着在 ./node_modules/@types/、../node/modules/@types/及../../node_modules/@types/等处的包。

若指定了 typeRoots，那么就只有 typeRoots下的包将被包含进来了。比如：

{
   "compilerOptions": {
        "typeRoots": ["./typings"]
   } 
}

此配置文件将包含在 ./typings 下的所有包，而不会包含那些 ./node_modules/@types 下的包了。

在指定了 types 属性时，那么就只有所列出的那些包被包含进来。比如：

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

此tsconfig.json文件将只包含 ./node_modules/@types/node、./node_modules/@types/lodash与./node_modules/@types/express。其他位处 ./node_modules/@types/* 的包不会被包含进来。

类型包（a types package）指的是某个带有名为index.d.ts文件的文件夹，或某个有着包含了types字段的package.json文件的文件夹。

在tsconfig.json中指定types: []字段，就关闭了@types包的自动包含。

请记住只有在使用那些带有全局声明的文件（与将文件声明为模块相反）时，自动包含才是重要的（keep in mind that automatic inclusion is only important if you're using files with global declarations(as opposed to files declared as modules)）。比如在使用一条import "foo"语句时，TypeScript将在node_modules与node_modules/@types文件夹中进行查找，以找到foo包。

使用`extends`配置继承

Configuration inheritence with extends

通过使用extends属性，tsconfig.json文件可从其他文件继承到配置。

在tsconfig.json中，extends属性是一项顶层属性（与compilerOptions、files、include与exclude一起）。extends的值是一个包含了到要继承的其他文件的路径的字符串。

来自基础文件的配置，将首先载入，随后被继承的配置文件覆盖。如发生了循环继承，编译器将报告错误。

继承配置文件中的files、include与exclude将覆盖基础配置文件中的对应属性（files, include and exclude from the inheriting config file overwrite those from the base config file）。

在配置文件中找到的所有相对路径，将解析为相对于配置文件原本的位置。

比如：

configs/base.json:

{
    "compilerOptions": {
        "noImplicitAny": true,
        "strictNullChecks": true
    }
}

tsconfig.json:

{
    "extends": "./config/base",
    "files": [
        "main.ts",
        "supplemental.ts"
    ]
}

tsconfig.nostrictnull.json:

{
    "extends": "./tsconfig",
    "compilerOptions": {
        "strictNullChecks": false
    }
}

关于 `compileOnSave` 属性

加入一个顶层的compileOnSave，告诉IDE在保存时生成给定tsconfig.json的所有文件。

{
    "compileOnSave": true,
    "compilerOptions": {
        "noImplicitAny": true
    }
}

此特性当前已在 Visual Studio 2015 与 TypeScript 1.8.4 以上版本，以及atom-typescript插件中得到支持。

关于`tsconfig.json`文件的完整结构

Schema

可以从 http://json.schemastore.org/tsconfig 查看到。

编译器选项

选项	值类型	默认值	简介
`--allowJs`	`boolean`	`false`	允许编译JavaScript文件。
`--allowSyntheticDefaultImports`	`boolean`	`module === "system"` 或 `--esModuleInterop`	允许从那些没有默认导出的模块默认导入。此选项不会影响生成的代码，只做类型检查。

更多编译器选项请参考 https://www.typescriptlang.org/docs/handbook/compiler-options.html

Yet another Chinese TypeScript tutorial.