探索 Agent 式開發 -

使用 JavaScript

本主題介紹 Visual Studio Code 支援的一些進階 JavaScript 功能。透過 TypeScript 語言服務，VS Code 不僅能提供智慧型程式碼完成 (IntelliSense)，還能為 JavaScript 提供型別檢查。

IntelliSense

Visual Studio Code 的 JavaScript IntelliSense 提供智慧型程式碼完成、參數資訊、參考搜尋以及許多其他進階語言功能。我們的 JavaScript IntelliSense 由 TypeScript 團隊開發的 JavaScript 語言服務所驅動。雖然對於大多數 JavaScript 專案而言，IntelliSense 無需任何設定即可運作，但您可以使用 JSDoc 或設定 jsconfig.json 專案，讓 IntelliSense 發揮更大效益。

關於 JavaScript IntelliSense 如何運作的詳細資訊，包括基於型別推論、JSDoc 註解、TypeScript 宣告，以及混合 JavaScript 和 TypeScript 專案的細節，請參閱 JavaScript 語言服務文件。

當型別推論無法提供所需的資訊時，可以使用 JSDoc 註解來明確提供型別資訊。本文件描述目前支援的 JSDoc 註解。

除了物件、方法和屬性之外，JavaScript IntelliSense 視窗還提供檔案中符號的基本文字完成功能。

型別定義檔與自動型別取得 (Automatic Type Acquisition)

JavaScript 程式庫和框架的 IntelliSense 是由 TypeScript 型別宣告 (typings) 檔案所驅動。型別宣告檔案使用 TypeScript 編寫，因此它們能夠表達參數和函式的資料型別，讓 VS Code 以高效能的方式提供豐富的 IntelliSense 體驗。

許多熱門的程式庫都隨附型別定義檔，因此您可以自動獲得它們的 IntelliSense 支援。對於不包含型別定義的程式庫，VS Code 的自動型別取得 (Automatic Type Acquisition) 功能會自動為您安裝社群維護的型別定義檔。

自動型別取得需要 npmjs（Node.js 的套件管理員），該工具已包含在 Node.js 執行環境中。在此影像中，您可以看到 IntelliSense，包括熱門 lodash 程式庫的方法簽章、參數資訊以及方法文件。

lodash typings

Visual Studio Code 會自動為您專案 package.json 中列出的套件，或您匯入至 JavaScript 檔案中的套件，下載並管理型別宣告檔案。

{
  "dependencies": {
    "lodash": "^4.17.0"
  }
}

您也可以在 jsconfig.json 中明確列出需要取得型別宣告檔案的套件。

{
  "typeAcquisition": {
    "include": ["jquery"]
  }
}

大多數常見的 JavaScript 程式庫都隨附宣告檔案，或是提供可用的型別宣告檔案。

修復「未安裝 npm」以啟用自動型別取得的警告

自動型別取得使用 Node.js 的套件管理員 npm 來安裝和管理型別宣告 (typings) 檔案。為確保自動型別取得功能正常運作，請先確認您的電腦已安裝 npm。

在終端機或命令提示字元中執行 npm --version，即可快速檢查 npm 是否已安裝且可用。

npm 隨 Node.js 執行環境安裝，可從 Nodejs.org 下載。安裝目前的 LTS（長期支援）版本後，npm 可執行檔預設會被加入至您的系統路徑中。

如果您已安裝 npm 但仍看到警告訊息，可以使用 js/ts.tsserver.npm.path 設定來明確告知 VS Code npm 的安裝位置。此設定應設為您電腦上 npm 可執行檔的完整路徑，且此路徑無須與您在工作區中管理套件所使用的 npm 版本一致。js/ts.tsserver.npm.path 需要 TypeScript 2.3.4+ 版本。

例如，在 Windows 上，您會在 settings.json 檔案中加入如下的路徑：

{
  "js/ts.tsserver.npm.path": "C:\\Program Files\\nodejs\\npm.cmd"
}

JavaScript 專案 (jsconfig.json)

目錄中若存在 jsconfig.json 檔案，代表該目錄為 JavaScript 專案的根目錄。jsconfig.json 會指定根檔案以及由 JavaScript 語言服務所提供語言功能的選項。對於常見的設定，不需要 jsconfig.json 檔案；但在某些情況下，您會希望加入此檔案。

  • 並非所有檔案都應包含在您的 JavaScript 專案中（例如，您希望排除某些檔案的 IntelliSense）。這種情況在前後端分離的程式碼中很常見。
  • 當您的工作區包含多個專案內容時，您應該在每個專案的根資料夾中加入一個 jsconfig.json 檔案。
  • 您正在使用 TypeScript 編譯器將 JavaScript 原始程式碼向下編譯 (down-level compile)。

