TypeScript 配置文件该怎么写？

时间  2020-08-26
标签 typescript 配置文件 怎么 繁體版
原文   原文链接

TypeScript 的学习资料很是多，其中也不乏不少优秀的文章和教程。可是目前为止没有一个我特别满意的。缘由有：前端

  • 它们大多数没有一个清晰的主线，而是按照 API 组织章节的，内容在逻辑上比较零散。
  • 大可能是“讲是什么，怎么用“，而不是”讲为何，讲原理“。
  • 大多数内容比较枯燥，趣味性比较低。都是干巴巴的文字，没有图片，缺少可以引发强烈共鸣的例子。

所以个人想法是作一套不一样市面上大多数的 TypeScript 学习教程。以人类认知的角度思考问题，学习 TypeScript，经过通俗易懂的例子和图片来帮助你们创建 TypeScript 世界观。node

系列安排：react

目录未来可能会有所调整。

注意，个人系列文章基本不会讲 API，所以须要你有必定的 TypeScript 使用基础，推荐两个学习资料。git

结合这两个资料和个人系列教程，掌握 TypeScript 指日可待。es6

接下来，咱们经过几个方面来从宏观的角度来看一下 TypeScript。github

<!-- more -->typescript

前言

这篇文章是个人 TypeScript 系列的第 5 篇。今天咱们就来看下， TypeScript 的配置文件 tsconfig.json 该如何写。json

和 package.json 同样， 它也是一个 JSON 文件。package.json 是包描述文件，对应的 Commonjs 规范，而 tsconfig.json 是最终被 TypeScript Compiler 解析和使用的一个 JSON 文件。 TypeScript Compiler 用这个配置文件来决定如何对项目进行编译。bash

说到编译，不得不提一个知名选手 - babel。 和 TypeScript 相似， 他们均可以将一种语法静态编译成另一种语法。若是说我想编译一个文件，我只须要告诉 babel 个人文件路径便可。babel

npx babel script.js

有时候我想编译整个文件夹：

npx babel src --out-dir lib

babel 也能够指定输出目录，指定须要忽略的文件或目录等等， TypeScript 也是同样！你固然能够像 babel 同样在命令行中所有指定好，也能够将这些配置放到 tsconfig.json 中，以配置文件的形式传递给 TypeScript Compiler 。 这就是 tsconfig.json 文件的初衷，即接受用户输入做为配置项。

初探 tsconfig

咱们先来看一个简单的 tsconfig 文件。

{
  "compilerOptions": {
    "outDir": "./built",
    "allowJs": true,
    "target": "es5"
  },
  "include": ["./src/**/*"]
}

如上配置作了：

  • 读取全部可识别的 src 目录下的文件（经过 include）。
  • 接受 JavaScript 作为输入（经过 allowJs）。
  • 生成的全部文件放在 built 目录下（经过 outDir）。
  • 将 JavaScript 代码降级到低版本好比 ECMAScript 5（经过 target）。

实际项目有比这个更复杂。 接下来， 咱们来进一步解读。 不过在讲配置项以前，咱们先来看下 tsconfig.json 是如何被解析的。

tsconfig 是如何被解析的？

若是一个目录下存在一个 tsconfig.json 文件，那么意味着这个目录是 TypeScript 项目的根目录。 若是你使用 tsc 编译你的项目，而且没有显式地指定配置文件的路径，那么 tsc 则会逐级向上搜索父目录寻找 tsconfig.json ，这个过程相似 node 的模块查找机制。

如图：

  • 在 _uglify-js@3.7.2@uglify-js 下执行 tsc 则会找到 配置文件 1，在 _uglify-js@3.7.2@uglify-js/bin 下执行 tsc 也会找到 配置文件 1
  • 同理在 lib，node_modules 也会找到 配置文件 1
  • 在 _uglify-js@3.7.2@uglify-js/bin/lucifer 下执行 tsc 则会找到 配置文件 2
  • 在 _uglify-js@3.7.2@uglify-js/lib/lucifer 下执行 tsc 则会找到 配置文件 3

我在 上帝视角看 TypeScript 一种讲述了 TypeScript 究竟作了什么，带你从宏观的角度看了一下 TypeScript。 其中提到了 TypeScript 编译器会接受文件或者文件集合做为输入，最终转换为 JavaScript（noEmit 为 false） 和 .d.ts(declarations 为 true)。

