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