TypeScript tsconfig.json

概述

如果一个目录下存在一个tsconfig.json文件，那么它意味着这个目录是TypeScript项目的根目录。tsconfig.json文件中指定了用来编译这个项目的根文件和编译选项。 一个项目可以通过以下方式之一来编译：

使用tsconfig.json

• 不带任何输入文件的情况下调用tsc，编译器会从当前目录开始去查找tsconfig.json文件，逐级向上搜索父目录。
• 不带任何输入文件的情况下调用tsc，且使用命令行参数--project（或-p）指定一个包含tsconfig.json文件的目录。

当命令行上指定了输入文件时，tsconfig.json文件会被忽略。

示例

tsconfig.json示例文件:

• 使用"files"属性

{
    "compilerOptions": {
        "module": "commonjs",
        "noImplicitAny": true,
        "removeComments": true,
        "preserveConstEnums": true,
        "outFile": "../../built/local/tsc.js",
        "sourceMap": true
    },
    "files": [
        "core.ts",
        "sys.ts",
        "types.ts",
        "scanner.ts",
        "parser.ts",
        "utilities.ts",
        "binder.ts",
        "checker.ts",
        "emitter.ts",
        "program.ts",
        "commandLineParser.ts",
        "tsc.ts",
        "diagnosticInformationMap.generated.ts"
    ]
}

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

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

细节

"compilerOptions"可以被忽略，这时编译器会使用默认值。在这里查看完整的[编译器选项](./Compiler Options.md)列表。

"files"指定一个包含相对或绝对文件路径的列表。 "include"和"exclude"属性指定一个文件glob匹配模式列表。 支持的glob通配符有：

• * 匹配0或多个字符（不包括目录分隔符）
• ? 匹配一个任意字符（不包括目录分隔符）
• **/ 递归匹配任意子目录

如果一个glob模式里的某部分只包含*或.*，那么仅有支持的文件扩展名类型被包含在内（比如默认.ts，.tsx，和.d.ts， 如果allowJs设置能true还包含.js和.jsx）。

如果"files"和"include"都没有被指定，编译器默认包含当前目录和子目录下所有的TypeScript文件（.ts,.d.ts 和 .tsx），排除在"exclude"里指定的文件。JS文件（.js和.jsx）也被包含进来如果allowJs被设置成true。 如果指定了 "files"或"include"，编译器会将它们结合一并包含进来。 使用 "outDir"指定的目录下的文件永远会被编译器排除，除非你明确地使用"files"将其包含进来（这时就算用exclude指定也没用）。

使用"include"引入的文件可以使用"exclude"属性过滤。 然而，通过 "files"属性明确指定的文件却总是会被包含在内，不管"exclude"如何设置。 如果没有特殊指定， "exclude"默认情况下会排除node_modules，bower_components，和jspm_packages目录。

