从零开始写 VS Code 插件：让编辑器听你指挥，而不是你被它拿捏

从零开始写 VS Code 插件：让编辑器听你指挥，而不是你被它拿捏

适合读者：会一点基础编程，刚听说“插件开发”，想让 VS Code 多干点活的新手。
阅读目标：读完后，你能知道 VS Code 插件是什么、项目结构怎么看，并做出一个“一键插入当前时间注释”的小插件。

你有没有想过，让 VS Code 自动提醒你摸鱼太久？或者一键生成常用代码片段？再或者，遇到某种奇怪格式的文件时，让编辑器别装傻，自动帮你高亮、格式化、生成侧边栏？

这就是插件开发能做的事。

VS Code 本体已经很好用，但它不可能猜中每个人的工作习惯。插件就像给编辑器安装“外挂技能包”：原本不会的事，装上以后就会了。你写插件，不是为了把编辑器改成宇宙飞船，而是让它更贴合自己的工作流。

目录

• 一、什么是 VS Code 插件
• 二、开发前需要准备什么
• 三、创建第一个 Hello World 插件
• 四、核心文件拆解
• 五、插件开发的几个核心概念
• 六、实战：一键生成当前时间注释
• 七、小白踩坑指南
• 八、学习路线
• 九、总结

一、什么是 VS Code 插件

一句话说：VS Code 插件就是一段运行在 VS Code 里的扩展程序，用来给编辑器增加新能力。

它可以做很多事：

官方文档里经常提到几个基础词：package.json、Activation Events、Contribution Points、VS Code API。别怕，听起来像进了会议室，实际不难。

• package.json：插件的身份证和说明书，写明插件叫什么、入口在哪、什么时候启动、提供哪些能力。
• Activation Events：激活事件，决定“什么时候叫醒插件”。
• Contribution Points：贡献点，声明“我要给 VS Code 增加什么能力”。
• VS Code API：VS Code 给插件用的工具箱，比如显示提示、读取当前编辑器、插入文本。

你可以这样理解：package.json负责告诉 VS Code“我是谁、我能干嘛”，extension.ts负责真正干活。

二、开发前需要准备什么

别慌，不是让你造火箭，只是先把扳手和螺丝刀准备好。

你需要：

如果你还不熟 TypeScript，也没关系。先把它理解成“带类型提示的 JavaScript”。插件入门阶段，不需要上来就掌握所有高级语法。

安装脚手架有两种方式。临时使用可以直接运行：

npx--packageyo--packagegenerator-code -- yo code

如果你想以后多次创建插件，也可以全局安装：

npminstall--globalyo generator-code yo code

三、创建第一个 Hello World 插件

创建插件项目时，生成器会问你一串问题。新手可以先选最常见的方案：

What type of extension do you want to create? New Extension (TypeScript) What's the name of your extension? HelloWorld Which package manager to use? npm

生成完成后，用 VS Code 打开项目。接着按F5，或者在命令面板里运行：

Debug: Start Debugging

VS Code 会打开一个新窗口，名字通常叫Extension Development Host。这个窗口可以理解为插件的“试验场”。你不是在污染自己的主编辑器，而是在一个测试用 VS Code 里运行插件。

如果项目刚打开时终端提示缺少依赖，可以先执行：

npminstall

这一步相当于把项目需要的零件装齐。脚手架负责搭房子骨架，依赖包负责提供门窗水电。缺了它们，代码看着没问题，跑起来却可能一脸茫然。

然后在新窗口中打开命令面板：

Ctrl + Shift + P

搜索并运行：

Hello World

如果一切正常，你会看到一个提示消息。这个过程就是官方入门示例想让你理解的核心：插件通过命令被触发，然后调用 VS Code API 做事情。

四、核心文件拆解

一个最基础的插件项目里，先重点看两个地方。

1. package.json：插件的身份证和说明书

它大概会包含这些内容：

{"name":"hello-world","main":"./out/extension.js","engines":{"vscode":"^1.90.0"},"activationEvents":["onCommand:hello-world.helloWorld"],"contributes":{"commands":[{"command":"hello-world.helloWorld","title":"Hello World"}]}}

这里几个字段很重要：

• name：插件名字；
• main：插件编译后的入口文件；
• engines.vscode：说明兼容哪些 VS Code 版本；
• activationEvents：什么时候激活插件；
• contributes：声明插件贡献了什么能力。

从 VS Code 1.74 开始，写在contributes.commands里的用户命令在被调用时可以自动激活插件。但为了理解原理，你仍然要知道 Activation Events 在做什么：它决定插件什么时候醒来。

2. src/extension.ts：插件真正干活的地方

它通常长这样：

import*asvscodefrom'vscode';exportfunctionactivate(context:vscode.ExtensionContext){constdisposable=vscode.commands.registerCommand('hello-world.helloWorld',()=>{vscode.window.showInformationMessage('Hello World!');});context.subscriptions.push(disposable);}exportfunctiondeactivate(){}

解释一下：

• activate：插件被激活时运行；
• registerCommand：把命令 ID 和具体函数绑定起来；
• showInformationMessage：让 VS Code 弹出一条提示；
• context.subscriptions.push：把命令注册记录交给 VS Code 管理，插件卸载或关闭时方便清理；
• deactivate：插件关闭前的清理入口。

