編譯 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)）將一路為你提供幫助。

一個針對 ES5、CommonJS 模組和 source map 的簡單 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 source map 支援

TypeScript 除錯支援 JavaScript source map。要為你的 TypeScript 檔案生成 source map，請使用 --sourcemap 選項進行編譯，或在 tsconfig.json 檔案中將 sourceMap 屬性設定為 true。

也支援內聯 source map（內容以資料 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 檔案被編譯到相同位置，檔案資源管理器將不再顯示其派生資源。

在工作區根目錄下的 .vscode 資料夾中的工作區 settings.json 檔案裡，新增帶有過濾器的 files.exclude 設定。你可以透過命令面板（⇧⌘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 語言服務，並預設使用它在你的工作區中提供智慧感知。工作區使用的 TypeScript 版本與你用來編譯 *.ts 檔案的 TypeScript 版本是獨立的。在大多數常見情況下，你可以直接使用 VS Code 內建的 TypeScript 版本進行智慧感知，無需擔心。但有時，你可能需要更改 VS Code 用於智慧感知的 TypeScript 版本。

這樣做的一些原因包括：

• 透過切換到 TypeScript 每夜構建版 (typescript@next) 來試用最新的 TypeScript 功能。
• 確保你用於智慧感知的 TypeScript 版本與用於編譯程式碼的版本相同。

當你檢視 TypeScript 檔案，並從語言狀態列將版本號固定後，當前活動的 TypeScript 版本及其安裝位置會顯示在狀態列中。

如果你想更改工作區中預設的 TypeScript 版本，有幾種選擇：

使用工作區的 TypeScript 版本

如果你的工作區有特定的 TypeScript 版本，你可以在工作區版本和 VS Code 預設版本之間切換。方法是開啟一個 TypeScript 或 JavaScript 檔案，然後點選狀態列中的 TypeScript 版本號。此時會彈出一個訊息框，詢問 VS Code 應該使用哪個版本的 TypeScript：

用此功能可以在 VS Code 自帶的 TypeScript 版本和你工作區中的 TypeScript 版本之間切換。你也可以透過**TypeScript: 選擇 TypeScript 版本**命令來觸發 TypeScript 版本選擇器。

VS Code 會自動檢測安裝在你工作區根目錄下 node_modules 中的 TypeScript 版本。你也可以透過在使用者或工作區設定中配置 typescript.tsdk 來明確告訴 VS Code 使用哪個版本的 TypeScript。typescript.tsdk 設定應指向包含 TypeScript tsserver.js 檔案的目錄。你可以使用 npm list -g typescript 來查詢 TypeScript 的安裝位置。tsserver.js 檔案通常位於 lib 資料夾中。

例如

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

提示：要獲取特定的 TypeScript 版本，請在 npm install 期間指定 @version。例如，對於 TypeScript 3.6.0，你應該使用 npm install --save-dev typescript@3.6.0。要預覽 TypeScript 的下一個版本，請執行 npm install --save-dev typescript@next。

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

你還可以透過新增一個指向 tsserver.js 檔案目錄的 typescript.tsdk 工作區設定，來告訴 VS Code 在特定工作區中使用特定版本的 TypeScript：

{
  "typescript.tsdk": "./node_modules/typescript/lib"
}

typescript.tsdk 工作區設定只是告訴 VS Code 存在一個工作區版本的 TypeScript。要真正開始使用工作區版本進行智慧感知，你必須執行**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 “無法編譯外部模組”的錯誤？

如果你遇到該錯誤，可以透過在你專案的根資料夾中建立一個 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 時，這些仍然會顯示為錯誤。

你可以透過在你的使用者設定中設定 "typescript.reportStyleChecksAsWarnings": false 來停用此行為。