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

xml
<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 语句中启用对贯穿情况的错误报告。
<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

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

调试和发布版本

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

xml
<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> 以确保 TypeScript 编译器在每次运行 MSBuild 时都被调用。