概述
¥Overview
如果你有一个基于 MSBuild 的项目,它使用了 TypeScript,例如 ASP.NET Core 项目,你可以通过两种方式配置 TypeScript。通过 tsconfig.json
或通过项目设置。
¥When you have an MSBuild based project which utilizes TypeScript such as an ASP.NET Core project, you can configure TypeScript in two ways. Either via a tsconfig.json
or via the project settings.
使用 tsconfig.json
¥Using a tsconfig.json
我们建议尽可能为你的项目使用 tsconfig.json
。要将一个项目添加到现有项目,请在项目中添加一个新项目,在现代版本的 Visual Studio 中称为 “TypeScript JSON 配置文件”。
¥We recommend using a tsconfig.json
for your project when possible. To add one to an existing project, add a new item to your project which is called a “TypeScript JSON Configuration File” in modern versions of Visual Studio.
然后,新的 tsconfig.json
将用作特定于 TypeScript 的构建信息(如文件和配置)的真实来源。可以学习 关于 TSConfigs 如何工作,还有 综合参考手册。
¥The new tsconfig.json
will then be used as the source of truth for TypeScript-specific build information like files and configuration. You can learn about how TSConfigs works here and there is a comprehensive reference here.
使用项目设置
¥Using Project Settings
你还可以在项目的设置中定义 TypeScript 的配置。这是通过编辑 .csproj
中的 XML 来定义 PropertyGroups
来完成的,PropertyGroups
描述了构建如何工作:
¥You can also define the configuration for TypeScript inside you project’s settings. This is done by editing the XML in your .csproj
to define PropertyGroups
which describe how the build can work:
xml
<PropertyGroup><TypeScriptNoEmitOnError>true</TypeScriptNoEmitOnError><TypeScriptNoImplicitReturns>true</TypeScriptNoImplicitReturns></PropertyGroup>
常见的 TypeScript 设置有一系列映射,这些设置直接映射到 TypeScript cli 选项,用于帮助你编写更易于理解的项目文件。你可以使用 TSConfig 参考手册 获取有关每个映射的值和默认值的更多信息。
¥There is a series of mappings for common TypeScript settings, these are settings which map directly to TypeScript cli options and are used to help you write a more understandable project file. You can use the TSConfig reference to get more information on what values and defaults are for each mapping.
CLI 映射
MSBuild 配置名称 | TSC 标志 | |
---|---|---|
<TypeScriptAllowJS> |
--allowJs |
|
允许 JavaScript 文件成为程序的一部分。使用 | ||
<TypeScriptRemoveComments> |
--removeComments |
|
禁用触发注释。 | ||
<TypeScriptNoImplicitAny> |
--noImplicitAny |
|
为具有隐含 | ||
<TypeScriptGeneratesDeclarations> |
--declaration |
|
从项目中的 TypeScript 和 JavaScript 文件生成 .d.ts 文件。 | ||
<TypeScriptModuleKind> |
--module |
|
指定生成什么模块代码。 | ||
<TypeScriptJSXEmit> |
--jsx |
|
指定生成的 JSX 代码。 | ||
<TypeScriptOutDir> |
--outDir |
|
为所有触发的文件指定一个输出文件夹。 | ||
<TypeScriptSourceMap> |
--sourcemap |
|
为触发的 JavaScript 文件创建源映射文件。 | ||
<TypeScriptTarget> |
--target |
|
为触发的 JavaScript 设置 JavaScript 语言版本并包含兼容的库声明。 | ||
<TypeScriptNoResolve> |
--noResolve |
|
禁止 | ||
<TypeScriptMapRoot> |
--mapRoot |
|
指定调试器应该定位映射文件而不是生成的位置的位置。 | ||
<TypeScriptSourceRoot> |
--sourceRoot |
|
指定调试器查找参考源代码的根路径。 | ||
<TypeScriptCharset> |
--charset |
|
不再支持。在早期版本中,手动设置读取文件的文本编码。 | ||
<TypeScriptEmitBOM> |
--emitBOM |
|
在输出文件的开头触发一个 UTF-8 字节顺序标记 (BOM)。 | ||
<TypeScriptNoLib> |
--noLib |
|
禁用包含任何库文件,包括默认的 lib.d.ts。 | ||
<TypeScriptPreserveConstEnums> |
--preserveConstEnums |
|
禁止擦除生成代码中的 | ||
<TypeScriptSuppressImplicitAnyIndexErrors> |
--suppressImplicitAnyIndexErrors |
|
对缺少索引签名的对象建立索引时抑制 | ||
<TypeScriptNoEmitHelpers> |
--noEmitHelpers |
|
禁用在编译输出中生成自定义辅助函数(例如 | ||
<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 |
|
指定为 | ||
<TypeScriptSkipDefaultLibCheck> |
--skipDefaultLibCheck |
|
跳过 TypeScript 中包含的类型检查 .d.ts 文件。 | ||
<TypeScriptAllowUnusedLabels> |
--allowUnusedLabels |
|
禁用未使用标签的错误报告。 | ||
<TypeScriptNoImplicitReturns> |
--noImplicitReturns |
|
为未在函数中显式返回的代码路径启用错误报告。 | ||
<TypeScriptNoFallthroughCasesInSwitch> |
--noFallthroughCasesInSwitch |
|
在 switch 语句中启用失败案例的错误报告。 | ||
<TypeScriptAllowUnreachableCode> |
--allowUnreachableCode |
|
禁用无法访问代码的错误报告。 | ||
<TypeScriptForceConsistentCasingInFileNames> |
--forceConsistentCasingInFileNames |
|
确保导入中的大小写正确。 | ||
<TypeScriptAllowSyntheticDefaultImports> |
--allowSyntheticDefaultImports |
|
当模块没有默认导出时允许 '从 y 导入 x'。 | ||
<TypeScriptNoImplicitUseStrict> |
--noImplicitUseStrict |
|
禁止在触发的 JavaScript 文件中添加 '使用严格' 指令。 | ||
<TypeScriptLib> |
--lib |
|
指定一组描述目标运行时环境的打包库声明文件。 | ||
<TypeScriptBaseUrl> |
--baseUrl |
|
指定基本目录来解析裸说明符模块名称。 | ||
<TypeScriptDeclarationDir> |
--declarationDir |
|
指定生成的声明文件的输出目录。 | ||
<TypeScriptNoImplicitThis> |
--noImplicitThis |
|
当 | ||
<TypeScriptSkipLibCheck> |
--skipLibCheck |
|
跳过类型检查所有 .d.ts 文件。 | ||
<TypeScriptStrictNullChecks> |
--strictNullChecks |
|
类型检查时,考虑 | ||
<TypeScriptNoUnusedLocals> |
--noUnusedLocals |
|
当未读取局部变量时启用错误报告。 | ||
<TypeScriptNoUnusedParameters> |
--noUnusedParameters |
|
未读取函数参数时引发错误 | ||
<TypeScriptAlwaysStrict> |
--alwaysStrict |
|
确保始终触发 '使用严格'。 | ||
<TypeScriptImportHelpers> |
--importHelpers |
|
允许每个项目从 tslib 导入帮助函数一次,而不是在每个文件中包含它们。 | ||
<TypeScriptJSXFactory> |
--jsxFactory |
|
指定在针对 React JSX 触发时使用的 JSX 工厂函数,例如 'React.createElement' 或 'h' | ||
<TypeScriptStripInternal> |
--stripInternal |
|
禁用触发 JSDoc 注释中包含 | ||
<TypeScriptCheckJs> |
--checkJs |
|
在类型检查的 JavaScript 文件中启用错误报告。 | ||
<TypeScriptDownlevelIteration> |
--downlevelIteration |
|
为迭代触发更合规但冗长且性能更低的 JavaScript。 | ||
<TypeScriptStrict> |
--strict |
|
启用所有严格类型检查选项。 | ||
<TypeScriptNoStrictGenericChecks> |
--noStrictGenericChecks |
|
禁用对函数类型中的泛型签名的严格检查。 | ||
<TypeScriptPreserveSymlinks> |
--preserveSymlinks |
|
禁用解析符号链接到他们的真实路径。这与 node 中的相同标志相关。 | ||
<TypeScriptStrictFunctionTypes> |
--strictFunctionTypes |
|
分配函数时,检查以确保参数和返回值是子类型兼容的。 | ||
<TypeScriptStrictPropertyInitialization> |
--strictPropertyInitialization |
|
检查已声明但未在构造函数中设置的类属性。 | ||
<TypeScriptESModuleInterop> |
--esModuleInterop |
|
触发额外的 JavaScript 以简化对导入 CommonJS 模块的支持。这使得 | ||
<TypeScriptEmitDeclarationOnly> |
--emitDeclarationOnly |
|
只输出 d.ts 文件,不输出 JavaScript 文件。 | ||
<TypeScriptKeyofStringsOnly> |
--keyofStringsOnly |
|
使 keyof 只返回字符串而不是字符串、数字或符号。旧版选项。 | ||
<TypeScriptUseDefineForClassFields> |
--useDefineForClassFields |
|
触发符合 ECMAScript 标准的类字段。 | ||
<TypeScriptDeclarationMap> |
--declarationMap |
|
为 d.ts 文件创建源映射。 | ||
<TypeScriptResolveJsonModule> |
--resolveJsonModule |
|
启用导入 .json 文件 | ||
<TypeScriptStrictBindCallApply> |
--strictBindCallApply |
|
检查 | ||
<TypeScriptNoEmitOnError> |
--noEmitOnError |
|
如果报告任何类型检查错误,则禁用触发文件。 |
附加标志
¥Additional Flags
因为 MSBuild 系统将参数直接传递给 TypeScript CLI,所以你可以使用选项 TypeScriptAdditionalFlags
来提供没有上述映射的特定标志。
¥Because the MSBuild system passes arguments directly to the TypeScript CLI, you can use the option TypeScriptAdditionalFlags
to provide specific flags which don’t have a mapping above.
例如,这将打开 noPropertyAccessFromIndexSignature
:
¥For example, this would turn on noPropertyAccessFromIndexSignature
:
xml
<TypeScriptAdditionalFlags> $(TypeScriptAdditionalFlags) --noPropertyAccessFromIndexSignature</TypeScriptAdditionalFlags>
调试和发布版本
¥Debug and Release Builds
你可以使用 PropertyGroup 条件来定义不同的配置集。例如,一个常见的任务是在生产中剥离注释和源映射。在此示例中,我们定义了一个具有不同 TypeScript 配置的调试和发布属性组:
¥You can use PropertyGroup conditions to define different sets of configurations. For example, a common task is stripping comments and sourcemaps in production. In this example, we define a debug and release property group which have different TypeScript configurations:
xml
<PropertyGroup Condition="'$(Configuration)' == 'Debug'"><TypeScriptRemoveComments>false</TypeScriptRemoveComments><TypeScriptSourceMap>true</TypeScriptSourceMap></PropertyGroup><PropertyGroup Condition="'$(Configuration)' == 'Release'"><TypeScriptRemoveComments>true</TypeScriptRemoveComments><TypeScriptSourceMap>false</TypeScriptSourceMap></PropertyGroup><ImportProject="$(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)。这允许项目在不同机器上针对相同版本的编译器进行构建。
¥The value of <TypeScriptToolsVersion>1.7</TypeScriptToolsVersion>
property in the project file identifies the compiler version to use to build (1.7 in this example).
This allows a project to build against the same versions of the compiler on different machines.
如果不指定 TypeScriptToolsVersion
,将使用机器上安装的最新编译器版本进行构建。
¥If TypeScriptToolsVersion
is not specified, the latest compiler version installed on the machine will be used to build.
使用较新版本 TS 的用户将在首次加载时看到升级项目的提示。
¥Users using newer versions of TS, will see a prompt to upgrade their project on first load.
TypeScriptCompileBlocked
如果你使用不同的构建工具来构建你的项目(例如 gulp、grunt 等)和 VS 以获得开发和调试体验,请在你的项目中设置 <TypeScriptCompileBlocked>true</TypeScriptCompileBlocked>
。这应该为你提供所有的编辑支持,但在你按下 F5 时不会为你提供构建支持。
¥If you are using a different build tool to build your project (e.g. gulp, grunt , etc.) and VS for the development and debugging experience, set <TypeScriptCompileBlocked>true</TypeScriptCompileBlocked>
in your project.
This should give you all the editing support, but not the build when you hit F5.
TypeScriptEnableIncrementalMSBuild(TypeScript 4.2 Beta 及更高版本)
¥TypeScriptEnableIncrementalMSBuild (TypeScript 4.2 Beta and later)
默认情况下,MSBuild 将尝试仅在自上次编译后更新项目的源文件时才运行 TypeScript 编译器。但是,如果此行为导致问题,例如启用 TypeScript 的 incremental
选项,请设置 <TypeScriptEnableIncrementalMSBuild>false</TypeScriptEnableIncrementalMSBuild>
以确保每次运行 MSBuild 都会调用 TypeScript 编译器。
¥By default, MSBuild will attempt to only run the TypeScript compiler when the project’s source files have been updated since the last compilation.
However, if this behavior is causing issues, such as when TypeScript’s incremental
option is enabled, set <TypeScriptEnableIncrementalMSBuild>false</TypeScriptEnableIncrementalMSBuild>
to ensure the TypeScript compiler is invoked with every run of MSBuild.