理解 Typescript 配置文件

熟悉 Typescript 配置选项是 TS 项目开发的最基本要求。
TS 使用 tsconfig.json 作为其配置文件，它主要包含两块内容：

1. 指定待编译的文件
2. 定义编译选项

另外，一般来说，tsconfig.json 文件所处的路径就是当前 TS 项目的根路径。

基本用法

TS 的编译命令为 tsc ，当我们在命令行中直接输入 tsc 时，会打印出如下的使用说明：

$ tsc
Version 2.7.2
Syntax:   tsc [options] [file ...]
Examples: tsc hello.ts
          tsc --outFile file.js file.ts
          tsc @args.txt

Options:
-h, --help                                         Print this message.
--all                                              Show all compiler options.
-v, --version                                      Print the compiler's version.
...

如果仅仅是编译少量的文件，我们可以直接使用 tsc ，通过其选项来设置编译配置，如：

tsc --outFile file.js --target es3 --module commonjs file.ts

但如果是编译整个项目的话，最推荐的做法是使用 tsconfig.json 文件，这样就不用每次编译时都还得手动敲配置，而且也便于团队协作。

以下是让 tsc 使用 tsconfig.json 的两种方式：

• 不显式指定 tsconfig.json ，此时，编译器会从当前路径开始寻找 tsconfig.json 文件，如果没有找到，则继续往上级路径逐步寻找，直到找到为止
• 通过 --project （或缩写 -p ）指定一个包含 tsconfig.json 的路径，或者包含配置信息的 .json 文件路径

注意，tsc 的命令行选项具有优先级，会覆盖 tsconfig.json 中的同名选项。

使用示例

下面是一个简单的配置示例：

{
  "compilerOptions": {
    "module": "commonjs",
    "noImplicitAny": true,
    "removeComments": true,
    "preserveConstEnums": true,
    "sourceMap": true
  },
  "files": [
    "app.ts",
    "foo.ts",
  ]
}

其中，compilerOptions 用来配置编译选项，files 用来指定待编译文件。
这里的待编译文件是指入口文件，任何被入口文件依赖的文件，比如 foo.ts 依赖 bar.ts ，那这里并不需要写上 bar.ts ，编译器会自动把所有的依赖文件纳为编译对象。

也可以使用 include 和 exclude 来指定和排除待编译文件：

{
  "compilerOptions": {
    "module": "commonjs",
    "noImplicitAny": true,
    "removeComments": true,
    "preserveConstEnums": true,
    "sourceMap": true
  },
  "include": [
    "src/**/*"
  ],
  "exclude": [
    "node_modules",
    "**/*.spec.ts"
  ]
}

所以，总结一下，指定待编译文件有两种方式：

• 使用 files 属性
• 使用 include 和 exclude 属性

开发者可以按照自己的喜好使用其中任意一种。但它们不是互斥的，在某些情况下两者搭配起来使用效果更佳。

配置说明

文件指定

files 属性是一个数组，数组元素可以是相对文件路径和绝对文件路径。

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

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

在继续说明之前，有必要先了解下在编译器眼里什么样的文件才算是 TS 文件。
TS 文件指拓展名为 .ts、.tsx 或 .d.ts 的文件。如果开启了 allowJs 选项，那 .js 和 .jsx 文件也属于 TS 文件。

如果仅仅包含一个 * 或者 .* ，那么只有TS 文件才会被包含。

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

如果同时设置 files 和 include ，那么编译器会把两者指定的文件都引入。

如果未设置 exclude ，那其默认值为 node_modules 、bower_components、jspm_packages 和编译选项 outDir 指定的路径。

exclude 只对 include 有效，对 files 无效。即 files 指定的文件如果同时被 exclude 排除，那么该文件仍然会被编译器引入。

前面提到，任何被 files 或 include 引入的文件的依赖会被自动引入。
反过来，如果 B.ts 被 A.ts 依赖，那么 B.ts 不能被 exclude 排除，除非 A.ts 也被排除了。

有一点要注意的是，编译器不会引入疑似为输出的文件。比如，如果引入的文件中包含 index.ts ，那么 index.d.ts 和 index.js 就会被排除。通常来说，只有拓展名不一样的文件命名法是不推荐的。

