VS Code 插件開發教程

概述

Visual Studio Code（簡稱 VS Code）是一款由 Microsoft 開發的開源輕量級編輯器，支持跨平臺（Windows、macOS、Linux）。
其最大的優勢之一是強大的插件系統，開發者可以通過編寫擴展（Extension）來增強 VS Code 的功能，比如支持新的編程語言、代碼提示、調試器、界面主題等。

VS Code 插件的主要原理是：

• 插件運行在獨立的進程（Extension Host）中，不會阻塞編輯器主線程。
• 插件通過 VS Code 提供的 API 與編輯器進行交互，比如注冊命令、添加菜單、修改編輯器行為等。
• 插件開發語言主要是 TypeScript 或 JavaScript，并基于 Node.js 生態。

---

安裝

VS Code 安裝

1. 打開 VS Code 官方下載頁面。
2. 選擇對應操作系統（Windows、macOS 或 Linux）。
3. 按提示進行安裝，安裝完成后可以通過 code 命令（需要在安裝時勾選“添加到 PATH”）在命令行中啟動 VS Code。

插件開發環境安裝

插件開發需要以下工具：

• yo（Yeoman 腳手架工具）
• generator-code（VS Code 插件項目生成器）
• vsce（VS Code Extension CLI，用于打包和發布插件）

安裝步驟：

# 安裝 yo 和 generator-code
npm install -g yo generator-code# 安裝 vsce
npm install -g @vscode/vsce

開發

生成代碼

使用 Yeoman 腳手架生成插件項目：

yo code

執行后會有交互式提示，例如：

• 選擇插件類型（TypeScript / JavaScript）
• 插件名稱
• 描述
• 初始化 Git 倉庫等

生成完成后，項目目錄大致結構如下：

my-extension/
├── .vscode/           # VS Code 調試配置
├── src/               # 插件源碼
│   └── extension.ts   # 插件入口文件
├── package.json       # 插件描述文件，配置命令、激活事件、依賴等
├── tsconfig.json      # TypeScript 配置（如果是 TS 項目）
└── README.md          # 插件說明文檔

• package.json：插件的核心配置文件，用來描述插件元信息和擴展點。
• extension.ts：插件入口文件，負責注冊命令和功能。

package.json 核心配置

package.json 是插件的描述文件，控制插件如何被 VS Code 加載。主要字段：

{"name": "my-extension","displayName": "My Extension","description": "一個簡單的 VS Code 插件示例","version": "0.0.1","publisher": "your-name","engines": {"vscode": "^1.80.0"},"activationEvents": ["onCommand:extension.helloWorld"],"main": "./out/extension.js","contributes": {"commands": [{"command": "extension.helloWorld","title": "Hello World"}]},"scripts": {"vscode:prepublish": "npm run compile","compile": "tsc -p ./","watch": "tsc -watch -p ./","test": "npm run compile && node ./out/test/runTest.js"},"devDependencies": {"typescript": "^5.0.0","vscode": "^1.1.37"}
}

核心字段說明：

• name：插件的唯一 ID（發布后不可更改）。
• displayName：VS Code Marketplace 上顯示的名稱。
• version：插件版本。
• publisher：發布者名稱（需與 Marketplace 發布者一致）。
• engines.vscode：兼容的 VS Code 版本范圍。
• activationEvents：觸發插件激活的事件（如 onCommand、onLanguage、*）。
• main：插件的入口文件（一般是編譯后的 extension.js）。
• contributes：插件擴展點，例如命令、菜單、快捷鍵、配置等。

extension.ts 核心函數

extension.ts 是插件的入口文件，負責插件的生命周期和功能實現。

import * as vscode from 'vscode';/*** 插件被激活時調用* @param context 插件上下文對象，包含訂閱、全局存儲等*/
export function activate(context: vscode.ExtensionContext) {console.log('插件已激活！');// 注冊命令let disposable = vscode.commands.registerCommand('extension.helloWorld', () => {vscode.window.showInformationMessage('Hello World from My Extension!');});// 將命令注冊到插件上下文，確保插件卸載時清理資源context.subscriptions.push(disposable);
}/*** 插件被停用時調用* 通常用于清理資源、保存數據*/
export function deactivate() {}

核心點解釋：