这里其实还少了一个点，那就是除了接受文件或者文件集合做为输入，还会接受 tsconfig.json。tsconfig.json 的内容决定了编译的范围和行为，不一样的 配置可能会获得不一样的输出，或者获得不一样的检查结果。

当 tsc 找到了一个 tsconfig.json 文件，那么其规定的编译目录则所有会被 typescript 处理，固然也包括其依赖的文件。 若是 tsc 没有找到一个 tsconfig.json 或 tsconfig 没有有效信息，那么 tsc 会使用默认配置。 好比 tsconfig 是一个空的就没有有效信息：

{}
tsconfig 的所有属性，以及属性的默认值能够在这里找到： http://json.schemastore.org/t...

总结一下 tsc 解析 tsconfig.json 的逻辑。

  • 若是命令行指定了配置选项或者指定了配置文件的路径，那么直接会读取。

    • 根据 tsconfig json schema 校验是否格式正确。

      • 若是正确，则将其和默认配置合并（若是有 extends 字段，也会一块儿合并），将合并后的配置传递给 TypeScript 编译器并开始编译。
      • 不然抛出错误

  • 不然，会从当前目录查找 tsconfig.json 文件， 若是找不到则逐层向上搜索父目录。

    • 若是找到了则会去根据 tsconfig json schema 校验是否格式正确。

      • 若是正确，则将其和默认配置合并（若是有 extends 字段，也会一块儿合并），将合并后的配置传递给 TypeScript 编译器并开始编译。
      • 不然抛出错误
    • 不然，始终找不到则直接使用默认配置

tsconfig 的顶层属性

tsconfig 的顶层属性（Top Level）很少，主要有：compilerOptions, files, include, exclude,extends,compileOnSave等。

  • compilerOptions 是重头戏，其属性也是最多的，咱们的项目也是对这个定制比较多，这个我后面会重点讲。
  • files 则是你须要编译的文件
  • exclude 则是你不须要编译的文件目录（支持 glob）
  • include 是你须要编译的文件目录（支持 glob）
  • extends 就是继承另一个配置文件，TypeScript 会对其进行合并，多项目公共配置有用。你也能够直接继承社区的“最佳实践”，好比:
{
  "extends": "@tsconfig/node12/tsconfig.json",

  "compilerOptions": {},

  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}
  • compileOnSave 则是和编辑器（确切地说是文件系统）联动的配置，便是否在文件保存后进行编译，实际项目不建议使用。

除了 compilerOptions，其余也相对比较好理解。 所以接下来我只针对 compilerOptions 详细讲解一番。

tsconfig 的编译项

详细全面的内容，你们只须要参考官网的就行了。官网写的不只全面，并且作了分类，很是清晰。

接下来，我会根据功能分开讲几个经常使用 的配置。

文件相关

经常使用的是如下四个，因为前面已经作了介绍，所以就不赘述了。

  • exclude
  • extends
  • files
  • include

严格检查

  • alwaysStrict

默认：false

首次发布版本：2.1

这个是和 ECMAScript 规范相关的，工做机制和 ES 5 的严格模式同样， 而且输出的 JS 顶部也会也会带上 'use strict'。

  • noImplicitAny（推荐打开）

默认：true

首次发布版本：-

我在 - TypeScript 类型系统 中提到了若是不对变量显式声明类型，那么 TypeScript 会对变量进行类型推导，这固然也有推导不出的状况，这个时候该变量的类型就是 any，这个叫作隐式 any。区别于显式 any：

const a: any = {};

隐式 any 是 TypeScript 编译器推断的。

  • noImplicitThis（推荐打开）

默认：true

首次发布版本：2.0

和隐式 any 类型， 只不过此次是针对的特殊的一个关键字 this，也就是你须要显式地指定 this 的类型。

  • strict（推荐打开）

默认：true

首次发布版本：2.3

实际上 strict 只是一个简写，是多个规则的合集。 相似于 babel 中插件（plugins）和 预设（presets）的差异。换句话说若是你指定了 strict 为 true ，那么全部严格相关的规则的都会开启，我所讲的严格检查都是，还有一部分我没有提到的。另外未来若是增长更多严格规则，你只要开启了 strict 则会自动加进来。

模块解析

模块相关

目的：allowSyntheticDefaultImports，allowUmdGlobalAccess，esModuleInterop，moduleResolution 都是为了和其余模块化规范兼容作的。

  • allowSyntheticDefaultImports
  • allowUmdGlobalAccess
  • esModuleInterop
  • moduleResolution