jsconfig.json 的位置

若要將您的程式碼定義為 JavaScript 專案，請在 JavaScript 程式碼的根目錄中建立 jsconfig.json，如下所示。JavaScript 專案應包含該專案的原始程式檔，且不應包含衍生或封裝後的檔案（例如 dist 目錄）。

jsconfig setup

在更複雜的專案中，您的工作區內可能會定義多個 jsconfig.json 檔案。這樣做是為了確保一個專案的原始程式碼不會出現在另一個專案的 IntelliSense 中。

下圖展示了一個包含 client 和 server 資料夾的專案，顯示了兩個獨立的 JavaScript 專案。

multiple jsconfigs

編寫 jsconfig.json

下方是 jsconfig.json 檔案的簡單模板，它將 JavaScript 的 target 定義為 ES6，並透過 exclude 屬性排除 node_modules 資料夾。您可以將此程式碼複製並貼上到您的 jsconfig.json 檔案中。

{
  "compilerOptions": {
    "module": "CommonJS",
    "target": "ES6"
  },
  "exclude": ["node_modules", "**/node_modules/*"]
}

exclude 屬性會告知語言服務哪些檔案不屬於您的原始程式碼。如果 IntelliSense 速度變慢，請將資料夾加入至 exclude 清單中（若 VS Code 偵測到程式碼完成速度變慢，會提示您執行此操作）。您應該 exclude 由建置程序產生的檔案（例如 dist 目錄）。這些檔案會導致建議重複顯示，並拖慢 IntelliSense 的速度。

您可以使用 include 屬性明確設定專案中的檔案。如果沒有 include 屬性，預設會包含包含目錄及其子目錄中的所有檔案。一旦指定了 include 屬性，則僅包含這些指定的檔案。

以下是使用明確 include 屬性的範例：

{
  "compilerOptions": {
    "module": "CommonJS",
    "target": "ES6"
  },
  "include": ["src/**/*"]
}

最佳做法且最不容易出錯的方式，是使用 include 屬性並指定單一的 src 資料夾。請注意，exclude 和 include 中的檔案路徑是相對於 jsconfig.json 的位置。

如需更多資訊，請參閱完整的 jsconfig.json 文件。

遷移至 TypeScript

您可以擁有混合 TypeScript 和 JavaScript 的專案。若要開始遷移至 TypeScript，請將您的 jsconfig.json 檔案重新命名為 tsconfig.json，並將 allowJs 屬性設為 true。如需更多資訊，請參閱從 JavaScript 遷移。

注意： jsconfig.json 與 tsconfig.json 檔案相同，只是 allowJs 被設為 true。請參閱此處的 tsconfig.json 文件以查看其他可用選項。

JavaScript 型別檢查

VS Code 允許您在一般的 JavaScript 檔案中利用 TypeScript 的部分進階型別檢查與錯誤報告功能。這是在開發初期捕捉常見程式錯誤的絕佳方式。這些型別檢查也為 JavaScript 啟用了許多令人振奮的快速修復 (Quick Fixes) 功能，包括新增缺失的匯入 (Add missing import) 和 新增缺失的屬性 (Add missing property)。

Using type checking and Quick Fixes in a JavaScript file

TypeScript 可以像在 .ts 檔案中一樣，在 .js 檔案中推論型別。當無法推論型別時，可以使用 JSDoc 註解來指定。您可以在檢查 JavaScript 檔案的型別一文中，進一步了解 TypeScript 如何使用 JSDoc 進行 JavaScript 型別檢查。

JavaScript 的型別檢查是選用且需自行啟用的。現有的 JavaScript 驗證工具（如 ESLint）可以與新的內建型別檢查功能並存使用。

根據您的需求，您可以透過幾種不同的方式開始使用型別檢查。

個別檔案

在 JavaScript 檔案中啟用型別檢查最簡單的方法，是在檔案頂端加入 // @ts-check。

// @ts-check
let itsAsEasyAs = 'abc';
itsAsEasyAs = 123; // Error: Type '123' is not assignable to type 'string'

如果您只是想在少數幾個檔案中嘗試型別檢查，而非立即對整個程式碼庫啟用，使用 // @ts-check 是個不錯的方法。

使用設定