• activate：插件激活時執行（如首次運行命令、打開特定文件類型）。
• deactivate：插件停用時執行，用于清理資源。
• vscode.commands.registerCommand：注冊一個命令（命令 ID 必須和 package.json 中一致）。
• vscode.window.showInformationMessage：在 VS Code 界面右下角彈出提示消息。
• context.subscriptions：插件上下文，保存所有注冊的資源，確保在插件停用時能正確釋放。

Hello World 示例

1. 編輯 src/extension.ts，添加一個最簡單的命令：

import * as vscode from 'vscode';export function activate(context: vscode.ExtensionContext) {console.log('插件已激活！');let disposable = vscode.commands.registerCommand('extension.helloWorld', () => {vscode.window.showInformationMessage('Hello World from My Extension!');});context.subscriptions.push(disposable);
}export function deactivate() {}

2. 在 package.json 中配置命令：

{"contributes": {"commands": [{"command": "extension.helloWorld","title": "Hello World"}]}
}

3. 運行調試：

• 按 F5 啟動調試，會打開一個新的 VS Code 窗口（Extension Development Host）。
• 打開命令面板（Ctrl+Shift+P / Cmd+Shift+P），輸入并運行 Hello World。
• 會彈出消息 “Hello World from My Extension!”。

拓展介紹

VS Code 插件 API 非常豐富，常見擴展能力包括：

• 編輯器擴展：代碼高亮、自動補全、格式化器。

• UI 擴展：狀態欄、活動欄、側邊欄視圖。

• 調試擴展：調試適配器，用于支持新的調試語言。

• 文件系統擴展：實現虛擬文件系統。

常見配置示例（在 package.json 中添加）：

1. 命令（Commands）

命令是最常見的擴展方式，用戶可以在命令面板（Ctrl+Shift+P）或綁定快捷鍵來觸發。

配置（package.json）：

{"contributes": {"commands": [{"command": "extension.helloWorld","title": "Hello World"}]}
}

實現（extension.ts）：

vscode.commands.registerCommand('extension.helloWorld', () => {vscode.window.showInformationMessage('Hello World!');
});

2. 菜單（Menus）

可以把命令掛載到編輯器右鍵菜單、資源管理器右鍵菜單等位置。

配置（package.json）：

