MSBuild 中的编译器选项

概述

当你有一个基于 MSBuild 的项目（例如 ASP.NET Core 项目）使用 TypeScript 时，你可以通过两种方式配置 TypeScript。要么通过 tsconfig.json，要么通过项目设置。

使用 tsconfig.json

我们建议尽可能在项目中使用 tsconfig.json。要将它添加到现有项目中，请在较新版本的 Visual Studio 中向项目添加一个名为“TypeScript JSON 配置文件”的新项。

新的 tsconfig.json 随后将用作 TypeScript 特定构建信息（如文件和配置）的权威来源。你可以在此处了解 TSConfig 的工作原理，并且此处有全面的参考。

使用项目设置

你也可以在项目设置内部定义 TypeScript 的配置。这是通过编辑 .csproj 中的 XML 来定义 PropertyGroups 来实现的，这些组描述了构建的工作方式：

<PropertyGroup>
  <TypeScriptNoEmitOnError>true</TypeScriptNoEmitOnError>
  <TypeScriptNoImplicitReturns>true</TypeScriptNoImplicitReturns>
</PropertyGroup>

有一系列常见 TypeScript 设置的映射，这些设置直接映射到 TypeScript cli 选项，用于帮助你编写更易理解的项目文件。你可以使用 TSConfig 参考 来获取有关每个映射的值和默认值的更多信息。

CLI 映射

MSBuild 配置名称	TSC 标志
<TypeScriptAllowJS>	--allowJs
允许 JavaScript 文件成为程序的一部分。使用 checkJS 选项从这些文件中获取错误。
<TypeScriptRemoveComments>	--removeComments
禁止输出注释。
<TypeScriptNoImplicitAny>	--noImplicitAny
对带有隐含 any 类型的表达式和声明启用错误报告。
<TypeScriptGeneratesDeclarations>	--declaration
从项目中的 TypeScript 和 JavaScript 文件生成 .d.ts 文件。
<TypeScriptModuleKind>	--module
指定生成的模块代码。
<TypeScriptJSXEmit>	--jsx
指定生成的 JSX 代码。
<TypeScriptOutDir>	--outDir
指定所有输出文件的输出文件夹。
<TypeScriptSourceMap>	--sourcemap
为输出的 JavaScript 文件创建源映射文件。
<TypeScriptTarget>	--target
设置输出 JavaScript 的 JavaScript 语言版本，并包含兼容的库声明。
<TypeScriptNoResolve>	--noResolve
禁止 import、require 或 <reference> 扩展 TypeScript 应添加到项目的文件数量。
<TypeScriptMapRoot>	--mapRoot
指定调试器定位映射文件的位置，而不是生成的位置。
<TypeScriptSourceRoot>	--sourceRoot
指定调试器查找引用源代码的根路径。
<TypeScriptCharset>	--charset
不再支持。在早期版本中，手动设置读取文件的文本编码。
<TypeScriptEmitBOM>	--emitBOM
在输出文件的开头输出 UTF-8 字节顺序标记（BOM）。
<TypeScriptNoLib>	--noLib
禁用包含任何库文件，包括默认的 lib.d.ts。
<TypeScriptPreserveConstEnums>	--preserveConstEnums
禁止在生成的代码中擦除 const enum 声明。
<TypeScriptSuppressImplicitAnyIndexErrors>	--suppressImplicitAnyIndexErrors
在索引缺少索引签名的对象时，抑制 noImplicitAny 错误。
<TypeScriptNoEmitHelpers>	--noEmitHelpers
禁止在编译输出中生成像 __extends 这样的自定义辅助函数。
<TypeScriptInlineSourceMap>	--inlineSourceMap
在输出的 JavaScript 中包含源映射文件。
<TypeScriptInlineSources>	--inlineSources
在输出的 JavaScript 的源映射中包含源代码。
<TypeScriptNewLine>	--newLine
设置输出文件的换行符。
<TypeScriptIsolatedModules>	--isolatedModules
确保每个文件可以安全地转译，而无需依赖其他导入。
<TypeScriptEmitDecoratorMetadata>	--emitDecoratorMetadata
为源文件中带有装饰器的声明输出设计时类型元数据。
<TypeScriptRootDir>	--rootDir
指定源文件中的根文件夹。
<TypeScriptExperimentalDecorators>	--experimentalDecorators
启用对 TC39 第 2 阶段草案装饰器的实验性支持。
<TypeScriptModuleResolution>	--moduleResolution
指定 TypeScript 如何根据给定的模块说明符查找文件。
<TypeScriptSuppressExcessPropertyErrors>	--suppressExcessPropertyErrors
在创建对象字面量期间禁止报告多余属性错误。
<TypeScriptReactNamespace>	--reactNamespace
指定为 createElement 调用的对象。这仅适用于目标为 react JSX 输出时。
<TypeScriptSkipDefaultLibCheck>	--skipDefaultLibCheck
跳过 TypeScript 附带的 .d.ts 文件的类型检查。
<TypeScriptAllowUnusedLabels>	--allowUnusedLabels
禁止报告未使用的标签错误。
<TypeScriptNoImplicitReturns>	--noImplicitReturns
对函数中未显式返回的代码路径启用错误报告。
<TypeScriptNoFallthroughCasesInSwitch>	--noFallthroughCasesInSwitch
对 switch 语句中的贯穿 case 启用错误报告。
<TypeScriptAllowUnreachableCode>	--allowUnreachableCode
禁止报告无法访问的代码错误。
<TypeScriptForceConsistentCasingInFileNames>	--forceConsistentCasingInFileNames
确保导入中的大小写正确。
<TypeScriptAllowSyntheticDefaultImports>	--allowSyntheticDefaultImports
当模块没有默认导出时，允许 'import x from y'。
<TypeScriptNoImplicitUseStrict>	--noImplicitUseStrict
禁止在输出的 JavaScript 文件中添加 'use strict' 指令。
<TypeScriptLib>	--lib
指定一组描述目标运行时环境的捆绑库声明文件。
<TypeScriptBaseUrl>	--baseUrl
指定解析裸说明符模块名称的基本目录。
<TypeScriptDeclarationDir>	--declarationDir
指定生成的声明文件的输出目录。
<TypeScriptNoImplicitThis>	--noImplicitThis
当 this 被赋予类型 any 时启用错误报告。
<TypeScriptSkipLibCheck>	--skipLibCheck
跳过所有 .d.ts 文件的类型检查。
<TypeScriptStrictNullChecks>	--strictNullChecks
进行类型检查时，考虑 null 和 undefined。
<TypeScriptNoUnusedLocals>	--noUnusedLocals
当局部变量未被读取时启用错误报告。
<TypeScriptNoUnusedParameters>	--noUnusedParameters
当函数参数未被读取时引发错误。
<TypeScriptAlwaysStrict>	--alwaysStrict
确保始终输出 'use strict'。
<TypeScriptImportHelpers>	--importHelpers
允许从 tslib 每个项目导入一次辅助函数，而不是每个文件都包含它们。
<TypeScriptJSXFactory>	--jsxFactory
指定目标为 React JSX 输出时使用的 JSX 工厂函数，例如 'React.createElement' 或 'h'。
<TypeScriptStripInternal>	--stripInternal
禁止输出在 JSDoc 注释中包含 @internal 的声明。
<TypeScriptCheckJs>	--checkJs
在类型检查的 JavaScript 文件中启用错误报告。
<TypeScriptDownlevelIteration>	--downlevelIteration
输出更符合规范但更冗长且性能较低的迭代 JavaScript。
<TypeScriptStrict>	--strict
启用所有严格类型检查选项。
<TypeScriptNoStrictGenericChecks>	--noStrictGenericChecks
禁用函数类型中泛型签名的严格检查。
<TypeScriptPreserveSymlinks>	--preserveSymlinks
禁止将符号链接解析为其真实路径。这对应于 node 中的相同标志。
<TypeScriptStrictFunctionTypes>	--strictFunctionTypes
分配函数时，检查以确保参数和返回值是子类型兼容的。
<TypeScriptStrictPropertyInitialization>	--strictPropertyInitialization
检查声明但在构造函数中未设置的类属性。
<TypeScriptESModuleInterop>	--esModuleInterop
输出额外的 JavaScript 以简化对导入 CommonJS 模块的支持。这为类型兼容性启用了 allowSyntheticDefaultImports。
<TypeScriptEmitDeclarationOnly>	--emitDeclarationOnly
仅输出 d.ts 文件，不输出 JavaScript 文件。
<TypeScriptKeyofStringsOnly>	--keyofStringsOnly
使 keyof 仅返回字符串，而不是字符串、数字或符号。遗留选项。
<TypeScriptUseDefineForClassFields>	--useDefineForClassFields
输出符合 ECMAScript 标准的类字段。
<TypeScriptDeclarationMap>	--declarationMap
为 d.ts 文件创建源映射。
<TypeScriptResolveJsonModule>	--resolveJsonModule
启用导入 .json 文件。
<TypeScriptStrictBindCallApply>	--strictBindCallApply
检查 bind、call 和 apply 方法的参数是否与原始函数匹配。
<TypeScriptNoEmitOnError>	--noEmitOnError
如果报告任何类型检查错误，则禁止输出文件。