若要在不變更任何程式碼的情況下，為所有 JavaScript 檔案啟用型別檢查，只需將 "js/ts.implicitProjectConfig.checkJs": true 加入至您的工作區或使用者設定中。這將為任何不屬於 jsconfig.json 或 tsconfig.json 專案的 JavaScript 檔案啟用型別檢查。

您可以使用檔案頂端的 // @ts-nocheck 註解，讓個別檔案退出型別檢查。

// @ts-nocheck
let easy = 'abc';
easy = 123; // no error

您也可以在錯誤發生的程式碼行上方使用 // @ts-ignore 註解，來停用 JavaScript 檔案中的個別錯誤。

let easy = 'abc';
// @ts-ignore
easy = 123; // no error

使用 jsconfig 或 tsconfig

若要為屬於 jsconfig.json 或 tsconfig.json 的 JavaScript 檔案啟用型別檢查，請將 "checkJs": true 加入至專案的編譯器選項中。

jsconfig.json:

{
  "compilerOptions": {
    "checkJs": true
  },
  "exclude": ["node_modules", "**/node_modules/*"]
}

tsconfig.json:

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true
  },
  "exclude": ["node_modules", "**/node_modules/*"]
}

這將為專案中的所有 JavaScript 檔案啟用型別檢查。您可以使用 // @ts-nocheck 針對個別檔案停用型別檢查。

JavaScript 型別檢查需要 TypeScript 2.3 或更高版本。如果不確定目前工作區中啟用的 TypeScript 版本，請執行 TypeScript: 選取 TypeScript 版本 (TypeScript: Select TypeScript Version) 命令進行檢查。您必須在編輯器中開啟 .js/.ts 檔案才能執行此命令。如果您開啟了 TypeScript 檔案，版本會顯示在右下角。

全域變數與型別檢查

假設您正在處理使用全域變數或非標準 DOM API 的舊版 JavaScript 程式碼：

window.onload = function() {
  if (window.webkitNotifications.requestPermission() === CAN_NOTIFY) {
    window.webkitNotifications.createNotification(null, 'Woof!', '🐶').show();
  } else {
    alert('Could not notify');
  }
};

如果您嘗試在上述程式碼中使用 // @ts-check，將會看到許多關於使用全域變數的錯誤。

  1. 第 2 行 - 屬性 'webkitNotifications' 不存在於型別 'Window' 上。
  2. 第 2 行 - 找不到名稱 'CAN_NOTIFY'。
  3. 第 3 行 - 屬性 'webkitNotifications' 不存在於型別 'Window' 上。

如果您想繼續使用 // @ts-check，但確定這些並非您應用程式中的實際問題，您必須讓 TypeScript 知道這些全域變數的存在。

首先，在您的專案根目錄中建立 jsconfig.json。

{
  "compilerOptions": {},
  "exclude": ["node_modules", "**/node_modules/*"]
}

接著，重新載入 VS Code 以確保變更已套用。jsconfig.json 的存在能讓 TypeScript 知道您的 JavaScript 檔案屬於一個較大的專案。

現在，在您的工作區中某處建立一個 globals.d.ts 檔案。

interface Window {
  webkitNotifications: any;
}

declare var CAN_NOTIFY: number;

d.ts 檔案是型別宣告檔。在此例中，globals.d.ts 告知 TypeScript 存在一個全域變數 CAN_NOTIFY，且 window 上存在一個 webkitNotifications 屬性。您可以閱讀 TypeScript 文件中關於撰寫 d.ts 的更多資訊。d.ts 檔案不會改變 JavaScript 的執行方式，它們僅用於提供更好的 JavaScript 語言支援。

使用任務 (Tasks)

使用 TypeScript 編譯器

TypeScript 的核心功能之一，是能夠使用最新的 JavaScript 語言功能，並轉譯出能在尚未支援這些新功能的 JavaScript 執行環境中運作的程式碼。既然 JavaScript 使用相同的語言服務，現在它也能利用此功能。

TypeScript 編譯器 tsc 可以將 JavaScript 檔案從 ES6 向下相容編譯 (down-level compile) 為其他語言等級。請使用所需的選項設定 jsconfig.json，然後使用 –p 參數讓 tsc 使用您的 jsconfig.json 檔案，例如執行 tsc -p jsconfig.json 進行向下相容編譯。

如需深入了解關於向下相容編譯的編譯器選項，請參閱 jsconfig 文件。

執行 Babel