tsconfig.json 也可以为空文件，这种情况下会使用默认的编译选项来编译所有默认引入的文件。

编译选项

常用选项

选项字段	类型	默认值	说明
allowJs	boolean	false	允许编译 JS 文件
checkJs	boolean	false	报告 JS 文件中存在的类型错误需要配合 allowJs 使用
declaration	boolean	false	生成对应的 .d.ts 文件
declarationDir	string	-	生成的 .d.ts 文件存放路径默认与 .ts 文件相同
experimentalDecorators	boolean	false	启用实验功能-ES 装饰器
jsx	string	Preserve	在 .tsx 中支持 JSX ：React 或 Preserve ，详细说明
jsxFactory	string	React.createElement	jsx 设置为 React 时使用的创建函数
lib	string[]	-	编译时引入的 ES 功能库，包括：es5 、es6、es7、dom 等。如果未设置，则默认为： target 为 es5 时: ["dom", "es5", "scripthost"] target 为 es6 时: ["dom", "es6", "dom.iterable", "scripthost"]
module	string	target === "es3" or "es5" ?"commonjs" : "es6"	生成的模块形式：none、commonjs、amd、system、umd、es6、es2015 或 esnext 只有 amd 和 system 能和 outFile 一起使用 target 为 es5 或更低时可用 es6 和 es2015
moduleResolution	string	module === "amd" or "system" or "es6" ? "classic" : "node"	模块解析方式，详细说明
noImplicitAny	boolean	false	存在隐式 any 时抛错
noImplicitReturns	boolean	false	不存在 return 时抛错
noImplicitThis	boolean	false	this 可能为 any 时抛错
outDir	string	-	编译生成的文件存放路径默认与 .ts 文件相同
sourceMap	boolean	false	生成 .map 文件
target	string	es3	生成 .js 文件版本

附：官方完整的编译选项列表

类型相关

类型相关的选项包括 typeRoots 和 types 。

有一个普遍的误解，以为这两个选项适用于所有的类型声明文件，包括用户自定义的声明文件。其实不然。
这两个选项只对通过 npm 安装的声明模块有效，用户自定义的类型声明文件与它们没有任何关系。

声明模块通常会包含一个 index.d.ts 文件，或者其 package.json 设置了 types 字段。

默认的，所有位于 node_modules/@types 路径下的模块都会引入到编译器。
具体来说是，./node_modules/@types 、../node_modules/@types、../../node_modules/@types 等等。

typeRoots 用来指定默认的类型声明文件查找路径，默认为 node_modules/@types 。比如:

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

上面的配置会自动引入 ./typings 下的所有 TS 类型声明模块，而不是 ./node_modules/@types 下的模块。

如果不希望自动引入 typeRoots 指定路径下的所有声明模块，那可以使用 types 指定自动引入哪些模块。比如：

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

只会引入 node 、 lodash 和 express 三个声明模块，其它的声明模块则不会被自动引入。
如果 types 被设置为 [] ，那么将不会自动引入任何声明模块。此时，如果想使用声明模块，只能在代码中手动引入了。

请记住，自动引入只对包含全局声明的模块有效。比如 jQuery ，我们不用手动 import 或者 ///<reference/> 即可在任何文件中使用 $ 的类型。再比如，对于 import 'foo' ，编译器会分别在 node_modules 和 node_modules/@types 文件下查找 foo 模块和声明模块。

基于此，如果想让自定义声明的类型不需要手动引入就可以在任何地方使用，可以将其声明为全局声明 global ，然后让 files 或者 include 包含即可。
比如：

declare global {
  const graphql: (query: TemplateStringsArray) => void;
  namespace Gatsby {
    interface ComponentProps {
      children: () => React.ReactNode,
      data: RootQueryType
    }
  }
}

这样的话，就可以在任何地方直接使用 graphql 和 Gatsby 对应的类型了。

配置复用

可以使用 extends 来实现配置复用，即一个配置文件可以继承另一个文件的配置属性。

比如，建立一个基础的配置文件 configs/base.json ：

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

然后，tsconfig.json 就可以引用这个文件的配置了：

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

这种继承有两种特点：

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

参考资料

• tsconfig.json 官方文档