轉譯 TypeScript

TypeScript 是 JavaScript 的具型別超集合 (typed superset)，可轉譯為純 JavaScript。它提供類別、模組與介面，能協助您建構強固的元件。

安裝 TypeScript 編譯器

Visual Studio Code 內建 TypeScript 語言支援，但不包含 TypeScript 編譯器 tsc。您需要全域或在工作區中安裝 TypeScript 編譯器，才能將 TypeScript 原始碼轉譯為 JavaScript (tsc HelloWorld.ts)。

安裝 TypeScript 最簡單的方法是透過 npm，即 Node.js 套件管理員。如果您已安裝 npm，可以透過下列指令在電腦上全域 (-g) 安裝 TypeScript：

npm install -g typescript

您可以透過檢查版本或說明來測試安裝是否成功。

tsc --version
tsc --help

另一種選擇是在您的專案中本機安裝 TypeScript 編譯器 (npm install --save-dev typescript)，這樣的好處是可以避免與您可能擁有的其他 TypeScript 專案發生潛在衝突。

編譯器與語言服務的差異

請記住，VS Code 的 TypeScript 語言服務與您安裝的 TypeScript 編譯器是分開的。當您開啟 TypeScript 檔案時，您可以在語言狀態列項目中看到 VS Code 的 TypeScript 版本。

本文稍後將討論如何變更 VS Code 所使用的 TypeScript 語言服務版本。

tsconfig.json

通常任何新 TypeScript 專案的第一個步驟是新增 tsconfig.json 檔案。tsconfig.json 檔案會定義 TypeScript 專案設定，例如編譯器選項以及應包含的檔案。若要這麼做，請開啟要儲存原始程式碼的資料夾，並新增名為 tsconfig.json 的新檔案。一旦進入此檔案中，IntelliSense (⌃Space (Windows, Linux Ctrl+Space)) 將會在過程中協助您。

針對 ES5、CommonJS 模組與原始對應檔，簡單的 tsconfig.json 長這樣：

{
  "compilerOptions": {
    "target": "ES5",
    "module": "CommonJS",
    "sourceMap": true
  }
}

現在，當您建立作為專案一部分的 .ts 檔案時，我們將提供豐富的編輯體驗與語法驗證。

將 TypeScript 轉譯為 JavaScript

VS Code 透過我們的整合式工作執行器與 tsc 整合。我們可以使用它將 .ts 檔案轉譯為 .js 檔案。使用 VS Code 工作的另一個好處是，您可以在問題面板中看到整合的錯誤與警告偵測。讓我們實際走訪轉譯簡單的 TypeScript Hello World 程式。

步驟 1：建立簡單的 TS 檔案

在空資料夾中開啟 VS Code 並建立 helloworld.ts 檔案，將下列程式碼放入該檔案中...

let message: string = 'Hello World';
console.log(message);

為了測試是否已正確安裝 TypeScript 編譯器 tsc 並且 Hello World 程式能正常運作，請開啟終端機並輸入 tsc helloworld.ts。您可以直接在 VS Code 中使用整合式終端機 (⌃` (Windows, Linux Ctrl+`))。

您現在應該會看到轉譯後的 helloworld.js JavaScript 檔案。如果您已安裝 Node.js，可以透過輸入 node helloworld.js 來執行它。

步驟 2：執行 TypeScript 建置

從全域的終端機功能表中執行執行建置工作 (⇧⌘B (Windows, Linux Ctrl+Shift+B))。如果您在前面的章節中建立了 tsconfig.json 檔案，這應該會顯示下列挑選器：

選取 tsc: build 項目。這會在工作區中產生 HelloWorld.js 與 HelloWorld.js.map 檔案。

如果您選取 tsc: watch，TypeScript 編譯器將會監視 TypeScript 檔案的變更，並在每次變更時執行轉譯器。

在幕後，我們會以工作方式執行 TypeScript 編譯器。我們使用的命令是：tsc -p .

步驟 3：將 TypeScript 建置設為預設值

