TypeScript 详解之 tsconfig.json

简介

tsconfig.json是 TypeScript 项目的配置文件,放在项目的根目录。反过来说,如果一个目录里面有tsconfig.json,TypeScript 就认为这是项目的根目录。

如果项目源码是 JavaScript,但是想用 TypeScript 处理,那么配置文件的名字是jsconfig.json,它跟tsconfig的写法是一样的。

tsconfig.json文件主要供tsc编译器使用,它的命令行参数--project-p可以指定tsconfig.json的位置(目录或文件皆可)。

$ tsc -p ./dir

如果不指定配置文件的位置,tsc就会在当前目录下搜索tsconfig.json文件,如果不存在,就到上一级目录搜索,直到找到为止。

tsconfig.json文件的格式,是一个 JSON 对象,最简单的情况可以只放置一个空对象{}。下面是一个示例。

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

本章后面会详细介绍tsconfig.json的各个属性,这里简单说一下,上面示例的四个属性的含义。

  • include:指定哪些文件需要编译。
  • allowJs:指定源目录的 JavaScript 文件是否原样拷贝到编译后的目录。
  • outDir:指定编译产物存放的目录。
  • target:指定编译产物的 JS 版本。

tsconfig.json文件可以不必手写,使用 tsc 命令的--init参数自动生成。

$ tsc --init

上面命令生成的tsconfig.json文件,里面会有一些默认配置。

你也可以使用别人预先写好的 tsconfig.json 文件,npm 的@tsconfig名称空间下面有很多模块,都是写好的tsconfig.json样本,比如 @tsconfig/recommended@tsconfig/node16

这些模块需要安装,以@tsconfig/deno为例。

$ npm install --save-dev @tsconfig/deno
# 或者
$ yarn add --dev @tsconfig/deno

安装以后,就可以在tsconfig.json里面引用这个模块,相当于继承它的设置,然后进行扩展。

{
  "extends": "@tsconfig/deno/tsconfig.json"
}

@tsconfig空间下包含的完整 tsconfig 文件目录,可以查看 GitHub

tsconfig.json的一级属性并不多,只有很少几个,但是compilerOptions属性有很多二级属性。下面先逐一介绍一级属性,然后再介绍compilerOptions的二级属性,按照首字母排序。

exclude

exclude属性是一个数组,必须与include属性一起使用,用来从编译列表中去除指定的文件。它也支持使用与include属性相同的通配符。

{
  "include": ["**/*"],
  "exclude": ["**/*.spec.ts"]
}

extends

tsconfig.json可以继承另一个tsconfig.json文件的配置。如果一个项目有多个配置,可以把共同的配置写成tsconfig.base.json,其他的配置文件继承该文件,这样便于维护和修改。

extends属性用来指定所要继承的配置文件。它可以是本地文件。

{
  "extends": "../tsconfig.base.json"
}

如果extends属性指定的路径不是以./../开头,那么编译器将在node_modules目录下查找指定的配置文件。

extends属性也可以继承已发布的 npm 模块里面的 tsconfig 文件。

{
  "extends": "@tsconfig/node12/tsconfig.json"
}

extends指定的tsconfig.json会先加载,然后加载当前的tsconfig.json。如果两者有重名的属性,后者会覆盖前者。

files

files属性指定编译的文件列表,如果其中有一个文件不存在,就会报错。

它是一个数组,排在前面的文件先编译。

{
  "files": ["a.ts", "b.ts"]
}

该属性必须逐一列出文件,不支持文件匹配。如果文件较多,建议使用includeexclude属性。

include

include属性指定所要编译的文件列表,既支持逐一列出文件,也支持通配符。文件位置相对于当前配置文件而定。

{
  "include": ["src/**/*", "tests/**/*"]
}

include属性支持三种通配符。

  • ?:指代单个字符
  • *:指代任意字符,不含路径分隔符
  • **:指定任意目录层级。

如果不指定文件后缀名,默认包括.ts.tsx.d.ts文件。如果打开了allowJs,那么还包括.js.jsx

references

references属性是一个数组,数组成员为对象,适合一个大项目由许多小项目构成的情况,用来设置需要引用的底层项目。

{
  "references": [
    { "path": "../pkg1" },
    { "path": "../pkg2/tsconfig.json" }
  ]
}

references数组成员对象的path属性,既可以是含有文件tsconfig.json的目录,也可以直接是该文件。

与此同时,引用的底层项目的tsconfig.json必须启用composite属性。

{
  "compilerOptions": {
    "composite": true
  }
}

compileOptions

compilerOptions属性用来定制编译行为。这个属性可以省略,这时编译器将使用默认设置。

allowJs

allowJs允许 TypeScript 项目加载 JS 脚本。编译时,也会将 JS 文件,一起拷贝到输出目录。

{
  "compilerOptions": {
    "allowJs": true
  }
}

alwaysStrict

alwaysStrict确保脚本以 ECMAScript 严格模式进行解析,因此脚本头部不用写"use strict"。它的值是一个布尔值,默认为true

allowSyntheticDefaultImports

allowSyntheticDefaultImports允许import命令默认加载没有default输出的模块。

比如,打开这个设置,就可以写import React from "react";,而不是import * as React from "react";

allowUnreachableCode

allowUnreachableCode设置是否允许存在不可能执行到的代码。它的值有三种可能。

  • undefined: 默认值,编辑器显示警告。
  • true:忽略不可能执行到的代码。
  • false:编译器报错。

allowUnusedLabels

allowUnusedLabels设置是否允许存在没有用到的代码标签(label)。它的值有三种可能。

  • undefined: 默认值,编辑器显示警告。
  • true:忽略没有用到的代码标签。
  • false:编译器报错。

baseUrl

baseUrl的值为字符串,指定 TypeScript 项目的基准目录。

由于默认是以 tsconfig.json 的位置作为基准目录,所以一般情况不需要使用该属性。

{
  "compilerOptions": {
    "baseUrl": "./"
  }
}

上面示例中,baseUrl为当前目录./。那么,当遇到下面的语句,TypeScript 将以./为起点,寻找hello/world.ts

import { helloWorld } from "hello/world";

checkJs

checkJS设置对 JS 文件同样进行类型检查。打开这个属性,也会自动打开allowJs。它等同于在 JS 脚本的头部添加// @ts-check命令。

{
  "compilerOptions":{
    "checkJs": true
  }
}

composite

composite打开某些设置,使得 TypeScript 项目可以进行增量构建,往往跟incremental属性配合使用。

declaration

declaration设置编译时是否为每个脚本生成类型声明文件.d.ts

{
  "compilerOptions": {
    "declaration": true
  }
}

declarationDir

declarationDir设置生成的.d.ts文件所在的目录。

{
  "compilerOptions": {
    "declaration": true,
    "declarationDir": "./types"
  }
}

declarationMap

declarationMap设置生成.d.ts类型声明文件的同时,还会生成对应的 Source Map 文件。

还有 66% 的精彩内容
©著作权归作者所有,转载或内容合作请联系作者
支付 ¥6.99 继续阅读
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 157,012评论 4 359
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 66,589评论 1 290
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 106,819评论 0 237
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 43,652评论 0 202
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 51,954评论 3 285
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 40,381评论 1 210
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 31,687评论 2 310
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 30,404评论 0 194
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 34,082评论 1 238
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 30,355评论 2 241
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 31,880评论 1 255
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 28,249评论 2 250
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 32,864评论 3 232
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 26,007评论 0 8
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 26,760评论 0 192
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 35,394评论 2 269
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 35,281评论 2 259

推荐阅读更多精彩内容