{"contributes": {"commands": [{"command": "extension.helloWorld","title": "hello"}，"menus": {"editor/context": [{"command": "extension.helloWorld","when": "editorLangId == javascript","group": "navigation"}]}}
}

說明：

• editor/context 表示編輯器內右鍵菜單。
• when 條件限制了命令只在 JavaScript 文件中出現。
• group 決定菜單項分組（navigation = 導航相關）。
• 菜單本身沒有名字，只能通過命令 title 來顯示，菜單本省command會關聯到commands的命令通過command的title顯示菜單名稱。

菜單位置由 menus 的 key 決定，比如：

菜單位置 key:
`editor/context` 編輯器右鍵菜單
`editor/title` 編輯器標題欄按鈕
`editor/title/context` 編輯器標題欄右鍵菜單
`explorer/context` 資源管理器右鍵菜單
`commandPalette` 命令面板（Ctrl+Shift+P）
`view/title` 視圖面板標題欄按鈕
`scm/title` 版本控制標題欄按鈕

3. 快捷鍵（Keybindings）

可以為命令綁定快捷鍵。

配置（package.json）：

{"contributes": {"keybindings": [{"command": "extension.helloWorld","key": "ctrl+alt+h","when": "editorTextFocus"}]}
}

說明：

• key：快捷鍵組合。
• when：觸發條件，這里是“編輯器有焦點時”。

4. 狀態欄（Status Bar Items）

可以在底部狀態欄添加一個按鈕。

實現（extension.ts）：

let statusBar = vscode.window.createStatusBarItem(vscode.StatusBarAlignment.Right, 100);
statusBar.text = "$(smiley) Hello";
statusBar.command = "extension.helloWorld";
statusBar.show();
context.subscriptions.push(statusBar);

說明：

• createStatusBarItem 用于創建狀態欄元素。
• text 可以包含圖標（如 $(smiley)）。
• command 綁定點擊事件。

5. 側邊欄視圖（Views）

可以在活動欄（左側豎欄）添加一個自定義視圖。

配置（package.json）：

{"contributes": {"views": {"explorer": [{"id": "mySidebar","name": "My Sidebar"}]}}
}

實現（extension.ts）：

class MyTreeDataProvider implements vscode.TreeDataProvider<vscode.TreeItem> {getTreeItem(element: vscode.TreeItem): vscode.TreeItem {return element;}getChildren(): vscode.TreeItem[] {return [new vscode.TreeItem("Item 1"),new vscode.TreeItem("Item 2")];}
}vscode.window.registerTreeDataProvider("mySidebar", new MyTreeDataProvider());

說明：

• 在 資源管理器面板 添加一個新視圖 “My Sidebar”。

• 用 TreeDataProvider 動態提供數據。

---

6. 編輯器裝飾（Decorations）

可以給代碼添加背景色、高亮、提示信息等。

實現（extension.ts）：

const decorationType = vscode.window.createTextEditorDecorationType({backgroundColor: "rgba(255,0,0,0.3)"
});const editor = vscode.window.activeTextEditor;
if (editor) {const range = new vscode.Range(0, 0, 0, 5);editor.setDecorations(decorationType, [range]);
}

說明：

• createTextEditorDecorationType 定義樣式。
• setDecorations 應用到代碼范圍。

---

7. 語言支持（Language Features）

可以擴展某種語言的代碼補全、懸浮提示等。

配置（package.json）：

{"contributes": {"languages": [{"id": "mylang","aliases": ["MyLang"],"extensions": [".mlg"],"configuration": "./language-configuration.json"}]}
}

實現補全（extension.ts）：

vscode.languages.registerCompletionItemProvider("mylang", {provideCompletionItems(document, position) {return [new vscode.CompletionItem("helloWorld", vscode.CompletionItemKind.Keyword)];}
});

說明：

• languages 定義新語言（這里是 .mlg 后綴）。
• registerCompletionItemProvider 提供自動補全。

---

8. 配置（Configuration）

插件可以在 VS Code 設置里增加配置項。

配置（package.json）：

{"contributes": {"configuration": {"title": "My Extension","properties": {"myExtension.enableFeature": {"type": "boolean","default": true,"description": "是否啟用我的功能"},"myExtension.apiEndpoint": {"type": "string","default": "https://api.example.com","description": "API 接口地址"}}}}
}

讀取配置（extension.ts）：

const config = vscode.workspace.getConfiguration("myExtension");
const enable = config.get("enableFeature", true);
const api = config.get("apiEndpoint", "");

9. 文件系統監聽（File System Watcher）

可以監聽文件變化事件。

實現（extension.ts）：

const watcher = vscode.workspace.createFileSystemWatcher("**/*.js");
watcher.onDidChange(uri => console.log("修改: " + uri.fsPath));
watcher.onDidCreate(uri => console.log("創建: " + uri.fsPath));
watcher.onDidDelete(uri => console.log("刪除: " + uri.fsPath));context.subscriptions.push(watcher);

10. 任務（Tasks）

可以讓插件在 VS Code 的“任務運行器”中提供任務。

配置（package.json）：

{"contributes": {"taskDefinitions": [{"type": "myTask","required": ["taskName"],"properties": {"taskName": {"type": "string","description": "任務名稱"}}}]}
}

實現（extension.ts）：

vscode.tasks.registerTaskProvider("myTask", {provideTasks: () => {return [new vscode.Task({ type: "myTask", taskName: "sayHello" },vscode.TaskScope.Workspace,"sayHello","myTask",new vscode.ShellExecution("echo Hello from task!"))];},resolveTask: () => undefined
});

發布

打包插件

使用 vsce 打包插件：

# 在插件項目根目錄執行
vsce package

執行成功后，會生成一個 .vsix 文件，例如：

my-extension-0.0.1.vsix

安裝插件：

code --install-extension my-extension-0.0.1.vsix

或者到vscode插件中心右側… install from vsix選擇本地文件。

發布到 VS Code Marketplace

1. 前往 Azure DevOps 創建 Publisher。

2. 使用 vsce login <publisher-name> 登錄，并輸入 Personal Access Token。

3. 發布插件：

vsce publish

或者指定版本號：

vsce publish minor

發布成功后，你的插件就會出現在 Visual Studio Marketplace 上，供所有用戶下載。