您也可以將 TypeScript 建置工作定義為預設建置工作，如此在觸發執行建置工作 (⇧⌘B (Windows, Linux Ctrl+Shift+B)) 時便會直接執行它。若要這麼做，請從全域的終端機功能表中選取設定預設建置工作。這會顯示包含可用建置工作的挑選器。請選取 TypeScript tsc: build，這會在 .vscode 資料夾中產生下列 tasks.json 檔案：

{
    // See https://go.microsoft.com/fwlink/?LinkId=733558
    // for the documentation about the tasks.json format
    "version": "2.0.0",
    "tasks": [
        {
            "type": "typescript",
            "tsconfig": "tsconfig.json",
            "problemMatcher": [
                "$tsc"
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            }
        }
    ]
}

請注意，該工作具有一個 group JSON 物件，將工作的 kind 設為 build 並將其設為預設值。現在，當您選取執行建置工作命令或按下 (⇧⌘B (Windows, Linux Ctrl+Shift+B)) 時，系統將不會提示您選取工作，而是直接開始編譯。

提示：您也可以使用 VS Code 的執行/偵錯功能來執行程式。有關在 VS Code 中執行與偵錯 Node.js 應用程式的詳細資料，可以在 Node.js 教學課程中找到。

步驟 4：檢閱建置問題

VS Code 工作系統也可以透過問題比對器來偵測建置問題。問題比對器會根據特定的建置工具來剖析建置輸出，並提供整合的問題顯示與導覽功能。VS Code 隨附了許多問題比對器，而上面在 tasks.json 中看到的 $tsc 就是針對 TypeScript 編譯器輸出的問題比對器。

例如，如果我們的 TypeScript 檔案中有一個簡單的錯誤 (console.log 中多了一個 'g')，我們可能會從 tsc 得到下列輸出：

HelloWorld.ts(3,17): error TS2339: Property 'logg' does not exist on type 'Console'.

這會顯示在終端機面板 (⌃` (Windows, Linux Ctrl+`)) 中，並且透過在終端機檢視下拉式選單中選取 Tasks - build tsconfig.json 來檢視。

您可以在狀態列中看到錯誤與警告的數量。按一下錯誤與警告圖示即可取得問題清單並巡覽至該處。

您也可以使用鍵盤開啟清單 ⇧⌘M (Windows, Linux Ctrl+Shift+M)。

提示：工作提供許多動作的豐富支援。請參閱工作主題以取得有關如何設定它們的詳細資訊。

JavaScript 原始對應檔支援

TypeScript 偵錯支援 JavaScript 原始對應檔。若要為您的 TypeScript 檔案產生原始對應檔，請使用 --sourcemap 選項進行編譯，或將 tsconfig.json 檔案中的 sourceMap 屬性設為 true。

同時也支援內嵌原始對應檔 (將內容儲存為資料 URL 而非獨立檔案的原始對應檔)，不過尚未支援內嵌原始程式碼。

產生檔案的輸出位置

將產生的 JavaScript 檔案放在與 TypeScript 原始檔相同的資料夾中，在較大型的專案中會迅速變得雜亂。您可以使用 outDir 屬性為編譯器指定輸出目錄。

{
  "compilerOptions": {
    "target": "ES5",
    "module": "CommonJS",
    "outDir": "out"
  }
}

隱藏衍生的 JavaScript 檔案

當您使用 TypeScript 時，通常會希望在檔案總管或搜尋結果中看不到產生的 JavaScript 檔案。VS Code 透過 files.exclude 工作區設定提供過濾功能，您可以輕鬆建立運算式來隱藏這些衍生的檔案：

**/*.js: { "when": "$(basename).ts" }

此模式將會符合任何 JavaScript 檔案 (**/*.js)，但前提是必須存在同名的對應 TypeScript 檔案。如果 JavaScript 資源被編譯到相同位置，檔案總管將不再顯示這些衍生資源。

