# MSBuild 中的编译器选项
# 概述
如果你有一个基于 MSBuild 的项目，它使用了 TypeScript，例如 ASP.NET Core 项目，你可以通过两种方式配置 TypeScript。通过 tsconfig.json或通过项目设置。
# 使用 tsconfig.json
我们建议尽可能为您的项目使用 tsconfig.json。要将一个项目添加到现有项目，请在项目中添加一个新项目，在现代版本的 Visual Studio 中称为 "TypeScript JSON Configuration File"。
然后，新的 tsconfig.json将用作特定于 TypeScript 的构建信息（如文件和配置）的真实来源。可以学关于 TSConfigs 如何在这里工作 ，有综合参考这里。
# 使用项目设置
您还可以在项目的设置中定义 TypeScript 的配置。这是通过编辑 .csproj中的 XML 来定义 PropertyGroups来完成的，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 |
| 禁止 imports、requires 或 <reference>s 扩展 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 中包含 sourcemap 文件。 | |
| <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 ：
<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 编译器。