在MSBuild里使用编译选项 - TypeScript 中文文档

概述

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

使用 `tsconfig.json`

在可能的情况下，我们建议为项目使用 tsconfig.json。若要向现有项目添加一个，请在较新版本的 Visual Studio 中为项目添加一个名为“TypeScript JSON Configuration File”的新项。

随后，新的 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 配置的 property group：调试和发布。

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