tsconfig.json编译选项配置说明

• incremental 增量编译，默认在 composite为true的为true，否则false

语言和环境

• target : 编译目标,默认 es3
• reactNamespace; react的命名空间，默认React
• lib： TypeScript 包括一组默认的内置 JS API（如Math）类型定义，以及浏览器环境中的类型定义（如document）。TypeScript 还包括用于匹配target您指定的较新 JS 功能的 API ；例如，Map如果target是ES6或更新，则定义可用。官方
• noLib： 禁用自动包含任何库文件。默认为false 。 当启用这个设置的时候，Array, Boolean, Function, IArguments, Number, Object, RegExp, 和String等类型都需要自己定义。
• jsx: 默认react , 控制如何在 JavaScript 文件中发出 JSX 构造。这只会影响文件中开始的 JS 文件的输出.tsx。
• experimentalDecorators : 启用对装饰器的支持
• emitDecoratorMetadata： 为装饰器输出类型支持

模块

选项	值	说明
allowUmdGlobalAccess	默认 false	允许Umd全局访问
baseUrl		解析非绝对模块名的基准目录
module		编译出来的代码使用什么模块系统
moduleResolution	'node' 用于 Node.js 的 CommonJS 实现 'classic'在 1.6 版本之前的 TypeScript 中使用, 之后版本不建议	模块解析策略
paths		设置路径映射，避免很长的相对路径
noResolve	默认值 false	不把 /// <reference``>或模块导入的文件加到编译文件列表
resolveJsonModule	默认值 false	允许导入带有“json扩展名的模块
rootDirs	默认：从输入文件列表计算。
rootDir	默认：从输入文件列表计算。
typeRoots
types

输出

选项	值	说明
outDir		指定编译文件的输出目录
outFile		当module是None，System或AMD的时候，将编译后的所有内容输出到指定文件
noEmit	默认 false	不输出任何文件
noEmitOnError	默认 false	报错时不生成输出文件。
noEmitHelpers	默认 false
preserveConstEnums	如果 isolatedModules 为 true ,否则为 fase	保留枚举常量(即const enum) 的声明，只是保留，并不使用。
preserveValueImports
removeComments	默认 false	删除注释
sourceMap	默认false	是否生成映射文件
sourceRoot		映射文件所在位置
declaration	如果 composite 为 true ,否则为 fase	为项目中的每个 TypeScript 或 JavaScript 文件生成.d.ts文件
declarationDir		类型说明文件的输出目录，相对于 outDir
declarationMap	默认 false	为.d.ts和.ts生成映射文件
downlevelIteration	默认false
emitBOM	默认值 false	保持默认值即可，除非有什么特别的理由必须要修改
emitDeclarationOnly	默认 false	只生成类型说明文件
importHelpers	默认 false
importsNotUsedAsValues
inlineSourceMap	默认 false	将生成的 js souremap 内联到 JavaScript 文件中
inlineSources	默认 false	TypeScript 会将.ts文件的原始内容作为嵌入字符串包含在源映射中
newLine	两个值crlf和lf，具体根据平台确定	使用何种换行符 CRLF (dos) 或 LF (unix)

类型检查

选项	值	说明
allowUnreachableCode	undefined （默认）向编辑提供建议作为警告 true 无法访问的代码被忽略 false 引发有关无法访问的代码的编译器错误	允许存在永远不会执行的代码
allowUnusedLabels	undefined （默认）向编辑提供建议作为警告 true 未使用的标签被忽略 false 引发有关未使用标签的编译器错误	允许未使用的标签
exactOptionalPropertyTypes	默认 true	严格明确可选属性类型
noFallthroughCasesInSwitch	默认 false	不允许switch的case语句贯穿
noImplicitReturns	默认 false	不允许函数使用隐式的返回类型
noImplicitOverride
noPropertyAccessFromIndexSignature	默认 false	不允许使用点语法来访问未定义的字段
noUncheckedIndexedAccess
noUnusedLocals	默认 false	不允许存在未使用的局部变量
noUnusedParameters	默认 false	不允许存在未使用的参数
strict	默认 false	启用所有严格类型检查选项 alwaysStrict strictNullChecks strictBindCallApply strictFunctionTypes strictPropertyInitialization noImplicitAny noImpliitThis useUnknownInCatchVariables
alwaysStrict	strict 为true的时候默认为 true，否则 false	始终使用严格模式，在module为每个源文件添加use strict声明。
noImplicitAny	strict 为true的时候默认为 true，否则 false	不允许使用隐式的any类型
noImplicitThis	strict 为true的时候默认为 true，否则 false	不允许this表达式的值为隐式d的 any类型
strictFunctionTypes	strict 为true的时候默认为 true，否则 false	严格检查函数的参数类型是否匹配
strictBindCallApply	strict 为true的时候默认为 true，否则 false	使用call或者apply时，严格检查参数的类型是否匹配
strictNullChecks	strict 为true的时候默认为 true，否则 false	不允许隐式的null和undefined
strictPropertyInitialization	strict 为true的时候默认为 true，否则 false	确保类的非undefined属性已经在构造函数里初始化。若要令此选项生效，需要同时启用–strictNullChecks
useUnknownInCatchVariables	strict 为true的时候默认为 true，否则 false	在 TypeScript 4.0 中，添加了支持以允许将 catch 子句中的变量类型从any更改为unknown

