VS Code 扩展开发教程：打造你的第一个插件 – wiki词典

---

VS Code 扩展开发教程：打造你的第一个插件

Visual Studio Code (VS Code) 已经成为现代开发者最受欢迎的代码编辑器之一。其强大之处不仅在于其核心功能，还在于其庞大且活跃的扩展生态系统。通过开发自定义扩展，你可以根据自己的工作流程、喜好或特定项目需求来定制和增强 VS Code，极大地提高开发效率。

本教程将带领你一步步创建一个最简单的 VS Code 扩展：一个能弹出“Hello World”消息的命令。

1. 为什么要开发 VS Code 扩展？

• 提升效率：自动化重复性任务，减少手动操作。
• 定制工作流：根据个人或团队的开发习惯定制编辑器行为。
• 集成新工具：将外部工具或服务无缝集成到 VS Code 中。
• 分享与协作：将你的扩展分享给社区，帮助更多开发者。
• 学习与成长：深入理解编辑器的内部机制，提升编程技能。

2. 前置准备

在开始之前，请确保你的系统上安装了以下工具：

1. Node.js: VS Code 扩展是基于 Node.js 构建的。请确保你的 Node.js 版本在 16.x 或更高。
   • 下载地址: https://nodejs.org/
2. npm (Node Package Manager) 或 Yarn: 通常随 Node.js 一起安装。我们将使用它来管理项目依赖。
3. Visual Studio Code: 你的开发环境。
   • 下载地址: https://code.visualstudio.com/
4. Git (可选但推荐): 用于版本控制。

3. 设置开发环境：安装 Yeoman 和扩展生成器

VS Code 官方提供了一个非常方便的脚手架工具——Yeoman，以及专门用于生成 VS Code 扩展项目的生成器 (generator-code)。

打开你的命令行工具（如终端、PowerShell 或 Git Bash），运行以下命令安装它们：

bash
npm install -g yo generator-code

• yo: Yeoman 命令行工具。
• generator-code: VS Code 扩展的 Yeoman 生成器。

4. 生成你的第一个扩展项目

现在，使用 Yeoman 来生成一个基础的扩展项目。

1. 创建一个新的文件夹来存放你的扩展项目，并进入该文件夹：

   bash
mkdir my-first-vscode-extension
cd my-first-vscode-extension

2. 在项目文件夹中，运行 Yeoman 生成器：

   bash
yo code

3. yo code 会引导你完成一系列选择，以配置你的扩展。对于我们的“Hello World”示例，请按照以下步骤选择：

   • What type of extension do you want to create? (选择你要创建的扩展类型)
     • 选择 New Extension (TypeScript)。TypeScript 是开发 VS Code 扩展的首选语言，因为它提供了类型安全和更好的开发体验。
   • What’s the name of your extension? (你的扩展名称)
     • 输入 MyFirstExtension (或者你喜欢的任何名称)。
   • What’s the identifier of your extension? (你的扩展标识符，通常与名称相同，但为小写，无空格)
     • 按回车键接受默认值 myfirstextension。
   • What’s the description of your extension? (扩展的描述)
     • 输入 A simple "Hello World" VS Code extension. (或者你喜欢的任何描述)。
   • Initialize a Git repository? (是否初始化 Git 仓库)
     • 选择 Yes (推荐)。
   • Which package manager to use? (选择包管理器)
     • 选择 npm (或 yarn，如果你更喜欢)。

   完成这些步骤后，Yeoman 会生成项目文件并安装所有必要的依赖。

4. 使用 VS Code 打开项目文件夹：

   bash
code .

   现在，你会在 VS Code 中看到生成好的项目结构。

5. 理解项目结构

让我们快速浏览一下生成项目中的关键文件和目录：

• .vscode/: 包含 VS Code 的调试配置 (launch.json) 和推荐设置 (settings.json)。
• src/extension.ts: 这是你的扩展的入口文件，包含了扩展的激活和注销逻辑。
• package.json: 这是扩展的清单文件，定义了扩展的元数据（名称、版本、描述等）、贡献点（commands, views, keybindings 等）以及依赖。
• README.md: 扩展的说明文件。
• tsconfig.json: TypeScript 配置文件。
• webpack.config.js: Webpack 配置文件，用于将 TypeScript 编译为 JavaScript。

