轉譯 TypeScript

TypeScript 是 JavaScript 的型別超集，可轉譯為純 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)) 將會輔助您進行設定。

一個簡單的 tsconfig.json 設定如下（適用於 ES5、CommonJS 模組與原始碼對應）

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

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

將 TypeScript 轉譯為 JavaScript

VS Code 透過整合式工作執行器 (Task Runner) 與 tsc 整合。我們可以使用它將 .ts 檔案轉譯為 .js 檔案。使用 VS Code 工作的另一個好處是，您可以在問題 (Problems) 面板中看到整合式的錯誤與警告偵測。讓我們逐步練習轉譯一個簡單的 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 建置

從全域的終端機 (Terminal) 選單中執行執行建置工作 (Run Build Task) (⇧⌘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 建置工作定義為預設建置工作，這樣在觸發執行建置工作 (Run Build Task) (⇧⌘B (Windows, Linux Ctrl+Shift+B)) 時，它會直接執行。若要這麼做，請從全域終端機 (Terminal) 選單中選擇設定預設建置工作 (Configure Default Build Task)。這會顯示一個包含可用建置工作的選單。選擇 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 工作系統還可以透過問題比對器 (Problem Matcher) 偵測建置問題。問題比對器會根據特定的建置工具解析建置輸出，並提供整合式的問題顯示與導覽。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)。

提示：工作對於許多動作提供了豐富的支援。請查看工作 (Tasks) 主題，以取得有關如何設定它們的更多資訊。

JavaScript 原始碼對應 (Source Map) 支援

TypeScript 偵錯支援 JavaScript 原始碼對應 (Source Maps)。若要為您的 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 檔案時才生效。如果衍生檔案被編譯到相同位置，檔案總管將不再顯示它們。

在工作區 settings.json 檔案中新增具有篩選器的 files.exclude 設定，該檔案位於工作區根目錄的 .vscode 資料夾中。您可以透過指令選擇區中的喜好設定：開啟工作區設定 (JSON) 指令開啟工作區的 settings.json (⇧⌘P (Windows, Linux Ctrl+Shift+P))。

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

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

這是一個小技巧。搜尋的全域模式 (Glob patterns) 會被用作鍵值。上述設定使用兩種不同的全域模式來提供兩個唯一的鍵值，但搜尋仍然會比對到相同的檔案。

使用較新版本的 TypeScript

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

執行此操作的原因包括

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

目前的 TypeScript 版本及其安裝位置會顯示在狀態列中。選取語言列狀態列項目 ({ })，然後選取 TypeScript 版本旁邊的釘選圖示，使其保持在狀態列中可見。

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

使用工作區版本的 TypeScript

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

使用此功能可在 VS Code 隨附的 TypeScript 版本與您工作區中的 TypeScript 版本之間切換。您也可以透過TypeScript: Select TypeScript Version 指令觸發 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: Select TypeScript Version 指令並選擇工作區版本。

使用 TypeScript 夜間組建 (Nightly builds)

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

此擴充功能會自動以最新的 TypeScript 夜間組建取代 VS Code 內建的 TypeScript 版本。如果您已透過TypeScript: Select TypeScript Version 指令設定過 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 的更多資訊。

使用專案參考 (Project References) 來拆解您的專案

與其將您的原始碼結構化為單一大型專案，不如透過使用專案參考將其拆解為較小的專案，這樣可以提升效能。這允許 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 語句中出現貫穿 (Fall through) 的 case
• 並非所有程式碼路徑都有回傳值

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

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