★ FEATURED ARTICLE 你打开自己用的编辑器一天里重复做的最多的事情是什么也许是每到一个新项目就把注释模板换一遍也许是把某个接口返回的数据反复整理成表格也许只是不停地把代码里的双引号替换成单引号。这些动作不会让程序崩溃但会在一天结束的时候让你觉得自己花了大把时间在给编辑器当人肉脚本。VSCode插件开发本质上就是把这类高频重复动作变成编辑器原生能力的过程。这篇文章不聊那些装完就用的现成插件而是从环境准备开始一路走完工程结构、命令注册、调试、打包上架这条完整链路带你写出第一个真正能用的插件。先说适合谁看。只要你会用VSCode并且写过一点JavaScript或者TypeScript哪怕只是刚学会写函数都可以跟着做完。不需要了解编译原理也不用对编辑器底层架构有什么研究。我会把每一步背后的原因也拆开讲清楚而不是让你停留在“照着敲能跑”的程度。1. 动手之前先想清楚一个插件到底替你解决什么问题很多新手一上来就打开官方文档然后被密密麻麻的API劝退。我的建议是反过来先别管API先找出你工作流里最让你烦的那件重复事。一个插件解决不了所有问题但它可以把一个具体的高频动作变得足够顺手。1.1 什么场景适合做成插件我总结下来适合做成插件的需求大概有三类。第一类是作用于单文件的快捷操作。比如你每天要把选中的文本转成Markdown引用格式、要给测试用例批量加跳过标记、要把当前文件的路径复制成带行号的字符串。这类需求有很强的“就地操作”属性用户处在编辑器上下文里做成命令面板入口或者右键菜单入口最自然。第二类是整工作区级别的扫描与监控。比如统计项目里所有待办标记、检查打开的文档里有没有残留的调试日志、监听某个配置文件变化后自动刷新页面。这些事靠人肉做容易漏做成一个后台插件在状态栏或者问题面板给出反馈就很合适。第三类是团队内部工具链的统一入口。把接口文档查询、构建部署脚本、代码规范校验收进一个侧边栏面板省得所有人各自记一堆命令。这类插件不一定非要上架公共市场打一个VSIX包丢给同事装或者放到内网扩展仓库里分发就够了。反过来也有不适合做插件的场景。比如复杂图形化的配置界面、需要长时间在后台跑的重计算任务这些更适合做成独立Web应用或命令行工具。插件擅长的是把逻辑和编辑器已有的交互能力拼起来而不是当重型计算宿主。为什么要强调先想清楚因为不少初学者一入门就想做一个“大而全”的工程结果连第一个命令都没跑通。别贪多先找到一个最小的重复动作在编辑器里用插件把它自动化掉完成一次端到端的闭环后面再慢慢扩。1.2 环境准备三样东西装齐就能开工第一样是Node.js推荐装当前LTS版本。插件开发里Node.js承担两件事一是通过npm安装脚手架和打包工具二是VSCode插件本身跑在Node.js环境里。版本太旧会导致某些依赖装不上版本追太新也可能碰到兼容问题用LTS最稳妥。装完在终端验证一下node -v npm -v第二样是VSCode本体。装好之后后面会一直用到它自带的“扩展开发宿主”调试模式一会儿专门说。第三样是脚手架和打包工具。在终端执行npm install -g yo generator-code vscode/vsceyo是项目脚手架生成器generator-code是VSCode扩展的生成模板vscode/vsce是打包发布插件用的命令行工具。全局装好后进到一个空目录运行yo code交互菜单里选New Extension (TypeScript)然后按提示填扩展名、发布者标识这些信息一个可运行的插件工程就自动生成了。这里多说一句选型理由很多教程会顺手让你选JavaScript但我建议选TypeScript。原因是VSCode的API类型定义完整用TypeScript写的时候参数、返回值、事件监听全都有智能提示新人面对不熟悉的API能少查很多文档。再者工程自带编译配置代码结构也更贴近社区里大部分扩展源码之后想看懂别人的插件会轻松太多。生成完的目录不复杂核心只需要理解三个文件package.json描述整个扩展的元信息和对外能力src/extension.ts是入口逻辑tsconfig.json负责把TypeScript编译到out目录。其余.vscode开头的目录是调试配置。先不用每个文件都看重点掌握package.json和src/extension.ts。2. package.json与入口文件先摸清扩展的“身份证”和“报到逻辑”我第一次写VSCode插件时以为package.json就是个普通npm依赖清单结果发现完全不是这么回事。它在插件工程里同时扮演“身份证”和“对外能力声明”两个角色很多诡异的问题都出在对这两个角色的误解上。2.1 package.json里藏着一个插件全部的对外声明除了npm包的常规字段插件工程里这几个字段要格外留意name扩展的唯一ID小写字母加连字符格式。它会进入市场的插件标识后面基本改不了。publisher发布者标识。上架公共市场后插件ID就是publisher拼接name构成的完整标识。main插件在主进程的入口文件路径TypeScript工程编译后一般指向out/extension.js。engines.vscode本插件要求的VSCode最低版本。配太高可能导致老版本用户装不了配太低又可能用一些只能在新版本里出现的API。activationEvents指定什么时机激活这个插件后面详细说。contributes声明插件贡献给编辑器的能力命令、菜单、快捷键、配置项、视图全要在这里登记。一个容易绕晕的点是package.json里的声明大多只负责“界面层”。命令出现在命令面板、菜单出现在右键位置、配置项出现在设置页这些是contributes的功劳但点击命令后真正执行什么逻辑要等插件进程加载后在代码里注册。两边必须对得上否则就会出现“命令面板里能看到命令点了却提示找不到命令”的情况。2.2 激活事件与命令注册先搞清这个联动逻辑插件不是一启动就常驻内存的而是在某些事件发生时被“叫醒”。这是为了省内存、省启动时间。最常用的激活事件就是onCommand:xxx意思是当用户执行xxx命令时插件才被激活。整个联动是这样的你在package.json里声明了一个命令demo-extension.sayHello也配置了activationEvents为onCommand:demo-extension.sayHello。用户执行这个命令时系统发现命令还没注册于是先激活插件插件加载后执行activate函数函数里调用registerCommand把命令真正的处理函数注册进去。接下来这条命令才开始正式响应。新手最容易踩的坑有两个。一个是声明了命令但忘了配activationEvents命令面板里完全看不到入口。另一个是声明和激活都配了但代码里registerCommand的命令ID写错了一个字符结果点击后提示找不到命令。排查这类问题最直接的办法就是打开package.json对照contributes和activationEvents都覆盖了哪些命令再去src/extension.ts里确认注册ID是否完全一致。2.3 入口文件里那两行activate与deactivate模板生成的src/extension.ts里一般长这样import * as vscode from vscode; export function activate(context: vscode.ExtensionContext) { // 在这里注册命令、监听事件、创建状态栏项等 } export function deactivate() {}activate是插件被激活时执行的函数所有初始化逻辑都放这里。deactivate是插件被禁用或卸载时执行的清理函数大多数插件不需要额外处理空着就行。真正要理解的是context参数它的subscriptions数组是用来收集Disposable资源的地方插件停用时这些资源会被统一释放避免内存泄漏。3. 手写第一个命令跑通从注册到生效的完整链路理论说完了现在写代码。这一节的目标是注册一个命令让它在命令面板里能被搜到点击后弹出一条通知。3.1 在extension.ts里注册命令打开src/extension.ts在activate函数里写入import * as vscode from vscode; export function activate(context: vscode.ExtensionContext) { const disposable vscode.commands.registerCommand(demo-extension.sayHello, () { vscode.window.showInformationMessage(你好这是我的第一个插件命令。); }); context.subscriptions.push(disposable); }registerCommand返回一个Disposable对象它的作用是当插件停用或卸载时自动把注册过的命令释放掉避免残留。把所有Disposable统一Push进context.subscriptions是最常见的资源管理方式相当于给插件生命周期上了保险。接着让命令名出现在命令面板里。在package.json的contributes里补上{ contributes: { commands: [ { command: demo-extension.sayHello, title: Demo: 打个招呼, category: Demo } ] } }注意command字段必须和代码里registerCommand的第一个参数完全一致大小写、连字符都不能差。title是用户看到的显示文本category用于命令面板里的分组前缀。3.2 启动调试窗口并执行命令写完代码后按F5。VSCode会弹出一个新的“扩展开发宿主”窗口当前插件以开发模式被加载到这个独立窗口里。在新窗口里打开命令面板Windows/Linux快捷键CtrlShiftPmacOS快捷键CmdShiftP输入“打个招呼”或者“Demo: 打个招呼”看到命令后回车右下角应该弹出通知这条通知就是插件本身弹出的。调试经验说一句扩展开发宿主窗口和主窗口是两个不同进程。如果焦点还在主窗口执行命令多半无效或者执行的是旧版本。每次改完代码也不用重启整个VSCode在开发宿主窗口里执行“开发者: 重新加载窗口”Developer: Reload Window就能快速加载新代码。3.3 给命令加上菜单和快捷键入口命令面板入口是最基础形式实际使用中更多是搭配右键菜单和快捷键。在contributes里继续增加menus和keybindings{ contributes: { commands: [ { command: demo-extension.sayHello, title: Demo: 打个招呼, category: Demo } ], menus: { editor/context: [ { command: demo-extension.sayHello, when: editorHasSelection, group: navigation } ] }, keybindings: [ { command: demo-extension.sayHello, key: ctrlalth, when: editorTextFocus } ] } }这样编辑器中选中文本时右键菜单里会出现命令入口编辑器文本聚焦时按CtrlAltH可以直接触发。when条件用来控制命令在什么场景下可见相当于命令触发的门禁。你后面看别人扩展的源码时会经常碰到这些条件表达式。3.4 做一个读取选区、插入包装文本的小功能光弹通知不过瘾来做一个有实际价值的选中的文本在光标位置被包成Markdown粗体语法。注册一个新命令代码写进activate函数里vscode.commands.registerCommand(demo-extension.wrapBold, () { const editor vscode.window.activeTextEditor; if (!editor) { vscode.window.showWarningMessage(请先打开一个文件并选中要处理的文本。); return; } const selection editor.selection; const selectedText editor.document.getText(selection); if (!selectedText) { vscode.window.showWarningMessage(请先选中文本。); return; } editor.edit(editBuilder { editBuilder.replace(selection, **${selectedText}**); }); });这段代码展示了拿到当前编辑器、读取选区文本、修改文档内容的核心套路。vscode.window.activeTextEditor是当前激活的编辑器editor.selection是用户选区通过document.getText(selection)拿到选中文本。修改文本必须走editor.edit()这个方法它会进入编辑器的撤销栈并触发相关事件通知。不要自己去改缓冲区里的原始字符那会绕过编辑器内部一致性机制。同样地记得在package.json的contributes.commands和activationEvents里补上demo-extension.wrapBold这个命令。保存后重载窗口在新窗口里选中一段文字执行命令就能看到文字被Markdown加粗语法包起来了。4. 再做深一点状态栏、配置项、问题面板与侧边栏跑通第一个命令之后插件开发算是入了门。但想让插件变得实用还得掌握几个高频API。这一节挑四个最常用的场景展开。4.1 状态栏按钮让插件的状态一眼可见状态栏是编辑器底部那条栏位很多插件会在这里放一个常驻图标告诉用户当前功能开没开。创建状态栏项的代码很简单const statusBarItem vscode.window.createStatusBarItem( vscode.StatusBarAlignment.Right, 100 ); statusBarItem.text $(eye) 监视中; statusBarItem.command demo-extension.sayHello; statusBarItem.show(); context.subscriptions.push(statusBarItem);这里有两个特别容易踩的坑。一个是创建完没调show()结果状态栏死活不显示。另一个是statusBarItem.text里想用图标却不会写格式是$(图标名)这些图标是编辑器内置Codicons比如$(eye)表示眼睛、$(zap)表示闪电。command字段可以填你注册过的任意命令ID用户点击状态栏项就能触发它。priority参数控制排列位置数字越大越靠右。alignment决定放左边还是右边一般工具类按钮放右边信息类提示放左边。4.2 让用户通过设置面板控制插件行为插件不能什么都写死得给用户留配置开关。这需要两步先在package.json里声明配置项再在代码里读取。配置项声明长这样{ contributes: { configuration: { title: Demo Extension, properties: { demo-extension.enableLog: { type: boolean, default: true, description: 是否开启插件日志输出 } } } } }代码里读取const config vscode.workspace.getConfiguration(demo-extension); const enableLog config.getboolean(enableLog, true);注意getConfiguration的参数是配置节名也就是你在properties里那个点号路径最左边的部分。这里demo-extension是配置节enableLog是配置子项。get的第二个参数是默认值防止用户没设置过任何值时拿不到结果。用户修改配置后可以监听变化事件vscode.workspace.onDidChangeConfiguration(event { if (event.affectsConfiguration(demo-extension.enableLog)) { const cfg vscode.workspace.getConfiguration(demo-extension); console.log(enableLog 被改为, cfg.get(enableLog)); } });onDidChangeConfiguration回调里用affectsConfiguration判断具体是哪个配置变化了避免无关配置变更也触发逻辑。4.3 把问题显示到“问题”面板诊断集合的用法写代码规范类插件最常用的反馈方式就是往编辑器的“问题”面板里塞诊断信息。核心对象是DiagnosticCollection。下面这段代码扫描打开文档里的TODO和FIXME标记把发现的标记以警告形式展示到问题面板const collection vscode.languages.createDiagnosticCollection(demo-extension); export function activate(context: vscode.ExtensionContext) { context.subscriptions.push( vscode.workspace.onDidOpenTextDocument(doc scanDoc(doc)), vscode.workspace.onDidChangeTextDocument(event scanDoc(event.document)) ); context.subscriptions.push(collection); } function scanDoc(doc: vscode.TextDocument) { const diagnostics: vscode.Diagnostic[] []; const text doc.getText(); const regex /TODO|FIXME/g; let match: RegExpExecArray | null; while ((match regex.exec(text)) ! null) { const startPos doc.positionAt(match.index); const endPos doc.positionAt(match.index match[0].length); const range new vscode.Range(startPos, endPos); diagnostics.push( new vscode.Diagnostic(range, 检测到 TODO 或 FIXME 标记, vscode.DiagnosticSeverity.Warning) ); } collection.set(doc.uri, diagnostics); }这段代码有几个关键点。doc.positionAt能把字符偏移量转成行列位置比如match.index是字符第几个转出来就是“第几行第几列”。new vscode.Diagnostic接收三个参数问题发生的位置范围、提示消息、严重级别Severity可以取Error、Warning、Information、Hint。最后collection.set(doc.uri, diagnostics)把诊断数组挂到文档URI上问题面板就会显示出来。如果后面想清空某个文档的诊断调用collection.clear()即可。这个模式是所有linter类扩展的骨架。你想检查什么就扫描什么无非是规则写简单还是写复杂的区别。4.4 一个最小TreeView侧边栏的骨架侧边栏面板是很多效率工具的主战场。TreeView相关的API看起来吓人但精华就在一个接口TreeDataProvider。它只需要你实现两个方法getTreeItem返回树节点的展示信息getChildren返回某个节点的子节点列表。先看package.json里的声明侧边栏视图必须先在contributes里注册{ contributes: { viewsContainers: { activitybar: [ { id: demo-extension, title: Demo 面板, icon: media/demo.svg } ] }, views: { demo-extension: [ { id: demo-extension.notesView, name: 待办清单 } ] } } }activitybar是左侧活动栏views里的key对应容器ID这样视图就挂到面板上了。icon字段需要一个实际的SVG文件模板默认有media目录放一个进去即可。再看代码实现import * as vscode from vscode; class NoteItem extends vscode.TreeItem { constructor(label: string, collapsibleState: vscode.TreeItemCollapsibleState) { super(label, collapsibleState); } } class NoteProvider implements vscode.TreeDataProviderNoteItem { private data: NoteItem[] [ new NoteItem(整理VSCode插件API, vscode.TreeItemCollapsibleState.None), new NoteItem(写第一篇博客, vscode.TreeItemCollapsibleState.None) ]; getTreeItem(element: NoteItem): vscode.TreeItem { return element; } getChildren(): ThenableNoteItem[] { return Promise.resolve(this.data); } } vscode.window.createTreeView(demo-extension.notesView, { treeDataProvider: new NoteProvider() });getTreeItem直接返回元素本身就行因为NoteItem已经继承了TreeItem。getChildren这里返回的是根级数据如果要支持展开子节点简单做法是给节点加children字段然后getChildren里根据element判断返回对应子树。记住一个原则provider只负责提供数据模型渲染和交互全部交给VSCode你不用管DOM相关的事情。5. 调试、打包、上架从“自己能跑”到“别人能用”写插件最爽的时刻是功能在自己机器上跑通但要让插件真正被人用上后面这几步比写代码更磨人。我把容易踩的坑集中说一下。5.1 扩展开发宿主的具体工作方式与调试技巧刚才说过按F5会弹出一个独立窗口这个窗口的专业叫法就是“扩展开发宿主”Extension Development Host。它和主窗口是两个进程你在主进程里看到的扩展栈、console日志都对应着不同的宿主。插件报错时要看开发宿主窗口的调试控制台不是主窗口的输出面板。有读者问过我为什么console.log打在主窗口看不见基本都是这个原因。调试插件时还需要注意并不是改了代码一保存就生效。因为插件是整包加载的改完代码后要重载开发宿主窗口快捷键可以自己设置命令面板搜索“Developer: Reload Window”。想让调试更快可以在终端运行npm run watch开一个TypeScript监听编译这样编译自动执行重载窗口后就能看到最新代码。断点调试没有特殊门槛直接在src/extension.ts里点击行号打红点然后在开发宿主窗口里触发命令程序就会停在断点上可以看变量值也可以看调用栈。5.2 用VSIX打包并验证本地安装插件开发到稳定版本后第一步是打包成VSIX文件。打包命令很简单vsce package这个命令会把当前目录的插件工程打包成一个.vsix文件。打包前先检查三件事package.json里的version必须是合法的三段式语义版本号比如0.0.1publisher字段不能是空的README文件建议一定要有因为很多检查流程会要求它存在。打包过程中如果报错仔细读终端输出最常遇到的几个我都踩过版本号格式不合法比如写了0.0会被直接拒绝。README缺失或内容为空vsce会给出提示。打包目录里意外混入了不需要的文件比如.vscode-test目录可以在.vscodeignore里排除。得到.vsix文件后先不要急着往外发先在本地验证打开扩展面板点右上角的“...”选择“Install from VSIX”选刚才生成的文件。装好后重启确认功能正常。这个验证过不了发布出去也是给别人制造麻烦。5.3 上架公共市场前必须处理的几个细节打算公开发布的话有几个细节值得提前处理好免得发布后返工。发布流程本身不复杂先到市场的发布后台用账号登录创建发布者标识Publisher然后生成一个个人访问令牌PAT。本地执行vsce login输入发布者名和令牌登录成功后执行vsce publish插件就会提交审核。审核通过后插件就能在搜索里出现了。这几个细节是我见过的“发布失败重灾区”第一插件ID是publisher加name的组合创建后很难改取名要谨慎。名字起得太宽泛比如“formatter”“helper”不仅搜索里淹没在同类里还可能和已存在的扩展撞ID。曾见到有人发布时发现ID被占用只能临时改工程名重新打包。第二图标要准备充分。推荐一张256×256的PNG配置在package.json的icon字段。市场列表页会把这张图放大展示模糊的、带文字的截图都非常影响观感。第三README就是你的插件主页。市场会把README整体渲染成详情页写清楚插件简介、演示截图、使用说明、快捷键列表、常见问题就够了。很多人忽略这张“门面”导致访问量低得可怜。第四每次更新都必须改版本号。市场不允许两个相同版本号存在上传新包之前先改package.json里的version否则发布会直接报错。第五不是所有插件都要上市场。团队内部工具完全可以只分发VSIX文件放内网共享目录或聊天工具就行。这样省了审核流程也不用管市场账号很多公司内部自研工具就是这么走的。6. 入门之后往哪走四条进阶路线与我的实际体会基础API都过完一遍你大概已经能写出一个“自己用着顺手”的插件了。后面再想深入我觉得有四个方向很值得花时间。6.1 值得重点关注的进阶方向一是语言功能类。代码补全、跳转定义、格式化、重命名、诊断这些底层走的是语言服务器协议LSP。如果你对某一门语言或某个框架很熟把相关知识封装成语言能力会非常有价值。二是项目级工具与文件管理。做项目管理器、模板生成器、批量替换工具、代码片段管理。这些插件不一定复杂但贴近日常做好了对开发效率提升明显。三是自定义视图和WebView。侧边栏TreeView只是基础想做一个可视化看板、配置面板或数据预览页面就需要在WebView里写前端代码。WebView本质是一个完全由你控制的网页用HTML/CSS/JS画界面再用一套消息机制和插件主体通信。四是Web扩展。把插件编译到能在纯浏览器环境运行的形式让它在在线编辑器里也能工作。这条路线比较新但符合未来云开发环境的方向。6.2 踩过坑后沉淀下来的建议最后分享几条我自己实际碰壁之后的体会。第一条第一个版本一定小。最理想的第一版就是一个命令能把选中文本格式化。端到端跑通后后续加功能都是在成熟骨架上长肉效率会很高。我见过不少人第一步就想着做一个集代码统计、TODO管理、接口文档生成的大插件结果在工程结构上纠结了好几天最后连一个能用的命令都没发布出来。第二条别背API要会查API。VSCode的API数量庞大靠记忆不现实。我写插件大部分时间都是翻类型定义文件或者官方示例仓库。关键是要知道遇到需求去哪个命名空间里找编辑器状态在vscode.window文件系统在vscode.workspace命令相关是vscode.commands事件监听统称onDid开头接口类型大多直接挂在vscode顶层命名空间下。这个“索引”能力比记住某个具体API要重要得多。第三条多翻官方示例仓库。每个示例都是按场景压缩的最小编码比零散碎片化的博客可靠得多。直接拿相关示例当骨架改改就能用。第四条给命令ID定一个清晰规范。我习惯用“扩展名.动作名”比如demo-extension.boldSelected。这样既避免和别人的扩展冲突用户在输入命令时也好检索团队协作时也容易看明白每个命令的归属。最后说句实在话。插件开发跟普通业务开发最大的不同是它离用户的手最近。你写一个小命令用户抬手就能用反馈是即时且直接的那种满足感。等你把第一版跑通会发现编辑器里那些原本让你烦躁的重复动作开始一个一个变成自己写的菜单项。那种感觉比看到测试用例全绿还要上头。保持这个手感再慢慢打磨交互细节最后决定要不要把它发布出去给更多人用。
阅读完成 · 觉得有帮助？