6. 开发你的第一个功能：“Hello World”命令

我们的目标是创建一个命令，当用户执行它时，VS Code 会弹出一个“Hello World”通知。

6.1. 修改 package.json：注册命令

首先，我们需要在 package.json 中声明我们的命令。在 contributes 字段下添加一个 commands 数组：

json
{
// ... 其他字段 ...
"contributes": {
"commands": [
{
"command": "myFirstExtension.sayHello",
"title": "Hello World",
"category": "MyFirstExtension"
}
]
},
// ... 其他字段 ...
}

• command: 这是命令的唯一标识符。在代码中，我们将使用它来引用这个命令。
• title: 这是当用户在命令面板 (Ctrl+Shift+P / Cmd+Shift+P) 中搜索时看到的显示名称。
• category (可选): 为命令分组，方便用户查找。

6.2. 修改 src/extension.ts：实现命令逻辑

src/extension.ts 是扩展的入口点。它包含两个主要函数：

• activate(context: vscode.ExtensionContext): 当扩展被激活时调用。你可以在这里注册命令、监听事件等。
• deactivate(): 当扩展被禁用或卸载时调用。你可以在这里进行清理工作。

我们将修改 activate 函数来注册和实现我们的“Hello World”命令。

打开 src/extension.ts，将其内容修改为以下代码：

“`typescript
import * as vscode from ‘vscode’;

// 当你的扩展被激活时，这个方法会被调用。
// 你的扩展仅在第一次执行命令时被激活。
export function activate(context: vscode.ExtensionContext) {

// 使用控制台来输出诊断信息（console.log）和错误（console.error）
// 这一行代码只会在你的扩展被激活时执行一次
console.log('Congratulations, your extension "myfirstextension" is now active!');

// 命令已在 package.json 中定义
// 现在用 registerCommand 提供其实现。
// commandId 参数必须与 package.json 中的 "command" 字段匹配。
let disposable = vscode.commands.registerCommand('myFirstExtension.sayHello', () => {
    // 当用户执行我们在 package.json 中注册的命令时，此代码会执行。

    // 显示一个信息消息框。
    vscode.window.showInformationMessage('Hello World from MyFirstExtension!');
});

// 将命令注册的返回对象添加到订阅列表中。
// 这确保了当扩展被禁用时，该命令也会被清理。
context.subscriptions.push(disposable);

}

// 当你的扩展被禁用时，这个方法会被调用。
export function deactivate() {}
“`

代码解释：

1. import * as vscode from 'vscode';: 导入 VS Code API。所有与 VS Code 交互的功能都通过 vscode 对象提供。
2. vscode.commands.registerCommand('myFirstExtension.sayHello', () => { ... });: 这是注册命令的关键部分。
   • 第一个参数 'myFirstExtension.sayHello' 必须与 package.json 中定义的 command 标识符完全一致。
   • 第二个参数是一个回调函数，当用户执行这个命令时，这个函数就会被调用。
3. vscode.window.showInformationMessage('Hello World from MyFirstExtension!');: 在回调函数中，我们使用 vscode.window.showInformationMessage 方法来显示一个信息通知。VS Code API 提供了多种类型的通知（信息、警告、错误）。
4. context.subscriptions.push(disposable);: 这是最佳实践。registerCommand 会返回一个 Disposable 对象。将其添加到 context.subscriptions 数组中，VS Code 会在扩展停用时自动清理这个命令，防止资源泄露。

7. 运行和调试你的扩展

现在，你的“Hello World”扩展已经准备好运行了！

1. 在 VS Code 中，按 F5 键（或者点击左侧活动栏的“运行和调试”图标，然后选择“运行扩展”）。
2. 这会启动一个新的 VS Code 窗口，称为“扩展开发主机”（Extension Development Host）。这个新窗口是一个独立的 VS Code 实例，用于测试你的扩展，而不会影响你正在开发的主窗口。
3. 在新打开的“扩展开发主机”窗口中，按下 Ctrl+Shift+P (Windows/Linux) 或 Cmd+Shift+P (macOS) 打开命令面板。
4. 在命令面板中，输入 Hello World。你会看到你的命令 Hello World (MyFirstExtension) 出现在列表中。
5. 选择并执行这个命令。你会在 VS Code 右下角看到一个弹出通知，显示“Hello World from MyFirstExtension!”。

