TypeScript：文档 - MSBuild 中的编译器选项

概述

当您使用基于 MSBuild 的项目（如 ASP.NET Core 项目）并运用 TypeScript 时，有两种配置 TypeScript 的方式：通过 tsconfig.json 或通过项目设置。

使用 `tsconfig.json`

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

此后，新的 tsconfig.json 将被用作 TypeScript 特定构建信息（如文件和配置）的权威来源。您可以在此了解 TSConfig 的工作原理，这里还有一个完整的参考指南。

使用项目设置

您也可以在项目设置中定义 TypeScript 的配置。这可以通过编辑 .csproj 中的 XML 来定义 PropertyGroups 实现，这些属性组描述了构建如何进行。

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

有一系列针对常见 TypeScript 设置的映射，这些设置直接映射到 TypeScript 命令行选项，并用于帮助您编写更易于理解的项目文件。您可以使用 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 的语言版本，并包含兼容的库声明。
`<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 stage 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

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

MSBuild 中的编译器选项

概述

使用 tsconfig.json