1. 为什么值得亲手写一个 VS Code 插件如果你每天都在 VS Code 里敲代码大概率已经装过不少插件格式化、Git 辅助、AI 补全。但有没有想过那些「一键完成重复操作」的能力其实你自己也能做出来VS Code 插件开发并没有想象中那么高深它的本质就是监听一个命令执行一段逻辑把结果反馈到编辑器界面。你不需要懂 Electron也不需要研究编辑器内核只要会写 TypeScript就能在半小时内跑通第一个自研插件。这篇是「从零开始开发一个简单的 VS Code 插件」系列的第一篇目标很明确带你认识extension.ts与package.json这两个骨架文件注册并触发第一个自动化命令最后用 F5 调试亲眼看到它跑起来。学完之后你会对「命令面板里那些选项到底从哪来」这件事彻底祛魅。同时我会顺带讲一下怎么通过 TaoToken 统一 Key/API 通道给这个插件预留接入 AI 能力的入口——毕竟现在很多实用插件最后都会走到「调用大模型」这一步。适合谁看写过一点 TypeScript、用过 VS Code、想把自己重复劳动自动化掉的开发者。全程可复制跟着敲就行。2. 前置准备脚手架与项目骨架2.1 环境与脚手架安装先确认 Node.js 版本不低于 18然后装官方脚手架生成器。我习惯用 pnpm你也可以用 npm命令对应替换即可。# 确认 Node 版本 node -v # 安装脚手架生成器 npm install -g yo generator-code # 如果习惯 pnpm npm install -g pnpm装完后在任意空目录执行yo code选择New Extension (TypeScript)依次填入插件名比如my-first-command、标识符、描述。生成器会自动创建目录并安装依赖。这里有个新手常踩的坑生成完毕后.vscode/tasks.json可能报一个关于 esbuild 匹配器的警告导致后面 F5 调试起不来。解决办法是安装官方推荐的connor4312.esbuild-problem-matchers插件装完警告消失调试链路才完整。2.2 目录结构速览生成的项目结构大致如下先混个脸熟重点看两个文件├── package.json # 插件清单命令、激活事件、入口 ├── src │ └── extension.ts # 插件主入口activate / deactivate ├── esbuild.js # 打包配置 ├── tsconfig.json # TS 编译配置 └── vsc-extension-quickstart.mdpackage.json负责「告诉 VS Code 我有什么能力」extension.ts负责「能力被触发时干什么」。两者配合插件才能被识别和运行。3. 解剖 package.json命令是怎么被注册的3.1 基础信息与引擎版本package.json里第一部分是插件身份信息name是内部标识符小写加连字符displayName是市场里显示的名字version遵循语义化版本。真正决定能不能跑起来的是engines{ name: my-first-command, displayName: My First Command, description: 演示注册并触发第一个自动化命令, version: 0.0.1, engines: { vscode: ^1.99.0 } }^1.99.0表示插件要求 VS Code 1.99.0 及以上。版本写太高低版本用户装不上写太低又可能用不到新 API。入门阶段跟着脚手架默认值走就行。3.2 核心配置main、activationEvents、contributes这三块是插件的灵魂直接决定命令能否出现在命令面板里{ main: ./dist/extension.js, activationEvents: [], contributes: { commands: [ { command: my-first-command.helloWorld, title: Hello World } ] } }main指向编译后的入口文件注意是dist不是src因为 TS 需要先编译。activationEvents现在留空即可——新版 VS Code 会根据contributes.commands自动推断激活时机命令被调用时才激活插件省资源。contributes.commands里注册的命令 ID 必须和后面extension.ts里注册的字符串完全一致这是最常见的「命令找不到」根因。改完配置后可以用官方工具自检一遍它会列出会被打包的文件并校验配置pnpm dlx vscode/vsce ls如果输出正常、没有报错说明package.json结构没问题。4. 编写 extension.ts注册第一个自动化命令4.1 生命周期函数 activate 与 deactivate打开src/extension.ts核心就两个导出函数。activate在插件被激活时执行deactivate在插件卸载或 VS Code 关闭时执行后者通常做资源清理。import * as vscode from vscode export function activate(context: vscode.ExtensionContext) { console.log(插件 my-first-command 已激活) const disposable vscode.commands.registerCommand( my-first-command.helloWorld, () { vscode.window.showInformationMessage(Hello World from my-first-command!) } ) context.subscriptions.push(disposable) } export function deactivate() {}context是扩展上下文提供生命周期管理和状态存储。registerCommand的第一个参数是命令 ID必须和package.json里写的那个一模一样第二个参数是回调命令触发时执行。最后把返回的disposable推进context.subscriptions这样插件停用时命令会被自动释放避免资源泄漏。4.2 让命令做点「自动化」的事光弹提示框太单薄我们让它顺手在当前编辑器插入一行时间戳体现「自动化」的价值const disposable vscode.commands.registerCommand( my-first-command.helloWorld, async () { const editor vscode.window.activeTextEditor if (!editor) { vscode.window.showWarningMessage(请先打开一个文件) return } const stamp new Date().toISOString() await editor.edit((builder) { builder.insert(editor.selection.active, // generated at ${stamp}\n) }) vscode.window.showInformationMessage(已插入时间戳) } )这段逻辑先取当前活动编辑器没有就提示有就在光标处插入一行注释。editor.edit是异步的用await保证插入完成后再弹提示。这就是一个最小可用的自动化命令雏形。5. F5 调试验证亲眼看到命令跑起来配置和代码都就绪后按F5启动调试。VS Code 会新开一个「扩展开发宿主」窗口标题栏通常带[Extension Development Host]字样。在新窗口里按CtrlShiftPMac 是CmdShiftP调出命令面板输入Hello World就能看到我们注册的命令。选中执行如果当前打开了文件光标处会插入时间戳右下角弹出「已插入时间戳」的提示。想确认激活日志可以在宿主窗口按CtrlShiftI打开开发者工具Console 里能看到插件 my-first-command 已激活。看到这一行说明整个链路——package.json注册、extension.ts绑定、命令触发——全部打通。6. 常见报错排查清单入门阶段卡住九成是下面几个问题对照排查即可现象原因解决命令面板搜不到命令命令 ID 不一致核对package.json与extension.ts字符串F5 无法启动调试esbuild 匹配器缺失安装connor4312.esbuild-problem-matchers修改代码后无变化未重新编译调试模式下保存会自动 watch确认终端无报错提示「请先打开一个文件」宿主窗口没打开文件新建或打开任意文件再执行命令vsce ls报错package.json字段缺失检查name、version、engines是否齐全另外提醒一句main指向的是编译产物如果你手动改了src却没触发编译调试窗口跑的还是旧代码。遇到「改了没反应」先看终端有没有编译成功。7. 给插件预留 AI 能力用 TaoToken 统一 Key 与 API 通道第一个命令跑通后下一步很自然会想能不能让插件调用大模型比如选中代码后自动生成注释、解释报错这时候就会遇到一个现实问题——不同模型厂商的 Key、Base URL、请求格式都不一样插件里到处散落配置维护起来很痛苦。我的做法是用 TaoToken 做统一入口把 Key 和 API 通道收敛到一处。它兼容常见的 OpenAI 风格接口插件里只需要维护一个 Base URL 和一个 Key切换模型时改配置即可不用动业务代码。官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。在插件里你可以把 Key 存进context.secretsVS Code 提供的加密存储而不是硬编码// 读取用户配置的 Key const key await context.secrets.get(taotoken.apiKey) if (!key) { vscode.window.showWarningMessage(请先配置 TaoToken API Key) return } const res await fetch(https://taotoken.net/api/v1/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${key} }, body: JSON.stringify({ model: gpt-4o-mini, messages: [{ role: user, content: 用一句话解释这段代码 }] }) }) const data await res.json()这样插件就具备了接入 AI 的通道后续做「选中代码生成注释」「报错自动解释」都只是换 prompt 的事。Key 的申请和管理可以在控制台完成https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 需要新建或轮换 Key 时用 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。接入细节和参数说明可以对照文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。如果你只是想先验证模型返回效果不想写代码可以直接在模型对话页面试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 。而如果你打算长期做编码类插件、甚至接 Agent 工作流Coding Plan 会更省心https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。用 Claude Code 这类工具做插件辅助开发时对应的接入方式在https://taotoken.net/claude-code?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-codeutm_campaignrewrite 。把 AI 通道提前规划好后面第二章做交互式插件弹选择框、动态取数据、指挥 VS Code 推送代码时就能直接复用这套配置不用推倒重来。第一个命令只是起点真正的效率魔法是从「命令 外部能力」组合开始的。