Babel 轉譯器可將 ES6 檔案轉換為可讀的 ES5 JavaScript 並產生 Source Maps。您可以將 Babel 整合到您的工作流程中，只需將下方設定加入至您的 tasks.json 檔案（位於工作區的 .vscode 資料夾下）。group 設定會將此任務設為預設的 任務: 執行建置任務 (Task: Run Build Task) 動作。isBackground 會告知 VS Code 在背景中持續執行此任務。若要了解更多，請參閱任務 (Tasks)。

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "watch",
      "command": "${workspaceFolder}/node_modules/.bin/babel",
      "args": ["src", "--out-dir", "lib", "-w", "--source-maps"],
      "type": "shell",
      "group": { "kind": "build", "isDefault": true },
      "isBackground": true
    }
  ]
}

一旦加入此設定，您就可以使用 ⇧⌘B (Windows, Linux Ctrl+Shift+B) (執行建置任務) 命令來啟動 Babel，它會將 src 目錄中的所有檔案編譯至 lib 目錄。

提示： 若需要 Babel CLI 的協助，請參閱 使用 Babel 中的說明。上述範例使用的是 CLI 選項。

停用 JavaScript 支援

如果您偏好使用其他 JavaScript 工具支援的語言功能（如 Flow），您可以停用 VS Code 內建的 JavaScript 支援。您可以透過停用內建的 TypeScript 語言擴充功能 TypeScript and JavaScript Language Features (vscode.typescript-language-features) 來達成，該擴充功能同時也提供了 JavaScript 語言支援。

若要停用 JavaScript/TypeScript 支援，請前往「擴充功能」檢視 (⇧⌘X (Windows, Linux Ctrl+Shift+X)) 並篩選內建擴充功能（在 ... 更多動作下拉選單中選擇 顯示內建擴充功能），然後輸入「typescript」。選取 TypeScript and JavaScript Language Features 擴充功能並按下 停用 (Disable) 按鈕。VS Code 的內建擴充功能無法移除，僅能停用，且可隨時重新啟用。

TypeScript and JavaScript Language Features extension

部分 IntelliSense 模式

VS Code 致力於為 JavaScript 和 TypeScript 提供全專案範圍的 IntelliSense，這正是自動匯入和 移至定義 (Go to Definition) 等功能得以實現的原因。然而，在某些情況下，VS Code 僅能運作於您目前開啟的檔案，無法載入構成您 JavaScript 或 TypeScript 專案的其他檔案。

這種情況可能發生在以下幾種情形：

  • 您正在 vscode.dev 或 github.dev 上使用瀏覽器進行開發。
  • 您從虛擬檔案系統中開啟檔案（例如使用 GitHub Repositories 擴充功能時）。
  • 專案目前正在載入中。載入完成後，您將能獲得全專案範圍的 IntelliSense。

在這些情況下，VS Code 的 IntelliSense 將會在 部分模式 (partial mode) 下運作。部分模式會盡力為您開啟的 JavaScript 或 TypeScript 檔案提供 IntelliSense，但功能受限，無法提供跨檔案的 IntelliSense 功能。

哪些功能會受到影響？

以下是不完整清單，列出了在部分模式下被停用或功能受限的功能：

  • 所有開啟的檔案被視為單一專案的一部分。
  • 不會套用來自 jsconfig 或 tsconfig 的設定選項（如 target）。
  • 僅報告語法錯誤。語意錯誤（例如存取未知屬性或傳遞錯誤型別給函式）不會被報告。
  • 針對語意錯誤的快速修復 (Quick Fixes) 功能被停用。
  • 符號僅能在目前檔案內解析。從其他檔案匯入的任何符號將被視為 any 型別。
  • 命令（如 移至定義 和 尋找所有參考）僅適用於已開啟的檔案，而非跨越整個專案。這也意味著您在 node_modules 下安裝的任何套件中的符號將無法被解析。
  • 工作區符號搜尋將僅包含目前開啟檔案中的符號。
  • 自動匯入功能被停用。
  • 重新命名功能被停用。
  • 許多重構功能被停用。

在 vscode.dev 和 github.dev 上還有一些額外的功能會被停用：

檢查是否處於部分模式

若要檢查目前檔案使用的是部分模式 IntelliSense 還是全專案範圍的 IntelliSense，請將滑鼠游標懸停在狀態列的 JavaScript 或 TypeScript 語言狀態項目上。

Partial mode status item

若目前檔案處於部分模式，該狀態項目將顯示 Partial mode。

4/8/2026
English 한국어 中文(简体) 中文(繁體)
© . This site is unofficial and not affiliated with Microsoft.