老实说以前我总觉得给 VS Code 写插件是一件离自己hen遥远的事情。那时候kan着编辑器里那些五花八门的功Neng，心里总想着这得是多厉害的大牛才Neng写出来的东西啊。直到后来工作上实在没办法，需要自己搞一个提升效率的小工具，硬着头皮去查了一圈资料，才发现：原来入门这事儿，门槛真的没有想象中那么高。甚至Ke以说只要你懂一点 JavaScript 或者 TypeScript，就Nenghen快上手。

我们每天在编辑器里写代码，享受着语法高亮、智Neng提示、甚至那些花里胡哨的主题，这背后其实全靠插件生态在支撑。VS Code 的本体其实相当精简，它就像是一个操作系统，而插件才是上面跑的各种应用。今天我就想以一个过来人的身份，跟大家聊聊怎么从零开始，迈出插件开发的第一步。

第一步：工欲善其事，必先利其器

在正式动工之前，我们得先把环境搭好。这就像Zuo饭前得先备好菜板和刀具一样。VS Code 的插件开发官方推荐了一套非常成熟的脚手架工具，主要依赖 Yeoman 和 generator-code。

你需要确保电脑上装了 Node.js。装好之后就Ke以打开终端，输入下面的命令来全局安装这两个核心工具：

npm install --global yo generator-code

这个过程可Neng需要一点点时间，取决于你的网络环境。装好之后你就有了一个名为 yo 的魔法棒，它Ke以帮你生成标准的项目结构。

第二步：生成你的第一个项目

环境准备好后我们就Ke以开始创建项目了。在你想存放代码的目录下执行：

yo code

这时候，终端里会弹出一连串的交互式问题。别紧张，大部分情况下一路按回车选择默认值就足够了。不过有几个关键点还是值得注意一下：

选择类型一般我们选 New Extension 就好，毕竟 TypeScript 提供了类型检查，Neng让你在调用 API 时少掉不少头发。

插件名称比如你Ke以叫它 HelloWorld，或者geng有创意一点的名字。

初始化 Git这个建议选 Y，版本控制是好习惯。

打包工具新手阶段选 unbundled Zui省心。

等它跑完，你会得到一个目录结构。这里面文件不少，但别被吓到了。对于初学者来说其实只需要重点关注两个核心文件：package.json 和 src/extension.ts。搞懂了这两个，你基本上就Yi经跨过了入门的门槛。

第三步：读懂插件的“身份证”——package.json

package.json 这个文件在 Node.js 项目里hen常见，但在 VS Code 插件里它的地位geng特殊。它不仅是配置文件，geng是插件的“静态声明中心”。VS Code 启动时会先去读这个文件，kankan你这个插件叫什么、Neng干什么、什么时候该醒过来干活。

这里面有几个字段特别重要，值得你花点时间去琢磨：

是 contributes。这部分定义了插件对外暴露的Neng力。比如你想在命令面板里加一个命令，就得在这里声明：

{
  "contributes": {
    "commands": 
  }
}

这段代码的意思是：“嘿，VS Code，我这里有个叫 helloworld.helloWorld 的命令，标题显示为 Hello World，请把它加到你的命令列表里去。”

但这只是“声明”，并不代表这个命令现在就Neng跑。这就像你在餐厅菜单上点了一道菜，服务员记下来了但后厨还没开始Zuo呢。

第四步：编写逻辑——extension.ts

真正的逻辑实现，dou在 src/extension.ts 里。这是插件的运行时入口。默认生成的代码里通常会导出两个函数：activate 和 deactivate。

activate 函数是重中之重。当插件被激活时这个函数就会被调用。我们在这里面进行命令注册、事件监听、状态初始化等等操作。

来kan一段Zui基础的代码：

import * as vscode from "vscode";
export function activate {
  const disposable = vscode.commands.registerCommand(
    "helloworld.helloWorld",
     => {
      vscode.window.showInformationMessage;
    }
  );
  context.subscriptions.push;
}
export function deactivate {}

这段代码其实只Zuo了一件事：把命令 ID helloworld.helloWorld 和一段回调函数绑定起来。当用户触发这个命令时VS Code 就会执行那个回调，弹出一个提示框。

这里有个细节特别关键，也是新手容易忽略的：context.subscriptions.push。这行代码不是写法讲究，而是插件生命周期管理的基本纪律。因为 registerCommand事件监听、文件系统 watcher 这些操作通常dou会返回一个 Disposable 对象。把它们放进 context.subscriptions，是为了确保当插件被禁用或者卸载时VS Code Neng帮我们自动清理这些资源，防止内存泄漏或者留下“脏监听器”。

第五步：关于激活策略的“玄学”

在旧版本的 VS Code 开发中，你在 contributes.commands 里声明了命令还不够，还得在 activationEvents 里手动去注册 onCommand 激活事件，这样插件才Neng用。这确实有点繁琐。

不过从 VS Code 某个版本开始，情况变了。对于像 commands 这样的贡献点，VS Code 支持自动推断激活事件。也就是说只要你在 contributes.commands 里写了当用户调用这个命令时插件就会自动激活。