这段代码像是在告诉 VS Code：“如果用户运行hello-world.helloWorld这个命令，就执行我后面这段函数。”

五、插件开发的几个核心概念

1. 命令 Command

命令就是用户可以触发的一件事。比如“格式化文档”“打开终端”“插入当前时间”。
你可以把命令理解成遥控器上的按钮。

2. 激活事件 Activation Events

插件不应该一打开 VS Code 就全部冲出来上班，否则编辑器会很累。激活事件决定插件什么时候启动。

比如：

"activationEvents":["onCommand:timeComment.insertCurrentTime"]

意思是：当用户运行这个命令时，再叫醒插件。

3. 贡献点 Contribution Points

贡献点通常写在package.json的contributes字段里，用来告诉 VS Code：我要增加命令、菜单、快捷键、视图、语言支持等能力。

它像报名表。你不报名，VS Code 不知道你带了什么技能。

4. VS Code API

VS Code API 是插件能调用的工具箱。它能帮你读取当前编辑器、插入文本、显示提示、创建侧边栏、打开文件、监听事件。

插件不能靠意念修改编辑器，得通过 API 正经办事。

5. 调试 Debug

按F5启动调试后，你可以打断点、看变量、观察命令有没有运行。
调试不是大佬专属，是你和 bug 谈判的基本工具。

6. 打包与发布

写完插件后，可以用打包工具生成.vsix文件，自己安装或分享给别人。想发布到 Marketplace，还要准备发布账号、版本号、说明文档和图标。入门阶段先把本地插件跑起来，别一上来就想着上架。

六、实战：一键生成当前时间注释

现在做一个小功能：用户在命令面板运行命令后，插件会在当前文件插入一行当前时间注释。

1. 修改 package.json

在contributes.commands里添加命令：

"activationEvents":["onCommand:timeComment.insertCurrentTime"],"contributes":{"commands":[{"command":"timeComment.insertCurrentTime","title":"插入当前时间注释"}]}

command是命令 ID，代码里也要用它。title是命令面板里显示给用户看的名字。

2. 修改 src/extension.ts

import*asvscodefrom'vscode';exportfunctionactivate(context:vscode.ExtensionContext){constdisposable=vscode.commands.registerCommand('timeComment.insertCurrentTime',()=>{consteditor=vscode.window.activeTextEditor;if(!editor){vscode.window.showInformationMessage('先打开一个文件，再让我动手。');return;}constnow=newDate().toLocaleString();consttext=`// 当前时间：${now}\n`;editor.edit((editBuilder)=>{editBuilder.insert(editor.selection.active,text);});});context.subscriptions.push(disposable);}exportfunctiondeactivate(){}

逐行看重点：

• activeTextEditor：当前正在编辑的文件窗口；
• if (!editor)：如果没打开文件，就别硬插文本；
• new Date().toLocaleString()：获取当前时间；
• `// 当前时间：${now}\n`：生成一行注释；
• editor.edit：准备修改编辑器内容；
• insert(editor.selection.active, text)：在光标位置插入文本。

这行代码的作用很直白：让插件伸手往编辑器里塞一句话。当然，是在 VS Code API 允许的范围内伸手。

运行方式还是一样：按F5，在新窗口里打开一个文件，命令面板搜索“插入当前时间注释”，运行它。如果光标位置出现了当前时间，恭喜，你的编辑器已经开始听你指挥了。

七、小白踩坑指南

官方文档也提醒过：如果 Hello World 命令看不到，要检查package.json里的engines.vscode和你本地 VS Code 版本是否兼容。比如插件要求^1.90.0，但你本地 VS Code 版本太旧，就可能出现命令不显示或扩展无法正常加载的情况。

八、学习路线

新手可以按这个路线走，不用一口吃成插件大师。

1. JavaScript / TypeScript 基础：会变量、函数、模块、异步。
2. Node.js 和 npm：知道依赖怎么装、脚本怎么跑。
3. 插件脚手架：会用 Yeoman 创建项目。
4. 核心结构：看懂package.json和extension.ts。
5. 做 3 个小插件：时间注释插件、代码片段插件、侧边栏待办插件。
6. 学习常见能力：Webview、Tree View、配置项、菜单、快捷键。
7. 打包与发布：生成.vsix，了解 Marketplace 发布流程。
8. 进阶项目：AI 编程助手、项目管理工具、代码质量检查工具。

插件开发最好的学习方式不是背 API，而是做小工具。功能可以小，但一定要能跑。

九、总结

VS Code 插件开发，本质上是在给编辑器加技能包。

package.json负责声明插件身份和能力，activationEvents决定什么时候叫醒插件，contributes告诉 VS Code 你要增加什么，extension.ts负责真正执行逻辑，VS Code API 则是你和编辑器沟通的工具箱。

一开始别急着做复杂插件。先从 Hello World、插入一行文本、显示提示消息这些小功能开始。每跑通一个小例子，你对 VS Code 插件机制的理解都会稳一点。

学 VS Code 插件开发，不是为了卷死别人，而是为了让编辑器替你多干一点活。毕竟程序员的终极理想，就是把重复劳动交给机器，自己负责喝水和假装思考。