任何被"files"或"include"指定的文件所引用的文件也会被包含进来。A.ts引用了B.ts，因此B.ts不能被排除，除非引用它的A.ts在"exclude"`列表中。

tsconfig.json文件可以是个空文件，那么所有默认的文件（如上面所述）都会以默认配置选项编译。

在命令行上指定的编译选项会覆盖在tsconfig.json文件里的相应选项。

compileOnSave

在最顶层设置compileOnSave标记，可以让IDE在保存文件的时候根据tsconfig.json重新生成文件。

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

要想支持这个特性需要Visual Studio 2015， TypeScript1.8.4以上并且安装atom-typescript插件。

模式

到这里查看模式: http://json.schemastore.org/tsconfig.

TypeScript 编译选项

选项	类型	默认值	描述
--allowJs	boolean	true	允许编译javascript文件。
--allowSyntheticDefaultImports	boolean	module === "system"	允许从没有设置默认导出的模块中默认导入。这并不影响代码的显示，仅为了类型检查。
--allowUnreachableCode	boolean	false	不报告执行不到的代码错误。
--allowUnusedLabels	boolean	false	不报告未使用的标签错误。
--baseUrl	string		解析非相对模块名的基准目录。查看模块解析文档了解详情。
--charset	string	"utf8"	输入文件的字符集。
--declaration -d	boolean	false	生成相应的'.d.ts'文件。
--declarationDir	string		生成声明文件的输出路径。
--diagnostics	boolean	false	显示诊断信息。
--disableSizeLimit	boolean	false	禁用JavaScript工程体积大小的限制
--emitBOM	boolean	false	在输出文件的开头加入BOM头（UTF-8 Byte Order Mark）。
--emitDecoratorMetadata[1]	boolean	false	给源码里的装饰器声明加上设计类型元数据。查看issue #2577了解更多信息。
--experimentalDecorators[1]	boolean	false	实验性启用ES7装饰器支持。
--forceConsistentCasingInFileNames	boolean	false	不允许不一致包装引用相同的文件。
--help -h			打印帮助信息。
--inlineSourceMap	boolean	false	生成单个sourcemaps文件，而不是将每sourcemaps生成不同的文件。
--inlineSources	boolean	false	将代码与sourcemaps生成到一个文件中，要求同时设置了--inlineSourceMap或--sourceMap属性。
--init			初始化TypeScript项目并创建一个tsconfig.json文件。
--isolatedModules	boolean	false	无条件地给没有解析的文件生成imports。
--jsx	string	"Preserve"	在'.tsx'文件里支持JSX：'React' 或 'Preserve'。查看JSX。
--lib	string[]		编译过程中需要引入的库文件的列表。 可能的值为：  ► es5  ► es6  ► es2015  ► es7  ► es2016  ► es2017 dom webworker scripthost  ► es2015.core  ► es2015.collection  ► es2015.generator  ► es2015.iterable  ► es2015.promise  ► es2015.proxy  ► es2015.reflect  ► es2015.symbol  ► es2015.symbol.wellknown  ► es2016.array.include  ► es2017.object  ► es2017.sharedmemory  注意：如果--lib没有指定默认库。默认库是 ► For --target ES5: dom,es5,scripthost ► For --target ES6: dom,es6,dom.iterable,scripthost
--listEmittedFiles	boolean	false	打印出编译后生成文件的名字。
--listFiles	boolean	false	编译过程中打印文件名。
--locale	string	(platform specific)	显示错误信息时使用的语言，比如：en-us。
--mapRoot	string		为调试器指定指定sourcemap文件的路径，而不是使用生成时的路径。当.map文件是在运行时指定的，并不同于js文件的地址时使用这个标记。指定的路径会嵌入到sourceMap里告诉调试器到哪里去找它们。
--maxNodeModuleJsDepth	number	0	node_modules下的最大依赖深度搜索并加载JavaScript文件。仅适用于使用--allowJs。
--module -m	string	target === 'ES6' ? 'ES6' : 'commonjs'	指定生成哪个模块系统代码：'commonjs'，'amd'，'system'，或 'umd'或'es2015'。只有'amd'和'system'能和--outFile一起使用。当目标是ES5或以下的时候不能使用'es2015'。
--moduleResolution	string	module === 'amd' | 'system' | 'ES6' ? 'classic' : 'node'	决定如何处理模块。或者是'node'对于Node.js/io.js，或者是'classic'（默认）。查看模块解析文档了解详情。
--newLine	string	(platform specific)	当生成文件时指定行结束符：'CRLF'（dos）或 'LF' （unix）。
--noEmit	boolean	false	不生成输出文件。
--noEmitHelpers	boolean	false	不在输出文件中生成用户自定义的帮助函数代码，如__extends。
--noEmitOnError	boolean	false	报错时不生成输出文件。
--noFallthroughCasesInSwitch	boolean	false	报告switch语句的fallthrough错误。（即，不允许switch的case语句贯穿）
--noImplicitAny	boolean	false	在表达式和声明上有隐含的'any'类型时报错。
--noImplicitReturns	boolean	false	不是函数的所有返回路径都有返回值时报错。
--noImplicitThis	boolean	false	当this表达式的值为any类型的时候，生成一个错误。
--noImplicitUseStrict	boolean	false	模块输出中不包含'use strict'指令。
--noLib	boolean	false	不包含默认的库文件（lib.d.ts）。
--noResolve	boolean	false	不把/// <reference``>或模块导入的文件加到编译文件列表。
--noUnusedLocals	boolean	false	若有未使用的局部变量则抛错。
--noUnusedParameters	boolean	false	若有未使用的参数则抛错。
--out	string		弃用。使用 --outFile 代替。
--outDir	string		重定向输出目录。
--outFile	string		将输出文件合并为一个文件。合并的顺序是根据传入编译器的文件顺序和///<reference``>和import的文件顺序决定的。查看输出文件顺序文件了解详情。
paths[2]	Object		模块名到基于baseUrl的路径映射的列表。查看模块解析文档了解详情。
--preserveConstEnums	boolean	false	保留const和enum声明。查看const enums documentation了解详情。
--pretty[1]	boolean	false	给错误和消息设置样式，使用颜色和上下文。
--project -p	string		编译指定目录下的项目。这个目录应该包含一个tsconfig.json文件来管理编译。查看tsconfig.json文档了解更多信息。
--reactNamespace	string	"React"	当目标为生成'react' JSX时，指定createElement和__spread的调用对象
--removeComments	boolean	false	删除所有注释，除了以/!*开头的版权信息。
--rootDir	string	(common root directory is computed from the list of input files)	仅用来控制输出的目录结构--outDir。
rootDirs[2]	string[]		根（root）文件夹列表，联给了代表运行时表示工程结构的内容。查看模块解析文档了解详情。
--skipLibCheck	boolean	false	不检查默认库文件（lib.d.ts）的正确性。
--skipDefaultLibCheck	boolean	false	不检查用户定义的库文件（*.d.ts）的正确性。
--sourceMap	boolean	false	生成相应的'.map'文件。
--sourceRoot	string		指定TypeScript源文件的路径，以便调试器定位。当TypeScript文件的位置是在运行时指定时使用此标记。路径信息会被加到sourceMap里。
--strictNullChecks	boolean	false	在严格的null检查模式下，null和undefined值不包含在任何类型里，只允许用它们自己和any来赋值（有个例外，undefined可以赋值到void）。
--stripInternal[1]	boolean	false	不对具有/** @internal */ JSDoc注解的代码生成代码。
--suppressExcessPropertyErrors[1]	boolean	false	阻止对对象字面量的额外属性检查。
--suppressImplicitAnyIndexErrors	boolean	false	阻止--noImplicitAny对缺少索引签名的索引对象报错。查看issue #1232了解详情。
--target -t	string	"ES5"	指定ECMAScript目标版本'ES3' (默认)，'ES5'，或'ES6'[1]
--traceResolution	boolean	false	生成模块解析日志信息
--types	string[]		要包含的类型声明文件名列表。
--typeRoots	string[]		要包含的类型声明文件路径列表。
--version -v			打印编译器版本号。
--watch -w			在监视模式下运行编译器。会监视输出文件，在它们改变时重新编译。

• [1] 这些选项是试验性的。
• [2] 这些选项只能在tsconfig.json里使用，不能在命令行使用。

TypeScript MSBuild编译选项

概述

编译选项可以在使用MSBuild的项目里通过MSBuild属性指定。

例子

<PropertyGroup Condition="'$(Configuration)' == 'Debug'">
  <TypeScriptRemoveComments>false</TypeScriptRemoveComments>
  <TypeScriptSourceMap>true</TypeScriptSourceMap>
</PropertyGroup>
<PropertyGroup Condition="'$(Configuration)' == 'Release'">
  <TypeScriptRemoveComments>true</TypeScriptRemoveComments>
  <TypeScriptSourceMap>false</TypeScriptSourceMap>
</PropertyGroup>
<Import Project="$(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v$(VisualStudioVersion)\TypeScript\Microsoft.TypeScript.targets"
        Condition="Exists('$(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v$(VisualStudioVersion)\TypeScript\Microsoft.TypeScript.targets')" />

映射

编译选项	MSBuild属性名称	可用值
--declaration	TypeScriptGeneratesDeclarations	布尔值
--module	TypeScriptModuleKind	AMD, CommonJs, UMD 或 System
--target	TypeScriptTarget	ES3, ES5, or ES6
--charset	TypeScriptCharset
--emitBOM	TypeScriptEmitBOM	布尔值
--emitDecoratorMetadata	TypeScriptEmitDecoratorMetadata	布尔值
--experimentalDecorators	TypeScriptExperimentalDecorators	布尔值
--inlineSourceMap	TypeScriptInlineSourceMap	布尔值
--inlineSources	TypeScriptInlineSources	布尔值
--locale	自动的	自动设置成PreferredUILang的值
--mapRoot	TypeScriptMapRoot	文件路径
--newLine	TypeScriptNewLine	CRLF 或 LF
--noEmitOnError	TypeScriptNoEmitOnError	布尔值
--noEmitHelpers	TypeScriptNoEmitHelpers	布尔值
--noImplicitAny	TypeScriptNoImplicitAny	布尔值
--noUnusedLocals	TypeScriptNoUnusedLocals	布尔值
--noUnusedParameters	TypeScriptNoUnusedParameters	布尔值
--noLib	TypeScriptNoLib	布尔值
--noResolve	TypeScriptNoResolve	布尔值
--out	TypeScriptOutFile	文件路径
--outDir	TypeScriptOutDir	文件路径
--preserveConstEnums	TypeScriptPreserveConstEnums	布尔值
--removeComments	TypeScriptRemoveComments	布尔值
--rootDir	TypeScriptRootDir	文件路径
--isolatedModules	TypeScriptIsolatedModules	布尔值
--sourceMap	TypeScriptSourceMap	文件路径
--sourceRoot	TypeScriptSourceRoot	文件路径
--strictNullChecks	TypeScriptStrictNullChecks	布尔值
--suppressImplicitAnyIndexErrors	TypeScriptSuppressImplicitAnyIndexErrors	布尔值
--suppressExcessPropertyErrors	TypeScriptSuppressExcessPropertyErrors	布尔值
--moduleResolution	TypeScriptModuleResolution	Classic or Node
--experimentalAsyncFunctions	TypeScriptExperimentalAsyncFunctions	布尔值
--jsx	TypeScriptJSXEmit	React or Preserve
--reactNamespace	TypeScriptReactNamespace	string
--skipDefaultLibCheck	TypeScriptSkipDefaultLibCheck	布尔值
--allowUnusedLabels	TypeScriptAllowUnusedLabels	布尔值
--noImplicitReturns	TypeScriptNoImplicitReturns	布尔值
--noFallthroughCasesInSwitch	TypeScriptNoFallthroughCasesInSwitch	布尔值
--allowUnreachableCode	TypeScriptAllowUnreachableCode	布尔值
--forceConsistentCasingInFileNames	TypeScriptForceConsistentCasingInFileNames	布尔值
--allowSyntheticDefaultImports	TypeScriptAllowSyntheticDefaultImports	布尔值
--noImplicitUseStrict	TypeScriptNoImplicitUseStrict	布尔值
--project	VS不支持
--watch	VS不支持
--diagnostics	VS不支持
--listFiles	VS不支持
--noEmit	VS不支持
--allowJs	VS不支持
VS特有选项	TypeScriptAdditionalFlags	任意编译选项

我使用的Visual Studio版本里支持哪些选项?

查找 C:\Program Files (x86)\MSBuild\Microsoft\VisualStudio\v$(VisualStudioVersion)\TypeScript\Microsoft.TypeScript.targets文件。 可用的MSBuild XML标签与相应的tsc编译选项的映射都在那里。

ToolsVersion

工程文件里的<TypeScriptToolsVersion>1.7</TypeScriptToolsVersion>属性值表明了构建时使用的编译器的版本号（这个例子里是1.7） 这样就允许一个工程在不同的机器上使用固定的版本去编译。

如果没有指定TypeScriptToolsVersion，则会使用机器上安装的最新版本的编译器去构建。

如果用户使用的是更新版本的TypeScript，则会在首次加载工程的时候看到一个提示升级工程的对话框。

TypeScriptCompileBlocked

如果你使用其它的构建工具（比如，gulp， grunt等等）并且使用VS做为开发和调试工具，那么在工程里设置<TypeScriptCompileBlocked>true</TypeScriptCompileBlocked>。 这样VS只会提供给你编辑的功能，而不会在你按F5的时候去构建。

TypeScript 构建工具整合

与其它构建工具整合

Browserify

安装

npm install tsify

使用命令行交互

browserify main.ts -p [ tsify --noImplicitAny ] > bundle.js

使用API

var browserify = require("browserify");
var tsify = require("tsify");

browserify()
    .add('main.ts')
    .plugin('tsify', { noImplicitAny: true })
    .bundle()
    .pipe(process.stdout);

Duo

安装

npm install duo-typescript

使用命令行交互

duo --use duo-typescript entry.ts

使用API

var Duo = require('duo');
var fs = require('fs')
var path = require('path')
var typescript = require('duo-typescript');

var out = path.join(__dirname, "output.js")

Duo(__dirname)
    .entry('entry.ts')
    .use(typescript())
    .run(function (err, results) {
        if (err) throw err;
        // Write compiled result to output file
        fs.writeFileSync(out, results.code);
    });

Grunt

安装

npm install grunt-ts

基本Gruntfile.js

module.exports = function(grunt) {
    grunt.initConfig({
        ts: {
            default : {
                src: ["**/*.ts", "!node_modules/**/*.ts"]
            }
        }
    });
    grunt.loadNpmTasks("grunt-ts");
    grunt.registerTask("default", ["ts"]);
};

gulp

安装

npm install gulp-typescript

基本gulpfile.js

var gulp = require("gulp");
var ts = require("gulp-typescript");

gulp.task("default", function () {
    var tsResult = gulp.src("src/*.ts")
        .pipe(ts({
              noImplicitAny: true,
              out: "output.js"
        }));
    return tsResult.js.pipe(gulp.dest('built/local'));
});

jspm

安装

npm install -g jspm@beta

注意：目前jspm的0.16beta版本支持TypeScript

webpack

安装

npm install ts-loader --save-dev

基本webpack.config.js

module.exports = {
    entry: "./src/index.tsx",
    output: {
        filename: "bundle.js"
    },
    resolve: {
        // Add '.ts' and '.tsx' as a resolvable extension.
        extensions: ["", ".webpack.js", ".web.js", ".ts", ".tsx", ".js"]
    },
    module: {
        loaders: [
            // all files with a '.ts' or '.tsx' extension will be handled by 'ts-loader'
            { test: /\.tsx?$/, loader: "ts-loader" }
        ]
    }
};

查看更多关于ts-loader的详细信息

或者

• awesome-typescript-loader

MSBuild

更新工程文件，包含本地安装的Microsoft.TypeScript.Default.props（在顶端）和Microsoft.TypeScript.targets（在底部）文件：

<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="4.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <!-- Include default props at the bottom -->
  <Import
      Project="$(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v$(VisualStudioVersion)\TypeScript\Microsoft.TypeScript.Default.props"
      Condition="Exists('$(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v$(VisualStudioVersion)\TypeScript\Microsoft.TypeScript.Default.props')" />

  <!-- TypeScript configurations go here -->
  <PropertyGroup Condition="'$(Configuration)' == 'Debug'">
    <TypeScriptRemoveComments>false</TypeScriptRemoveComments>
    <TypeScriptSourceMap>true</TypeScriptSourceMap>
  </PropertyGroup>
  <PropertyGroup Condition="'$(Configuration)' == 'Release'">
    <TypeScriptRemoveComments>true</TypeScriptRemoveComments>
    <TypeScriptSourceMap>false</TypeScriptSourceMap>
  </PropertyGroup>

  <!-- Include default targets at the bottom -->
  <Import
      Project="$(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v$(VisualStudioVersion)\TypeScript\Microsoft.TypeScript.targets"
      Condition="Exists('$(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v$(VisualStudioVersion)\TypeScript\Microsoft.TypeScript.targets')" />
</Project>

关于配置MSBuild编译器选项的更多详细信息，请参考：[在MSBuild里使用编译选项](./Compiler Options in MSBuild.md)

NuGet

• 右键点击 -> Manage NuGet Packages
• 查找Microsoft.TypeScript.MSBuild
• 点击Install
• 安装完成后，Rebuild。

TypeScript 每日构建

在太平洋标准时间每天午夜会自动构建TypeScript的master 分支代码并发布到NPM和NuGet上。下面将介绍如何获得并在工具里使用它们。

使用npm

npm install -g typescript@next

使用NuGet和MSBuild

注意：你需要配置工程来使用NuGet包。

有两个包：

• Microsoft.TypeScript.Compiler：仅包含工具（tsc.exe，lib.d.ts ，等。）。
• Microsoft.TypeScript.MSBuild：和上面一样的工具，还有的MSBuild的任务和目标（Microsoft.TypeScript.targets， Microsoft.TypeScript.Default.props 。，等）

更新IDE来使用每日构建

你还可以配置IDE来使用每日构建。首先你要通过npm安装包。你可以进行全局安装或者安装到本地的node_modules目录下。

下面的步骤里我们假设你已经安装好了typescript@next。

Visual Studio代码

更新.vscode/settings.json如下：

"typescript.tsdk": "<path to your folder>/node_modules/typescript/lib"

详细信息参见VSCode文档 。

崇高文本

更新Settings - User如下：

"typescript_tsdk": "<path to your folder>/node_modules/typescript/lib"

Visual Studio 2013和2015

注意：大多数的改变不需要你安装新版本的VS TypeScript插件。

当前的每日构建不包含完整的插件安装包，但是我们正在试着提供每日构建的安装包。

1. 在PowerShell命令行窗口里执行：

VS 2015：

VSDevMode.ps1 14 -tsScript <path to your folder>/node_modules/typescrip

VS 2013：

VSDevMode.ps1 12 -tsScript <path to your folder>/node_modules/typescript/lib

IntelliJ IDEA (Mac)

前往Preferences > Languages & Frameworks > TypeScript：

TypeScript Version: 如果通过NPM安装：/usr/local/lib/node_modules/typescript/lib