但这并不意味着你Ke以完全不管激活策略。Ru果你的插件需要在编辑器启动时就常驻后台，那你还是得老老实实配置 activationEvents，比如用 * 或者 onStartupFinished。

不过作为一个有追求的开发者，我建议尽量少用这种“暴力”激活方式。毕竟激活得越早，对编辑器启动性Neng的影响就越大。Ru果一个功Neng真的只在命令执行时才需要，那就让它按需激活，这样用户体验才好。简单说就是：先保证正确，再追求“无感”，别一上来就把插件Zuo成一个常驻后台的巨无霸。

第六步：调试——F5 的魔力

写好了代码，怎么跑起来呢？VS Code 为插件开发提供了一个非常贴心的调试功Neng。

直接打开项目，按 F5。这时候，VS Code 会启动一个新的窗口。这个新窗口叫 Extension Development Host，你Ke以把它理解成一个专门用来Zuo实验的沙盒环境。你的插件就在这个新窗口里运行。

在这个新窗口里按下 Ctrl+Shift+P，输入你的命令名，然后回车。Ru果一切顺利，你应该Nengkan到右下角弹出一个提示框。恭喜你，这说明你的插件Yi经成功运行了！

当然有时候为了测试geng复杂的场景，比如需要依赖其他插件，你可Neng需要修改 launch.json，配置以 .vscode-test 的内容为启动窗口，或者把依赖的插件安装到测试目录里。比如：

# 比如说要安装一个 be5invis.vscode-custom-css
code --extensions-dir .vscode-test/extensions --install-extension be5invis.vscode-custom-css

注意启动时会弹窗显示编辑器环境变化，记得要点确认，不然可Neng会加载失败。

第七步：测试——不仅仅是单元测试

当你完成了Zui基础的命令插件，下一步建议就是写测试。VS Code 插件的测试和普通的 Node.js 单元测试不太一样，它geng像是一种集成测试。

官方现在推荐使用 @vscode/test-cli 和 @vscode/test-electron。先安装依赖：

npm install --save-dev @vscode/test-cli @vscode/test-electron

然后在 package.json 里配置一下脚本：

{
  "scripts": {
    "test": "vscode-test"
  }
}

运行 npm test 时工具会自动下载一个专用的 VS Code 实例来跑测试。你Ke以新建一个测试配置文件，里面Ke以定义测试的标签、入口文件、使用的 VS Code 版本等等。

这里有一个简单的测试示例，用到了 Mocha 框架：

import * as assert from "assert";
import * as vscode from "vscode";
suite => {
    suiteTeardown => {
        vscode.window.showInformationMessage;
    });
    suiteSetup => {
        vscode.window.showInformationMessage;
    });
    test => {
        assert.strictEqual);
        assert.strictEqual);
    });
    test => {
        const doc = await vscode.workspace.openTextDocument({
            content: "测试内容",
        });
        await vscode.window.showTextDocument;
        assert.strictEqual(
            vscode.window.activeTextEditor?.document.getText,
            "测试内容"
        );
    });
});

这种测试方式Neng让你验证插件在真实的 VS Code 环境中的表现，而不仅仅是验证某个函数的逻辑是否正确。

进阶之路：从 Hello World 到实用工具

当你跑通了 Hello World，其实Yi经完成了一个插件的基本闭环。但这只是开始。Ru果你想继续深入，Ke以尝试按照这个路线去练习：

交互式教程hen多优秀的插件dou会内置新手引导，教用户怎么用。你也Ke以试着给你的插件加一个。

代码解释工具利用悬停提示功Neng，给选中的代码段显示详细解释。

错误提示辅助拦截系统的错误信息，用geng通俗的语言告诉用户怎么回事，甚至提供解决方法。

学习进度跟踪Ru果插件是教育类的，Ke以记录用户的学习成果。

比如你Ke以试着Zuo一个Neng记录文件作者和Zui后修改时间的插件。这就涉及到监听文件保存事件，甚至可Neng需要覆盖默认的 Ctrl+S 行为。这时候你就得去研究 executeCommand 这个 API，kankan怎么通过命令来保存文件。

写在Zui后

开发 VS Code 插件，本质上就是在构建一个带有“ 清单”的 Node.js 项目。先把插件写对，再把插件写强，这个顺序千万别搞反了。不要一上来就想着怎么搞个大新闻，先从Zui简单的命令开始，理解 package.json 决定“插件对外提供什么”，代码文件决定“这些Neng力具体怎么实现”这个核心逻辑。

在这个过程中，你可Neng会遇到各种坑，比如 API 调不通、激活事件不对导致插件没反应等等。别灰心，多kankan官方文档，多逛逛 GitHub 上优秀的开源项目，kankan别人是怎么写的。

Zui后定期检查插件geng新，作为开发者，我们自己也要不断添加新功Neng。毕竟只有不断进化，才Neng让我们的工具真正成为提升效率的神器。希望这篇文章Neng帮你推开 VS Code 插件开发的大门，祝你玩得开心！

---