VSCode 插件开发实战：从零搭建一个可调试的本地扩展

1. 从零理解 VSCode 插件开发它到底是什么、能做什么VSCode 插件Extension本质是一个跑在独立 Extension Host 进程里的 Node.js 程序通过官方vscode模块提供的 API 与编辑器主进程通信。它能做的事情比很多人想象的多注册命令、监听文件保存、往编辑器注入装饰器改颜色、提供代码补全、挂载侧边栏视图、甚至开一个 Webview 当独立面板用。你平时用的代码高亮、括号配色、智能提示背后都是插件在干活。适合谁上手如果你写过 JavaScript 或 TypeScript能看懂package.json的字段含义就已经够了。不需要你懂 Electron 底层也不需要你熟悉编辑器源码。整个链路是用脚手架生成骨架 → 在extension.ts里写激活逻辑 → 配好launch.json→ 按 F5 起一个「扩展开发宿主」窗口 → 在里面验证你的命令和提示是否生效。我见过太多人卡在第一步脚手架跑完不知道哪个文件是入口F5 按下去报找不到调试配置或者插件装上了但命令面板里搜不到。这篇就把这些坑一个个填掉最后再给插件接一个统一的模型请求通道让它不只是个空壳。全程可跟做代码直接复制就能跑。2. 环境准备与 yo code 脚手架生成可调试的插件骨架2.1 安装必备工具链先确认 Node.js 版本。VSCode 插件对 Node 版本有要求建议 18 LTS 以上。终端里执行node -v npm -v然后全局装两个东西Yeoman 和 VSCode 官方脚手架生成器。npm install -g yo generator-codeyo是脚手架引擎generator-code是 VSCode 团队维护的模板集合。装完后进入你想放项目的目录运行yo code2.2 脚手架交互选项怎么选运行后会有一串问答第一次做容易选错。按下面来类型选New Extension (TypeScript)TypeScript 有类型提示写 API 时不容易拼错。名称填hello-token这是你的插件标识后面package.json里的name就是它。identifier 保持默认或填hello-token。description 随便写一句比如a demo extension with model endpoint。是否初始化 git 仓库选 Yes。包管理器选 npm。生成完目录结构大致是这样hello-token/ ├── .vscode/ │ ├── launch.json │ └── tasks.json ├── src/ │ └── extension.ts ├── package.json ├── tsconfig.json关键就三个文件package.json声明插件能力src/extension.ts写逻辑.vscode/launch.json管调试。很多人忽略package.json里的contributes字段结果命令注册了却在命令面板搜不到问题就出在这。2.3 package.json 里必须看懂的两个字段打开package.json找到contributescontributes: { commands: [ { command: hello-token.helloWorld, title: Hello Token } ] }commands数组里每一条就是一个可被调用的命令command是内部 IDtitle是命令面板里显示的名字。你在extension.ts里registerCommand用的 ID 必须和这里完全一致否则命令面板里根本不会出现这一项。另一个是activationEvents。新版脚手架默认用onCommand自动激活你不需要手动加。但如果你想让插件在打开某种文件时就激活就得在这里声明比如onLanguage:python。激活时机选错插件要么不启动要么拖慢编辑器启动速度。3. 可复制配置launch.json 调试参数与模型 endpoint 接入3.1 launch.json 逐字段说明脚手架生成的.vscode/launch.json已经能直接用但值得逐行看懂{ version: 0.2.0, configurations: [ { name: Run Extension, type: extensionHost, request: launch, args: [--extensionDevelopmentPath${workspaceFolder}], outFiles: [${workspaceFolder}/out/**/*.js], preLaunchTask: ${defaultBuildTask} } ] }type必须是extensionHost这是 VSCode 专门为插件调试提供的调试器类型。args里的--extensionDevelopmentPath告诉编辑器去哪个目录加载你的插件。outFiles指向编译产物TypeScript 编译后 JS 在out目录断点才能正确映射。preLaunchTask会在 F5 之前自动跑一次编译对应tasks.json里的npm: watch任务。如果你改了源码目录结构比如把src改成source记得同步改tsconfig.json的outDir和这里的outFiles否则断点会变成灰色打不上。3.2 把模型请求 endpoint 改到统一通道插件骨架跑通后通常下一步就是让它能调模型。与其在每个插件里硬编码各家地址不如统一走一个兼容 OpenAI 协议的通道。这里用 TaoToken 的 API 地址作为 endpoint它兼容标准/v1/chat/completions格式改一行 base URL 就能切换。在插件里建一个src/config.tsexport const MODEL_CONFIG { baseUrl: https://taotoken.net/api, apiKey: process.env.TAOTOKEN_API_KEY || , modelId: claude-3-5-sonnet, maxTokens: 1024 };注意baseUrl用https://taotoken.net/api不要带多余路径SDK 会自动拼/v1/chat/completions。API Key 从环境变量读别写死在代码里提交到仓库。模型 ID 按你实际开通的填这里只是示例占位。然后在extension.ts里发请求import * as vscode from vscode; import fetch from node-fetch; import { MODEL_CONFIG } from ./config; async function askModel(prompt: string): Promisestring { const res await fetch(${MODEL_CONFIG.baseUrl}/v1/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${MODEL_CONFIG.apiKey} }, body: JSON.stringify({ model: MODEL_CONFIG.modelId, messages: [{ role: user, content: prompt }], max_tokens: MODEL_CONFIG.maxTokens }) }); if (!res.ok) { throw new Error(request failed: ${res.status}); } const data: any await res.json(); return data.choices[0].message.content; }node-fetch需要npm install node-fetch2v3 是 ESM 的在 CommonJS 的插件里会报错这个坑后面排障会讲。3.3 注册命令并调用在activate函数里注册一个命令把模型返回的内容弹出来export function activate(context: vscode.ExtensionContext) { const disposable vscode.commands.registerCommand( hello-token.helloWorld, async () { const editor vscode.window.activeTextEditor; const selected editor ? editor.document.getText(editor.selection) : ; const reply await askModel(解释这段代码${selected || print(hi)}); vscode.window.showInformationMessage(reply.slice(0, 200)); } ); context.subscriptions.push(disposable); }选中一段代码命令面板执行Hello Token就能看到模型返回的解释。这就是一个最小可用的「代码解释」插件雏形。4. F5 验证请求从启动宿主到看到成功结果4.1 启动调试宿主在 VSCode 里打开hello-token项目确认.vscode/launch.json存在然后直接按 F5。会弹出一个新窗口标题栏写着[Extension Development Host]这就是你的调试宿主。原窗口底部状态栏会变成橙色表示调试会话已连接。新窗口里按CtrlShiftP打开命令面板输入Hello Token应该能看到你注册的命令。如果搜不到八成是package.json的contributes.commands里 ID 拼错了或者activationEvents没配对。4.2 验证模型请求是否通执行命令前先确保环境变量里有 Key。在启动调试的终端里设置export TAOTOKEN_API_KEY你的key然后回到调试宿主窗口打开任意一个文件选中几行代码执行Hello Token。如果配置正确右下角会弹出模型返回的解释文本。第一次请求可能慢一两秒属正常。想更直观地看请求过程可以在askModel里加一行日志console.log(requesting, MODEL_CONFIG.baseUrl, MODEL_CONFIG.modelId);日志会输出到原窗口的「调试控制台」里能看到实际请求的地址和模型 ID确认没拼错。4.3 断点调试技巧在askModel的fetch那一行左侧点一下打个红点断点。再次执行命令代码会停在那里。此时把鼠标悬停在MODEL_CONFIG上能看到baseUrl和apiKey的实际值。如果apiKey是空字符串说明环境变量没传进来检查是不是在错误的终端里 export 的。调试宿主窗口里改代码不会热更新改完要在原窗口按CtrlShiftF5重启调试会话。这个操作会关掉旧宿主、重新编译、开新宿主比手动关窗口快。5. 本篇常见错误排查401、local proxy failed、reading choices5.1 401 Unauthorized最常见。报错长这样request failed: 401原因就三类Key 没传、Key 传错、Key 没权限。先确认Authorization头格式是Bearer加空格再加 Key少个空格也会 401。再确认环境变量在启动调试的那个终端里设置过很多人是在系统终端 export 的但 VSCode 调试用的是另一个 shell读不到。排查方法在askModel里打印MODEL_CONFIG.apiKey.length如果是 0 就是没读到。解决方式是在项目根目录建.env文件用dotenv加载或者直接在 VSCode 的launch.json里加env字段env: { TAOTOKEN_API_KEY: 你的key }这样每次调试都会自动注入不用手动 export。5.2 local proxy failed报错类似FetchError: request to https://taotoken.net/api/v1/chat/completions failed, reason: connect ECONNREFUSED这通常是本机网络配置问题不是代码问题。检查是不是设了HTTP_PROXY或HTTPS_PROXY环境变量指向了一个没启动的本地端口。在终端里echo $HTTPS_PROXY看看如果有值且那个端口没服务就会 ECONNREFUSED。清掉这两个变量再试unset HTTP_PROXY unset HTTPS_PROXY另外确认baseUrl没写成http://必须是https://否则可能被重定向或直接拒绝。5.3 Cannot read properties of undefined (reading choices)报错TypeError: Cannot read properties of undefined (reading choices)说明data.choices是 undefined即返回的 JSON 结构和你预期的不一样。两种可能一是请求根本没成功返回的是错误对象但你没检查res.ok就直接取choices二是模型 ID 填错了服务端返回了错误信息。修复方式是先判断状态码再解析if (!res.ok) { const errText await res.text(); throw new Error(status ${res.status}: ${errText}); }这样报错信息里会带上服务端返回的具体原因比单纯reading choices好定位得多。另外确认modelId是你账号下真实可用的模型标识填一个不存在的 ID 也会走到这个分支。5.4 命令面板搜不到命令不是报错但很常见。检查package.json的contributes.commands[].command和extension.ts里registerCommand的第一个参数是否完全一致大小写敏感。再检查activationEvents是否包含onCommand:你的命令ID。新版脚手架会自动生成但如果你手动删过就可能丢。5.5 node-fetch 版本导致的 ESM 报错报错Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported这是装了node-fetch3导致的v3 是纯 ESM 模块而插件默认编译成 CommonJS。降级到 v2 即可npm install node-fetch2或者改用 Node 18 内置的全局fetch连依赖都不用装直接把import fetch from node-fetch删掉就能用。6. 把骨架变成可复用插件接入文档与后续方向到这里你已经有了一个能跑、能调模型、能断点调试的插件骨架。接下来可以往几个方向扩展把askModel抽成独立的 service 模块加一个配置项让用户在设置里填自己的 Key用vscode.window.createOutputChannel把请求日志输出到独立面板或者用TextEditorDecorationType把模型返回的提示直接标在代码行旁边——这就是你开头提到的「代码颜色区分与代码提示」的实现路径。调试参数和 endpoint 配置这两块建议对照官方文档再核一遍字段含义避免版本升级后字段改名。API Key 的创建和管理在控制台里操作接入细节可以查接入文档里面有完整的请求示例和参数说明。如果你打算把这个骨架用到长期编码或 Agent 场景Coding Plan 里有更完整的配额和模型选择说明。最后留一个实用技巧调试插件时把out目录加到.gitignore只提交src和配置文件。每次 F5 前preLaunchTask会自动编译不需要手动tsc。这样仓库干净协作时也不会因为编译产物冲突。