必须push到context.subscriptions,因为VSCode停用插件时仅自动dispose该数组中的资源;漏掉会导致监听器、定时器等残留,引发卡顿或Extension host异常终止。

VSCode插件生成代码的流程不是“写完就能跑”,而是围绕 activationEvents 触发时机、context.subscriptions 资源管理、以及 vscode.commands.registerCommand 的调用链展开——漏掉任一环,命令就无法响应或导致内存泄漏。
为什么 yo code 生成的 extension.ts 里必须 push 到 context.subscriptions
VSCode 在插件停用时,会自动 dispose 所有注册到 context.subscriptions 的资源。没加进去的监听器、定时器、Webview 实例都会残留,轻则卡顿,重则引发 Extension host terminated unexpectedly 错误。
-
vscode.commands.registerCommand返回的是一个Disposable对象,必须显式context.subscriptions.push(disposable) - 如果你用了
vscode.workspace.onDidChangeTextDocument这类事件监听器,也要同样 push,否则编辑器重启后旧监听还在跑 - TypeScript 类型提示会帮你发现遗漏:未 push 的
Disposable变量在deactivate里无法被清理,TS 编译不报错但运行时出问题
package.json 里 activationEvents 写错会导致插件根本不动
插件不会随 VSCode 启动就加载,而是按 activationEvents 声明的条件懒激活。常见错误是写成 "onCommand:myExt.convert",但实际注册命令时用了 "myExt.convertText" —— 名字不一致,命令面板能看见,点下去却没反应,控制台也无报错。
- 确保
activationEvents中的命令名与registerCommand第一个参数完全一致(包括大小写和分隔符) - 避免过度激活:不要写
"*"或"onStartup",除非真需要全局监听;多数插件用onCommand:就够了 - 如果想支持右键菜单触发,还要额外在
contributes.menus里声明,仅靠activationEvents不生效
tsconfig.json 和 package.json 的 main 字段必须对齐
TypeScript 编译输出路径和 main 指向不一致,会导致插件加载时报 Error: Cannot find module './out/extension.js' —— 即使你本地 npm run compile 成功了。
- 默认脚手架生成的
tsconfig.json输出目录是out/,对应package.json的"main": "./out/extension.js" - 若改过
compilerOptions.outDir(比如改成dist/),必须同步改main,否则调试窗口启动失败 - 用
npm run watch时,确保终端当前在项目根目录,否则tsc -watch找不到tsconfig.json,编译静默失败
最易被忽略的是:插件逻辑里调用 vscode.window.showInformationMessage 等 API 时,如果没在 activate 函数作用域内执行(比如丢进 setTimeout 或 event listener 里又没传 context),后续操作可能因上下文丢失而静默失败 —— 它不抛错,只不显示。


















