TypeScript——tsconfig.json

tsconfig.json1、使用配置文件1.1、自动搜索配置文件1.2、指定配置文件2、编译选项列表3、编译文件列表3.1、--listFiles编译选项3.2、 默认编译文件列表3.3、files属性3.4、include属性3.5、 exclude属性4、声明文件列表4.1、--typeRoots编译选项4.2、--types编译选项5、继承配置文件5.1、--showConfig编译选项5.2、使用相对路径5.3、使用非相对路径在TypeScript 1.5版本之前缺少一种内置的方法能够管理TypeScript工程的配置。在TypeScript 1.5版本中提供了使用tsconfig.json配置文件来管理TypeScript工程的功能从而弥补了这个不足。tsconfig.json配置文件能够管理如下种类的工程配置编译文件列表。编译选项。tsconfig.json配置文件间的继承关系TypeScript 2.1​。工程间的引用关系TypeScript 3.0​。1、使用配置文件“tsconfig.json”配置文件是一个JSON[插图]格式的文件。若一个目录中存在“tsconfig.json”文件那么该目录将被编译器视作TypeScript工程的根目录。假设当前工程目录结构如下C:\app |-- src | -- index.ts -- tsconfig.json此例中​“C:\app”目录下包含了一个“tsconfig.json”文件因此“C:\app”成了一个TypeScript工程并且“C:\app”目录将被视为工程的根目录。“tsconfig.json”文件的内容如下{compilerOptions:{target:ES5}}在编写好“tsconfig.json”配置文件之后有以下两种方式来使用它运行tsc命令时让编译器自动搜索“tsconfig.json”配置文件。运行tsc命令时使用“–project”或“-p”编译选项指定使用的“tsconfig.json”配置文件。需要注意的是如果运行tsc命令时指定了输入文件那么编译器将忽略“tsconfig.json”配置文件既不会自动搜索配置文件也不会使用指定的配置文件。示例如下tsc index.ts-ptsconfig.json此例中在运行tsc命令时指定了输入文件“index.ts”​因此编译器将不使用指定的“tsconfig.json”配置文件。1.1、自动搜索配置文件在运行tsc命令时若没有使用“–project”或“-p”编译选项那么编译器将在tsc命令的运行目录下查找是否存在文件名为“tsconfig.json”的配置文件。若存在“tsconfig.json”配置文件则使用该配置文件来编译工程若不存在则继续在父级目录下查找“tsconfig.json”配置文件直到搜索到系统根目录为止如果最终也未能找到一个可用的“tsconfig.json”配置文件那么就会停止编译工程。假设当前工程目录结构如下C:\app |-- src | -- index.ts -- tsconfig.json当在“C:\app\src”目录下运行tsc命令时编译器搜索“tsconfig.json”配置文件的流程如下搜索“C:\app\src\tsconfig.json”​。搜索“C:\app\tsconfig.json”​。搜索“C:\tsconfig.json”​。退出tsc编译命令不进行编译。一旦编译器找到了匹配的“tsconfig.json”配置文件就会终止查找过程并使用找到的配置文件。此例中在第2步能够找到匹配的“tsconfig.json”配置文件于是使用该配置文件来编译工程并终止后续的查找。1.2、指定配置文件在运行tsc命令时可以使用“–project”编译选项短名字为“-p”​来指定使用的配置文件。“–project”编译选项的参数是一个路径它的值可以为指向某个具体的配置文件。在这种情况下配置文件的文件名不限例如可以使用名为“app.config.json”的配置文件。指向一个包含了“tsconfig.json”配置文件的目录。在这种情况下该目录中必须包含一个名为“tsconfig.json”的配置文件。假设当前工程目录结构如下C:\app |-- src | -- index.ts |-- tsconfig.json -- tsconfig.release.json在“C:\app”目录下运行tsc命令并使用“-p”编译选项来指定使用“tsconfig.release.json”配置文件编译该工程。示例如下tsc-ptsconfig.release.json在“C:\app”目录下运行tsc命令并使用“-p”编译选项来指定一个包含了“tsconfig.json”配置文件的目录。示例如下tsc-p.此例中​“-p”编译选项的参数值为一个点符号“.”​它表示当前目录也就是运行tsc命令时所在的目录。因此编译器会查找并使用“C:\app\tsconfig.json”配置文件。2、编译选项列表在“tsconfig.json”配置文件中使用顶层的“compilerOptions”属性能够设置编译选项。对于同一个编译选项而言不论是在命令行上指定还是在“tsconfig.json”配置文件中指定它们都具有相同的效果并且使用相同的名称。示例如下{compilerOptions:{strict:true,target:ES5}}注意不是所有的编译选项都能够在“tsconfig.json”配置文件中指定。例如前文介绍的“–help”和“–version”编译选项不支持在“tsconfig.json”配置文件中使用。TypeScript提供了一个“–init”编译选项在命令行上运行tsc命令并使用“–init”编译选项会初始化一个“tsconfig.json”配置文件。在生成的“tsconfig.json”配置文件中会自动添加一些常用的编译选项并将它们分类。假设当前工程目录结构如下C:\app -- index.ts在“C:\app”目录下运行tsc命令并使用“–init”编译选项。示例如下tsc--inittsc命令的运行结果是在“C:\app”目录下新生成了一个“tsconfig.json”配置文件。该文件的内容如下{compilerOptions:{/* 基础选项 */incremental:true,target:es5,module:commonjs,lib:[],allowJs:true,checkJs:true,jsx:preserve,declaration:true,declarationMap:true,sourceMap:true,outFile:./,outDir:./,rootDir:./,composite:true,tsBuildInfoFile:./,removeComments:true,noEmit:true,importHelpers:true,downlevelIteration:true,isolatedModules:true,/* 严格类型检查选项 */strict:true,noImplicitAny:true,strictNullChecks:true,strictFunctionTypes:true,strictBindCallApply:true,strictPropertyInitialization:true,noImplicitThis:true,alwaysStrict:true,/* 额外检查选项 */noUnusedLocals:true,noUnusedParameters:true,noImplicitReturns:true,noFallthroughCasesInSwitch:true,/* 模块解析选项 */moduleResolution:node,baseUrl:./,paths:{},rootDirs:[],typeRoots:[],types:[],allowSyntheticDefaultImports:true,esModuleInterop:true,preserveSymlinks:true,allowUmdGlobalAccess:true,/* SourceMap 选项 */sourceRoot:,mapRoot:,inlineSourceMap:true,inlineSources:true,/* 实验性选项 */experimentalDecorators:true,emitDecoratorMetadata:true,/* 高级选项 */forceConsistentCasingInFileNames:true}}3、编译文件列表“tsconfig.json”配置文件的另一个主要用途是配置待编译的文件列表。3.1、–listFiles编译选项TypeScript提供了一个“–listFiles”编译选项如果启用了该编译选项那么在编译工程时编译器将打印出参与本次编译的文件列表。该编译选项既可以在命令行上使用也可以在“tsconfig.json”配置文件中使用。假设当前工程目录结构如下C:\app -- src |---a.ts -- b.ts在命令行上使用“–listFiles”编译选项示例如下tsc--listFiles在“tsconfig.json”配置文件中使用“–listFiles”编译选项示例如下{compilerOptions:{listFiles:true,strict:true,target:ES5}}在使用上例中的“tsconfig.json”配置文件编译工程时编译器将输出编译文件列表。示例如下...\typescript\lib\lib.d.ts...\typescript\lib\lib.es5.d.ts...\typescript\lib\lib.dom.d.ts...\typescript\lib\lib.webworker.importscripts.d.ts...\typescript\lib\lib.scripthost.d.ts C:\app\src\a.ts C:\app\src\b.ts通过以上运行结果能够看到编译文件列表除了包含工程内的源文件外还包含了Type-Script内置的一些声明文件。3.2、 默认编译文件列表如果工程中含有一个“tsconfig.json”配置文件那么在默认情况下“tsconfig.json”配置文件所在目录及其子目录下的所有“.ts”​“.d.ts”​“.tsx”文件都会被添加到编译文件列表。假设当前工程目录结构如下C:\app |-- a.ts |-- src | |-- b.ts | -- c.ts -- tsconfig.json“tsconfig.json”配置文件内容如下{compilerOptions:{listFiles:true}}在“C:\app”目录下运行tsc编译命令示例如下tsctsc命令的运行结果如下此处省略了内置的声明文件列表 C:\app\a.ts C:\app\src\b.ts C:\app\src\c.ts通过以上运行结果能够看到​“C:\app”目录与其子目录“C:\app\src”下的所有Type-Script源文件都参与了本次编译。3.3、files属性在“tsconfig.json”配置文件中使用顶层的“files”属性能够定义编译文件列表。​“files”属性的值是由待编译文件路径所构成的数组。假设当前工程目录结构如下C:\app |-- a.ts |-- src | |-- b.ts | -- c.ts -- tsconfig.json“tsconfig.json”配置文件内容如下{compilerOptions:{listFiles:true},files:[src/b.ts,src/c.ts]}在“C:\app”目录下运行tsc命令示例如下tsctsc命令的运行结果如下此处省略了内置的声明文件列表 C:\app\src\b.ts C:\app\src\c.ts通过以上运行结果能够看到只有“files”属性中指定的“C:\app\src\b.ts”和“C:\app\src\c.ts”文件参与了本次编译而“C:\app\a.ts”文件则没有参与编译。在使用“files”属性设置编译文件列表时必须逐一地列出每一个文件该属性不支持进行模糊的文件匹配。因此​“files”属性适用于待编译文件数量较少的情况。当待编译文件数量较多时使用“include”和“exclude”属性是更好的选择。3.4、include属性在“tsconfig.json”配置文件中使用顶层的“include”属性能够定义编译文件列表。​“include”属性的功能包含了“files”属性的功能它既支持逐一地列出每一个待编译的文件也支持使用通配符来模糊匹配待编译的文件。“include”属性支持使用三种通配符来匹配文件。假设当前工程目录结构如下C:\app |-- bar | -- c.ts |-- foo | |-- a.spec.ts | |-- a.ts | |-- b.spec.ts | -- b.ts -- tsconfig.json如果tsconfig.json配置文件的内容如下{include:[foo/*.spec.ts]}那么只有“C:\app\foo\a.spec.ts”和“C:\app\foo\b.spec.ts”文件会被添加到编译文件列表。如果“tsconfig.json”配置文件的内容如下{include:[foo/?.ts]}那么只有“C:\app\foo\a.ts”和“C:\app\foo\b.ts”文件会被添加到编译文件列表。如果“tsconfig.json”配置文件的内容如下{include:[bar/**/*.ts]}那么只有“C:\app\bar\c.ts”文件会被添加到编译文件列表。3.5、 exclude属性在“tsconfig.json”配置文件中​“exclude”属性需要与“include”属性一起使用它的作用是从“include”属性匹配到的文件列表中去除指定的文件。​“exclude”属性也支持和“include”属性相同的通配符。假设当前工程目录结构如下C:\app |-- bar | -- c.ts |-- foo | |-- a.spec.ts | |-- a.ts | |-- b.spec.ts | -- b.ts -- tsconfig.json“tsconfig.json”配置文件的内容如下{compilerOptions:{listFiles:true},include:[**/*],exclude:[**/*.spec.ts]}在“C:\app”目录下运行tsc命令示例如下tsctsc命令的运行结果如下此处省略了内置的声明文件列表 C:\app\bar\c.ts C:\app\foo\a.ts C:\app\foo\b.ts此例中​“include”属性将“C:\app”目录下所有的“.ts”文件添加到编译文件列表然后“exclude”属性则将所有的“.spec.ts”文件从编译文件列表中移除。4、声明文件列表在TypeScript工程中“node_modules/types”目录是一个特殊的目录TypeScript将其视为第三方声明文件的根目录因为在安装DefinitelyTyped提供的声明文件时它会被安装到“node_modules/types”目录下。在默认情况下编译器会将安装在“node_modules/types”目录下的所有声明文件添加到编译文件列表。该默认行为可以使用“–typeRoots”和“–types”编译选项设置。4.1、–typeRoots编译选项“–typeRoots”编译选项用来设置声明文件的根目录。当配置了“–typeRoots”编译选项时只有该选项指定的目录下的声明文件会被添加到编译文件列表而“node_modules/types”目录下的声明文件将不再被默认添加到编译文件列表。假设当前工程目录结构如下C:\app |-- node_modules | -- types | -- jquery | | |-- ... | | |-- index.d.ts | | -- package.json | -- ... |-- typings | -- utils | -- index.d.ts |-- index.ts |-- package.json |-- package-lock.json -- tsconfig.json“tsconfig.json”配置文件的内容如下{compilerOptions:{listFiles:true,typeRoots:[./typings]}}注意​“typeRoots”属性中的路径是相对于当前“tsconfig.json”配置文件的路径来进行解析的。在“C:\app”目录下运行tsc命令示例如下tsctsc命令的运行结果如下此处省略了内置的声明文件列表 C:\app\index.ts C:\app\typings\utils\index.d.ts通过该运行结果能够看到只有“typeRoots”属性定义的“C:\app\typings”目录下的声明文件被添加到了编译文件列表而“C:\app\node_modulestypes”目录下的声明文件则没有被添加到编译文件列表。如果想要同时使用“C:\app\typings”和“C:\app\node_modulestypes”目录下的声明文件则需要将两者同时添加到“typeRoots”属性中。示例如下{compilerOptions:{listFiles:true,typeRoots:[./node_modules/types,./typings]}}在“C:\app”目录下运行tsc命令的运行结果如下此处省略了内置的声明文件列表 C:\app\index.ts C:\app\typings\utils\index.d.ts C:\app\node_modules\types\jquery\index.d.ts4.2、–types编译选项“–types”编译选项也能够用来指定使用的声明文件。​“–typeRoots”编译选项配置的是含有声明文件的目录而“–types”编译选项则配置的是具体的声明文件。假设当前工程目录结构如下C:\app |-- node_modules | -- types | |-- jquery | | |-- index.d.ts | | -- package.json | -- lodash | |-- index.d.ts | -- package.json |-- index.ts |-- package.json |-- package-lock.json -- tsconfig.json“tsconfig.json”配置文件的内容如下{compilerOptions:{listFiles:true,types:[jquery]}}在“C:\app”目录下运行tsc命令示例如下tsc --listFilestsc命令的运行结果如下此处省略了内置的声明文件列表 C:\app\index.ts C:\app\node_modules\types\jquery\index.d.ts通过以上运行结果能够看到只有“types”属性中定义的jQuery声明文件被添加到了编译文件列表而“C:\app\node_modulestypes\lodash\index.d.ts”声明文件则没有被添加到编译文件列表。5、继承配置文件一个“tsconfig.json”配置文件可以继承另一个“tsconfig.json”配置文件中的配置。当一个项目中包含了多个TypeScript工程时我们可以将工程共同的配置提取到“tsconfig.base.json”配置文件中其他的“tsconfig.json”配置文件继承“tsconfig.base.json”配置文件中的配置。这种方式避免了重复配置同一属性并且能够增强可维护性当需要修改某一共通属性时仅需要修改一处即可。在“tsconfig.json”配置文件中使用顶层的“extends”属性来设置要继承的“tscon-fig.json”配置文件。在“extends”属性中指定的路径既可以是相对路径也可以是绝对路径但路径解析规则有所不同。5.1、–showConfig编译选项在介绍配置文件的继承之前先介绍一下“–showConfig”编译选项。在使用该编译选项后编译器将显示出编译工程时使用的所有配置信息。当我们在调试工程配置的时候该编译选项是非常有帮助的。但需要注意的是若启用了“–showConfig”编译选项那么编译器将不会真正编译一个工程而只是显示工程的配置。假设当前工程目录结构如下C:\app |-- src | -- index.ts -- tsconfig.json“tsconfig.json”配置文件的内容如下{compilerOptions:{listFiles:true,target:ES6}}在“C:\app”目录下运行tsc命令示例如下tsctsc命令的运行结果如下{compilerOptions:{target:es6},files:[./src/index.ts]}该结果显示了在编译工程时最终使用的配置信息它不但包含了“tsconfig.json”配置文件中的配置信息还包含了待编译的文件列表。注意​“–showConfig”编译选项只能在命令行上使用在“tsconfig.json”配置文件中不能使用该编译选项。5.2、使用相对路径若“extends”属性中指定的路径是以“./”或“…/”作为起始的那么编译器在解析相对路径时将参照当前“tsconfig.json”配置文件所在的目录。假设当前工程目录结构如下C:\app |-- src | -- index.ts |-- tsconfig.app.json |-- tsconfig.base.json -- tsconfig.spec.json在“tsconfig.base.json”配置文件中包含了共同的配置而“tsconfig.app.json”配置文件和“tsconfig.spec.json”配置文件继承了“tsconfig.base.json”配置文件中的配置。“tsconfig.base.json”文件的内容如下{compilerOptions:{target:ES6}}“tsconfig.app.json”文件的内容如下{extends:./tsconfig.base.json,compilerOptions:{strict:true},files:[./src/index.ts]}在“C:\app”目录下运行tsc命令并使用“tsconfig.app.json”配置文件来编译该工程。示例如下tsc--showConfig-ptsconfig.app.jsontsc命令的运行结果如下{compilerOptions:{target:es6,strict:true},files:[./src/index.ts]}在“C:\app”目录下运行tsc命令并使用“tsconfig.spec.json”配置文件来编译该工程。示例如下tsc--showConfig-ptsconfig.spec.jsontsc命令的运行结果如下{compilerOptions:{target:es6,strict:false},files:[./src/index.spec.ts]}通过以上运行结果能够看到​“tsconfig.app.json”配置文件和“tsconfig.spec.json”配置文件都继承了“tsconfig.base.json”配置文件中的“target”编译选项。5.3、使用非相对路径若“extends”属性指定的路径不是以“./”或“…/”作为起始的那么编译器将在“node_modules”目录下查找指定的配置文件。编译器首先在“tsconfig.json”配置文件所在目录的“node_modules”子目录下查找若该目录下包含了指定的配置文件则使用该配置文件否则继续在父级目录下的“node_modules”子目录下查找直到搜索到系统根目录为止。若最终未能找到指定的配置文件则产生编译错误。假设有如下目录结构的工程C:\app |-- node_modules | -- tsconfig | -- tsconfig.standard.json |-- index.ts -- tsconfig.json“tsconfig.json”配置文件的内容如下{extends:tsconfig/tsconfig.standard.json}此例中编译器查找“tsconfig/tsconfig.standard.json”文件的步骤如下查找“C:\app\node_modules\tsconfig\tsconfig.standard.json”文件。查找“C:\node_modules\tsconfig\tsconfig.standard.json”文件。报错文件未找到。当编译器找到了匹配的配置文件时就会终止查找过程。此例中在第1步找到了匹配的“tsconfig.standard.json”配置文件于是使用该配置文件来编译工程并终止后续的查找。