附加标志

由于 MSBuild 系统将参数直接传递给 TypeScript CLI，你可以使用 TypeScriptAdditionalFlags 选项来提供上面没有映射的特定标志。

例如，这可以启用 noPropertyAccessFromIndexSignature：

<TypeScriptAdditionalFlags> $(TypeScriptAdditionalFlags) --noPropertyAccessFromIndexSignature</TypeScriptAdditionalFlags>

调试和发布构建

你可以使用 PropertyGroup 条件来定义不同的配置集。例如，一个常见的任务是在生产环境中剥离注释和源映射。在此示例中，我们定义了一个调试和发布属性组，它们具有不同的 TypeScript 配置：

<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')" />

ToolsVersion

项目文件中的 <TypeScriptToolsVersion>1.7</TypeScriptToolsVersion> 属性值标识了用于构建的编译器版本（此示例中为 1.7）。 这允许项目在不同的机器上针对相同版本的编译器进行构建。

如果未指定 TypeScriptToolsVersion，则将使用计算机上安装的最新编译器版本来构建。

使用较新 TS 版本的用户在首次加载时，会看到升级项目的提示。

TypeScriptCompileBlocked

如果你使用其他构建工具（例如 gulp、grunt 等）来构建项目，并使用 VS 进行开发和调试体验，请在项目中设置 <TypeScriptCompileBlocked>true</TypeScriptCompileBlocked>。 这将为你提供所有编辑支持，但在按 F5 时不会进行构建。

TypeScriptEnableIncrementalMSBuild（TypeScript 4.2 Beta 及更高版本）

默认情况下，MSBuild 将尝试仅在项目的源文件自上次编译以来已更新时才运行 TypeScript 编译器。 但是，如果此行为导致问题，例如当 TypeScript 的 incremental 选项启用时，请设置 <TypeScriptEnableIncrementalMSBuild>false</TypeScriptEnableIncrementalMSBuild> 以确保每次运行 MSBuild 时都调用 TypeScript 编译器。