TypeScript入门之配置文件-阿里云开发者社区

简介

tsconfig.json是TypeScript的配置文件，在平时使用TypeScript开发的时候我们一般都会创建tsconfig.json。

下面我们来说说怎么生成 tsconfig.json、tsconfig.json的作用，以及tsconfig.json中各个选项都代表什么意思。

生成 tsconfig.json

在讲TypeScript环境搭建的时候我们就已经说过了，我们需要通过tsc --init来生成配置文件。

详细可以参看TypeScript学习之环境搭建

tsconfig.json 的作用

用于标识 TypeScript 项目的根路径。
用于配置 TypeScript 编译器。
用于指定编译的文件。

tsconfig.json 的读取方式

tsconfig.json 的读取方式主要有两种

不带任何输入文件的情况下调用 tsc，编译器会从当前目录开始去查找 tsconfig.json 文件，逐级向上搜索父目录，直到根路径。
不带任何输入文件的情况下调用 tsc，且使用命令行参数 --project（或-p）指定一个包含 tsconfig.json 文件的目录。

注意当命令行上指定了输入文件时，tsconfig.json文件会被忽略(报错)。

error TS5042: Option 'project' cannot be mixed with source files on a command line.

tsconfig.json 详解

我们先看一下 tsconfig.json 主要配置项：

{
  "files": [],
  "include": [],
  "exclude": [],
  "compileOnSave": false,
  "extends": "",
  "compilerOptions": {}
}

files

files 是一个数组列表，里面包含指定文件的相对或绝对路径，用来指定待编译文件，编译器在编译的时候只会编译包含在files中列出的文件。

如果我们不指定待编译文件的话，则取决于有没有设置 include 选项，如果没有 include 选项，则默认会编译根目录以及所有子目录中的文件。

include/exclude

include/exclude 也是一个数组，但数组元素是类似 glob 的文件模式。它支持的 glob 通配符包括：

*：匹配 0 或多个字符（注意：不含路径分隔符）
?：匹配任意单个字符（注意：不含路径分隔符）
**/ ：递归匹配任何子路径

在这里我们既可以指定目录也可以指定文件，而上面的 files 选项则只能指定文件。

我们再说明一个问题，什么才是 TypeScript 编译器眼中的文件？

TS 文件指拓展名为 .ts、.tsx 或 .d.ts 的文件。如果开启了 allowJs 选项，那 .js 和 .jsx 文件也属于 TS 文件，因此一个目录下只有上述文件才会被编译。

include/exclude 的作用也很好理解，我们可以指定编译某些文件，或者指定排除某些文件，但是别忘了，还有上面我们提到的 files，这三者的关系是什么样的？有没有优先级？或者默认值?

include/exclude/files 三者的关系

首先我们明确一点，exclude 是有默认值的，如果我们没有设置 exclude ，那其默认值为 node_modules 、bower_components、jspm_packages 和编译选项 outDir 指定的路径。

还有一点，files 的优先级是最高的，比如我们在 files 中指定了一些文件，但是又在 exclude 中把它们排除了，这是无效的，因为 files 的优先级更高，这些文件依然会被编译，但是如果 include 中包含，那么依然会被排除，由此可见这三者的优先级如下：

files > exclude > include

如果 files 和 include 都未设置，那么除了 exclude 排除的文件，编译器会默认包含路径下的所有 TS 文件。

compileOnSave

在最顶层设置compileOnSave标记，可以让IDE在保存文件的时候根据tsconfig.json重新编译文件。

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

要想支持这个特性需要Visual Studio 2015， TypeScript1.8.4以上并且安装atom-typescript插件。

extends

它的作用是实现配置复用，即一个配置文件可以继承另一个文件的配置属性。

比如我们创建一个文件 configs/base.json:

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

如果我们想引用上属配置，那么就需要 extends 这个配置项了：

{
  "extends": "./configs/base"
}

值得注意的有两点：

继承者中的同名配置会覆盖被继承者
所有相对路径都被解析为其所在文件的路径

compilerOptions

下面我们来说说最最重要的compilerOptions选项。

{
  "compilerOptions": {

    /* 基本选项 */
    "target": "es5",                       // 指定 ECMAScript 目标版本: 'ES3' (default), 'ES5', 'ES6'/'ES2015', 'ES2016', 'ES2017', or 'ESNEXT'
    "module": "commonjs",                  // 指定使用模块: 'commonjs', 'amd', 'system', 'umd' or 'es2015'
    "lib": [],                             // 指定要包含在编译中的库文件
    "allowJs": true,                       // 允许编译 javascript 文件
    "checkJs": true,                       // 报告 javascript 文件中的错误
    "jsx": "preserve",                     // 指定 jsx 代码的生成: 'preserve', 'react-native', or 'react'
    "declaration": true,                   // 生成相应的 '.d.ts' 文件
    "sourceMap": true,                     // 生成相应的 '.map' 文件
    "outFile": "./",                       // 将输出文件合并为一个文件
    "outDir": "./",                        // 指定输出目录
    "rootDir": "./",                       // 用来控制输出目录结构 --outDir.
    "removeComments": true,                // 删除编译后的所有的注释
    "noEmit": true,                        // 不生成输出文件
    "importHelpers": true,                 // 从 tslib 导入辅助工具函数
    "isolatedModules": true,               // 将每个文件做为单独的模块 （与 'ts.transpileModule' 类似）.

    /* 严格的类型检查选项 */
    "strict": true,                        // 启用所有严格类型检查选项
    "noImplicitAny": true,                 // 在表达式和声明上有隐含的 any类型时报错
    "strictNullChecks": true,              // 启用严格的 null 检查
    "noImplicitThis": true,                // 当 this 表达式值为 any 类型的时候，生成一个错误
    "alwaysStrict": true,                  // 以严格模式检查每个模块，并在每个文件里加入 'use strict'

    /* 额外的检查 */
    "noUnusedLocals": true,                // 有未使用的变量时，抛出错误
    "noUnusedParameters": true,            // 有未使用的参数时，抛出错误
    "noImplicitReturns": true,             // 并不是所有函数里的代码都有返回值时，抛出错误
    "noFallthroughCasesInSwitch": true,    // 报告 switch 语句的 fallthrough 错误。（即，不允许 switch 的 case 语句贯穿）

    /* 模块解析选项 */
    "moduleResolution": "node",            // 选择模块解析策略： 'node' (Node.js) or 'classic' (TypeScript pre-1.6)
    "baseUrl": "./",                       // 用于解析非相对模块名称的基目录
    "paths": {},                           // 模块名到基于 baseUrl 的路径映射的列表
    "rootDirs": [],                        // 根文件夹列表，其组合内容表示项目运行时的结构内容
    "typeRoots": [],                       // 包含类型声明的文件列表
    "types": [],                           // 需要包含的类型声明文件名列表
    "allowSyntheticDefaultImports": true,  // 允许从没有设置默认导出的模块中默认导入。

    /* Source Map Options */
    "sourceRoot": "./",                    // 指定调试器应该找到 TypeScript 文件而不是源文件的位置
    "mapRoot": "./",                       // 指定调试器应该找到映射文件而不是生成文件的位置
    "inlineSourceMap": true,               // 生成单个 soucemaps 文件，而不是将 sourcemaps 生成不同的文件
    "inlineSources": true,                 // 将代码与 sourcemaps 生成到一个文件中，要求同时设置了 --inlineSourceMap 或 --sourceMap 属性

    /* 其他选项 */
    "experimentalDecorators": true,        // 启用装饰器
    "emitDecoratorMetadata": true          // 为装饰器提供元数据的支持
  }
}