还有一个配置 module，规定了项目的模块化方式，选项有 AMD，UMD，commonjs 等。

路径相关

目的： baseUrl，paths，rootDirs， typeRoots，types 都是为了简化路径的拼写作的。

  • baseUrl

这个配置是告诉 TypeScript 如何解析模块路径的。好比：

import { helloWorld } from "hello/world";

console.log(helloWorld);

这个就会从 baseUrl 下找 hello 目录下的 world 文件。

  • paths

定义相似别名的存在，从而简化路径的书写。

  • rootDirs

注意是 rootDirs ，而不是 rootDir，也就是说根目录能够有多个。 当你指定了多个根目录的时候， 不一样根目录的文件能够像在一个目录下同样互相访问。

实际上也有一个叫 rootDir 的， 和 rootDirs 的区别就是其只能指定一个。
  • typeRoots
  • types

types 和 typeRoots 我在 - types 和 @types 是什么？ 已经讲得很清楚了，这里就很少说了。

项目配置

JavaScript 相关

  • allowJs

默认：false

首次发布版本：1.8

顾名思义，容许在 TypeScript 项目中使用 JavaScript，这在从 JavaScript 迁移到 TypeScript 中是很是重要的。

  • checkJs

默认：false

首次发布版本：-

和 allowJs 相似， 只不过 checkJs 会额外对 JS 文件进行校验。

声明文件相关

若是 TypeScript 是将 TS 文件编译为 JS，那么声明文件 + JS 文件就能够反推出 TS 文件。

这两个用来生成 .d.ts 和 .d.ts 的 sourcemap 文件。

  • declaration

默认：false

首次发布版本：1.0

  • declarationMap

默认：false

首次发布版本：2.9

外部库相关

  • jsx

默认：react

首次发布版本：2.2

这个是告诉 TypeScript 如何编译 jsx 语法的。

  • lib

默认：-

首次发布版本：2.0

lib 我在 TypeScript 类型系统 中讲过。 Typescript 提供了诸如 lib.d.ts 等类型库文件。随着 ES 的不断更新， JavaScript 类型和全局变量会逐渐变多。Typescript 也是采用这种 lib 的方式来解决的。

（TypeScript 提供的部分 lib）

输出相关

outDir 和 outFile 这两个配置则是告诉 TypeScript 将文件生成到哪里。

  • outDir

默认：和 ts 文件同目录（且同名，只是后缀不一样）

首次发布版本：-

  • outFile

默认：-

首次发布版本：1.0

module 是 CommonJS 和 ES6 module 不能知道 outFile，只有是 None, System 或 AMD 才行，其会将这些模块的文件内容打包到全局文件内容以后。

而 noEmit 则是控制是否输出 JS 文件的。

  • noEmit

默认：false

首次发布版本：-

若是你只但愿用 TypeScript 进行类型检查，不但愿要它生成文件，则能够将 noEmit 设置成 true。

  • target

即输出的 JavaScript 对标的 ECMA 规范。 好比 “target”: “es6” 就是将 es6 + 的语法转换为 ES6 的 代码。其选项有 ES3，ES5，ES6 等。

为何没有 ES4 ？ ^_^

总结

  • tsconfig 就是一个 JSON 文件，TypeScript 会使用该文件来决定如何编译和检查 TypeScript 项目。和 babel 相似，甚至不少配置项都是相通的。
  • 若是一个目录下存在一个 tsconfig.json 文件，那么意味着这个目录是 TypeScript 项目的根目录。 若是你使用 tsc 编译你的项目，而且没有显式地指定配置文件的路径，那么 tsc 则会逐级向上搜索父目录寻找 tsconfig.json ，这个过程相似 node 的模块查找机制。
  • tsconfig 中最重要的恐怕就是编译器选项（compilerOptions）了。若是你按照功能去记忆则会比较简单， 好比文件相关的有哪些， 严格检查的有哪些，声明文件的有哪些等等。

参考

关注我

你们也能够关注个人公众号《脑洞前端》获取更多更新鲜的前端硬核文章，带你认识你不知道的前端。

知乎专栏【 Lucifer - 知乎】

点关注，不迷路！

相关文章
相关标签/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公众号
   欢迎关注本站公众号,获取更多信息
联系我们 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程