ts-learnings/00_tsconfig-json.md

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