MSBuild 中的編譯器選項

概觀

當您有一個基於 MSBuild 的專案，它使用 TypeScript，例如 ASP.NET Core 專案，您可以透過兩種方式來設定 TypeScript。透過 tsconfig.json 或專案設定。

使用 tsconfig.json

我們建議在可能的情況下，為您的專案使用 tsconfig.json。若要將它新增到現有專案，請在您的專案中新增一個新項目，在最新版本的 Visual Studio 中稱為「TypeScript JSON 設定檔」。

新的 tsconfig.json 然後將用作 TypeScript 特定建置資訊（例如檔案和設定）的真實來源。您可以 在此處瞭解 TSConfigs 的運作方式，並且 在此處有一個全面的參考。

使用專案設定

您也可以在專案設定中定義 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
停用將符號連結解析為其真實路徑。這與節點中的相同標記相關。
<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 編譯器。