請將帶有篩選器的 files.exclude 設定新增至工作區的 settings.json 檔案中（該檔案位於工作區根目錄的 .vscode 資料夾內）。您可以透過命令選擇區 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 中的喜好設定: 開啟工作區設定 (JSON) 命令來開啟工作區的 settings.json。

若要排除從 .ts 與 .tsx 原始檔所產生的 JavaScript 檔案，請使用此運算式：

"files.exclude": {
    "**/*.js": { "when": "$(basename).ts" },
    "**/**.js": { "when": "$(basename).tsx" }
}

這有點像是個小技巧。搜尋 glob 模式被用作鍵。上面的設定使用了兩個不同的 glob 模式來提供兩個唯一的鍵，但搜尋仍然會符合相同的檔案。

使用較新版本的 TypeScript

VS Code 隨附了 TypeScript 語言服務的最新穩定版本，並預設使用它來提供工作區中的 IntelliSense。工作區版本的 TypeScript 與您用來編譯 *.ts 檔案的 TypeScript 版本是獨立的。在多數常見的情況下，您可以安心地直接使用 VS Code 內建的 TypeScript 版本來進行 IntelliSense，但有時候您可能會需要變更 VS Code 用於 IntelliSense 的 TypeScript 版本。

這樣做的原因包括：

• 切換至 TypeScript 夜間組建 (typescript@next) 以嘗試最新的 TypeScript 功能。
• 確保您用於 IntelliSense 的 TypeScript 版本與您用來編譯程式碼的版本相同。

目前啟用的 TypeScript 版本及其安裝位置可以顯示在狀態列中。請選取語言列狀態列項目 ({ })，然後選取 TypeScript 版本的釘選圖示，使其常駐顯示在狀態列中。

如果您想要變更工作區中的預設 TypeScript 版本，您有幾個選擇：

使用工作區版本的 TypeScript

如果您的工作區具有特定的 TypeScript 版本，您可以透過開啟 TypeScript 或 JavaScript 檔案並按一下狀態列中的 TypeScript 版本號碼，來在工作區版本的 TypeScript 與 VS Code 預設使用的版本之間進行切換。隨後會出現一個訊息方塊，詢問您要讓 VS Code 使用哪個版本的 TypeScript：

使用此功能可在隨 VS Code 附帶的 TypeScript 版本與工作區中的 TypeScript 版本之間進行切換。您也可以透過TypeScript: 選取 TypeScript 版本命令來觸發 TypeScript 版本選擇器。

VS Code 會自動偵測安裝在工作區根目錄 node_modules 下的工作區版本 TypeScript。您也可以透過在使用者或工作區設定中設定 js/ts.tsdk.path，明確告知 VS Code 要使用哪個版本的 TypeScript。js/ts.tsdk.path 設定應該指向包含 TypeScript tsserver.js 檔案的目錄。您可以使用 npm list -g typescript 來尋找 TypeScript 的安裝位置。tsserver.js 檔案通常位於 lib 資料夾中。

例如

{
  "js/ts.tsdk.path": "/usr/local/lib/node_modules/typescript/lib"
}

提示：若要取得特定的 TypeScript 版本，請在執行 npm 安裝時指定 @version。例如，若要使用 TypeScript 3.6.0，您可以使用 npm install --save-dev typescript@3.6.0。若要預覽下一個版本的 TypeScript，請執行 npm install --save-dev typescript@next。

請注意，雖然在這些範例中 js/ts.tsdk.path 指向 typescript 內部的 lib 目錄，但 typescript 目錄必須是一個包含 TypeScript package.json 檔案的完整 TypeScript 安裝。

您也可以透過新增指向 tsserver.js 檔案目錄的 js/ts.tsdk.path 工作區設定，來告訴 VS Code 在特定工作區中使用特定版本的 TypeScript：

{
  "js/ts.tsdk.path": "./node_modules/typescript/lib"
}

js/ts.tsdk.path 工作區設定只會告知 VS Code 存在工作區版本的 TypeScript。若要實際開始使用工作區版本來進行 IntelliSense，您必須執行TypeScript: 選取 TypeScript 版本命令並選取工作區版本。