恭喜！你已经成功创建并运行了你的第一个 VS Code 扩展！

8. 调试你的扩展

在开发过程中，调试是必不可少的。

1. 在 src/extension.ts 文件中的 vscode.window.showInformationMessage(...) 这一行设置一个断点（点击行号左侧的空白区域）。
2. 再次按 F5 启动调试。
3. 在“扩展开发主机”中执行你的“Hello World”命令。
4. 你会发现 VS Code 的执行会在断点处暂停，你可以检查变量、单步执行代码等。
5. 在调试控制台中，你还会看到 console.log 的输出。

9. 打包你的扩展 (可选)

如果你想将你的扩展分享给其他人，或者发布到 VS Code Marketplace，你需要先将其打包成一个 .vsix 文件。

1. 安装 vsce 工具：这是一个命令行工具，用于打包、发布和管理 VS Code 扩展。

   bash
npm install -g vsce

2. 更新 package.json: 在打包之前，确保你的 package.json 中的 publisher 字段已设置。如果你打算发布到 Marketplace，需要注册一个 publisher ID。对于本地测试，你可以设置任意值，例如：

   json
{
"name": "myfirstextension",
"displayName": "MyFirstExtension",
"description": "A simple 'Hello World' VS Code extension.",
"version": "0.0.1",
"publisher": "YourPublisherName", // <-- 添加这一行，替换为你的名字或ID
// ... 其他字段 ...
}

3. 运行打包命令：在你的扩展项目根目录下，运行：

   bash
vsce package

   这会在你的项目根目录下生成一个 .vsix 文件 (例如：myfirstextension-0.0.1.vsix)。

10. 安装 .vsix 文件 (可选)

要手动安装 .vsix 文件，可以在 VS Code 中执行以下操作：

1. 打开 VS Code。
2. 点击左侧活动栏的“扩展”图标 (或按 Ctrl+Shift+X / Cmd+Shift+X)。
3. 点击扩展视图右上角的“…” (更多操作) 菜单。
4. 选择“从 VSIX 安装…”，然后选择你刚才生成的 .vsix 文件。

11. 发布你的扩展到 Marketplace (高级)

发布到 VS Code Marketplace 涉及以下几个步骤：

1. 注册 Azure DevOps 组织：用于获取 Personal Access Token。
2. 创建 Publisher ID：在 Marketplace 上注册你的发布者身份。
3. 获取 Personal Access Token (PAT)：用于 vsce 工具进行认证。

4. 使用 vsce publish 命令发布：

   bash
vsce publish

   详细的发布流程请参考官方文档：https://code.visualstudio.com/api/working-with-extensions/publishing-extension

12. 进阶学习和下一步

“Hello World”只是一个开始。VS Code 扩展可以做的事情非常多。你可以尝试：

• 创建状态栏项目：在 VS Code 底部状态栏显示信息。
• 创建 WebView：在 VS Code 中显示自定义 Web 界面。
• 注册快捷键：为你的命令绑定键盘快捷键。
• 实现语言服务：为特定语言提供代码补全、诊断、格式化等功能。
• 自定义视图和树视图：在侧边栏或面板中显示自定义内容。
• 文件操作：读写文件，创建、删除目录等。
• 使用工作区状态：持久化扩展数据。

推荐资源：

• VS Code 扩展 API 官方文档：https://code.visualstudio.com/api – 包含了所有可用的 API 接口和详细的指南。
• VS Code 扩展示例：https://github.com/Microsoft/vscode-extension-samples – 大量官方提供的示例代码，非常适合学习。

总结

通过本教程，你已经成功创建、运行和调试了你的第一个 VS Code 扩展。这个简单的“Hello World”示例为你打开了 VS Code 扩展开发的大门。希望它能激发你创造更多强大和有用的工具，以提升你和社区的开发体验！祝你编码愉快！

---

日期：2026年1月6日
操作系统：win32
作者：Gemini CLI