交互约束

• esModuleInterop （默认false）

• allowSyntheticDefaultImports
  如果module===‘system’，或开启esModuleInterop并且module不是es6/es2015/esnext 的时候为true, 否则为false。

  typescript编译选项esModuleInterop的作用

• forceConsistentCasingInFileNames（默认 false）
  强制文件名区分大小写

• isolatedModules（默认 false）
  将每个文件作为单独的模块，当启用的时候，所有实现文件都必须是模块（这意味着它具有某种形式的import/ export）
  限制不适用于.d.ts文件

• preserveSymlinks

Javascript 支持

选项	值	说明
allowJs	默认 false	允许编译javascript文件。
checkJs	默认 false	在 .js文件中报告错误。与 --allowJs配合使用。
maxNodeModuleJsDepth	默认 0	搜索node_modules和加载 JavaScript 文件的最大依赖深度。

编辑器支持

选项	值	说明
disableSizeLimit	默认 false	为了避免在处理非常大的 JavaScript 项目时可能出现的内存膨胀问题，TypeScript 将分配的内存量有一个上限。打开此标志将取消限制。

reference

项目引用是 TypeScript 3.0的新特性，它支持将 TypeScript 程序的结构分割成更小的组成部分。

这是 typescript 官网中的描述，那怎么理解这句话呢。我们通过一个场景认识新出这种的 reference 特性。

假设我们要开发一个类似于 lodash 的工具库，并在项目中使用，而且后期很有可能还要在业界推广。为了保证这个工具的顺利开发及推广，我们必须要做相应的单元测试。那这个工具库可以看做一个项目，对其中的每个功能的测试也可作为一个独立的项目。但整个过程中，工具库的开发和测试应该是属于同一个项目下 “分项目” 的。那这种情况下 reference 就很棒了。首先我们搭一个目录出来：

|---- src/
 |---- index.ts // 整个工具库的入口
 |---- copyDeep.ts // 其中定义了copyDeep方法
|---- test/
 |---- copyDeep.test.ts // copyDeep的单元测试
|---- package.json
|---- tsconfig.json

在 copyDeep.test.ts 中肯定要引用 src/copyDeep，也就是说 test 的项目是依赖于 src 的。如果 src 中的代码发生了变化，整个工具库项目应该重新编译，而 test 项目不应该再被编译，这本来就是合理的。如果 test 项目中的代码发生了变化，那 test 项目应该被重新编译，而 src 项目不应该再被编译。如何在一个项目中配置而做到分别编译相应的子项目呢？首先最先想到的应该是在 tsconfig.json 文件中引入 include 字段配置，我们先尝试一下下面的配置：

{
 "files": [
 "./src/index.ts"
 ],
 "include": [
 "./test/**/*.test.ts"
 ],
 "compilerOptions": {
 "outDir": "./dist/"
 }
}

我们来分析这样配置的会有哪些问题：

1. 首先，从整个项目层面，确实做到了修改任意文件重新编译的功能。但注意，编译的是全量的 ts 文件。
2. 随着日后项目的增大，在 *.test.ts 文件中引入也将逐渐变大。
3. 修改了 src//**/*.ts 的内容，test/**/*.ts 也将作为输出，这是我们不希望看到的。

此时，reference 将解决上述的每一个问题，我们修改项目结构如下：

|---- src/
 |---- index.ts // 整个工具库的入口
 |---- copyDeep.ts // 其中定义了copyDeep方法
 |---- tsconfig.json // 工具库的编译配置文件
|---- test/
 |---- copyDeep.test.ts // copyDeep的单元测试
 |---- tsconfig.json // 测试的编译配置文件
|---- package.json
|---- tsconfig.json

并修改为以下配置：

// 根目录下的 /tsconfig.json
{
 "compilerOptions": {
 "declaration": true, // 为子项目生成.d.ts声明文件
 "outDir": "./dist",
 }
}

// src目录下的 /src/tsconfig.json
{
 "extends": "../tsconfig",
 "compilerOptions": {
 "composite": true // 必须设置为true，表明该文件夹为一个子项目
 }
}

// test目录下的 /src/tsconfig.json
{
 "extends": "../tsconfig",
 "references": [
 { "path": "../src" } // 表示引用了工具库项目
 ]
}

这样配置后，如果 src 项目已经编译完成并且输出了编译后的文件， 那在 test 项目中，实际加载的是 src 项目声明的 .d.ts 文件，而且这个声明文件是对 test 项目可见的。另外，如果开启了 watch 模式，修改了内容只会编译相应的项目而不会全量编译。这会显著的加速类型检查和编译，减少编辑器的内存占用。而且在代码结构层命有了一个很清晰的规划。

总结来讲，refrence 的作用是将两个项目关联起来作为一个项目开发，当某个项目代码修改后还能单独编译相应的项目而不是整个项目。再说的简单点，就是实现了关联项目间的懒编译。