使用 TypeScript 夜間組建

在 VS Code 中試用最新 TypeScript 功能的最簡單方法，就是安裝 JavaScript and TypeScript Nightly 擴充功能。

此擴充功能會自動將 VS Code 內建的 TypeScript 版本替換為最新的 TypeScript 夜間組建。如果您已使用TypeScript: 選取 TypeScript 版本命令設定了 TypeScript 版本，只要確保切換回使用 VS Code 的 TypeScript 版本即可。

混合使用 TypeScript 與 JavaScript 的專案

您可以擁有混合 TypeScript 與 JavaScript 的專案。若要在 TypeScript 專案中啟用 JavaScript，您可以在 tsconfig.json 中將 allowJs 屬性設為 true。

提示：tsc 編譯器不會自動偵測 jsconfig.json 檔案的存在。請使用 –p 引數來讓 tsc 使用您的 jsconfig.json 檔案，例如 tsc -p jsconfig.json。

處理大型專案

如果您在擁有數百個或數千個 TypeScript 檔案的程式碼基底中工作，您可以採取下列幾個步驟來改善 VS Code 中的編輯體驗以及命令列上的編譯時間。

確保您的 tsconfig 僅包含您關心的檔案

在專案的 tsconfig.json 中使用 include 或 files，以確保專案僅包含應該成為專案一部分的檔案。

有關設定專案 tsconfig.json 的更多資訊。

使用專案參考來分割您的專案

與其將原始程式碼結構化為單一大型專案，不如使用專案參考將其分割成較小的專案來改善效能。這可讓 TypeScript 每次只載入程式碼基底的一個子集，而不是載入全部內容。

請參閱 TypeScript 文件以取得關於如何使用專案參考及其最佳做法的詳細資料。

後續步驟

繼續閱讀以了解

• 編輯 TypeScript - TypeScript 的特定編輯功能。
• 重構 TypeScript - TypeScript 語言服務提供的實用重構功能。
• 對 TypeScript 進行偵錯 - 為您的 TypeScript 專案設定偵錯器。

常見問題

如何解決 TypeScript 的「無法編譯外部模組 (Cannot compile external module)」錯誤？

如果您遇到該錯誤，請透過在專案根資料夾中建立 tsconfig.json 檔案來解決它。tsconfig.json 檔案可讓您控制 Visual Studio Code 如何編譯您的 TypeScript 程式碼。如需詳細資訊，請參閱 tsconfig.json 概觀。

為什麼使用 VS Code 時遇到的錯誤和警告與編譯 TypeScript 專案時不同？

VS Code 隨附了 TypeScript 語言服務的最新穩定版本，它可能與您電腦上全域安裝或工作區中本機安裝的 TypeScript 版本不符。因此，您的編譯器輸出與由作用中 TypeScript 語言服務偵測到的錯誤之間可能會出現差異。請參閱使用較新版本的 TypeScript 以取得安裝相符 TypeScript 版本的詳細資料。

我可以使用隨 VS 2022 附帶的 TypeScript 版本嗎？

不行，隨 Visual Studio 2019 與 2022 附帶的 TypeScript 語言服務與 VS Code 不相容。您需要從 npm 安裝獨立的 TypeScript 版本。

為什麼有些錯誤會被回報為警告？

依預設，VS Code TypeScript 會將程式碼樣式問題顯示為警告而非錯誤。這適用於以下情況：

• 變數已宣告但從未使用過
• 屬性已宣告但從未讀取過其值
• 偵測到無法到達的程式碼
• 未使用的標籤
• switch 中的穿透 case
• 並非所有程式碼路徑都會傳回值

將這些視為警告與其他工具（例如 TSLint）一致。當您從命令列執行 tsc 時，這些仍會顯示為錯誤。

您可以在使用者設定中將 "js/ts.reportStyleChecksAsWarnings": false 設為 false，藉此停用此行為。