VSCode命令注册必须与package.json中contributes.commands.command字段严格一致，包括大小写、点号和命名空间；activationEvents需匹配onCommand:xxx，且activate函数为懒加载，修改后须重载窗口。
命令注册必须和 package.json 严格对齐
VSCode 不会自动发现你写了 vscode.commands.registerCommand，它只认 package.json 里 contributes.commands.command 声明过的 ID。两者稍有差异（比如大小写、拼写、前缀不一致），命令就根本不会出现在命令面板里，也不会被触发。
常见错误现象：按 Ctrl+Shift+P 搜不到命令名，控制台也无报错，调试断点完全不进回调函数。
-
package.json中的command字段值（如"myExtension.insertDate"）必须和registerCommand第一个参数完全一致 - 推荐统一用小写字母 + 点号分隔命名空间，避免中划线或大驼峰（
myextension.insert-date或MyExtension.insertDate都容易出错） - 如果改过命令 ID，务必重启“扩展开发主机”窗口，F5 启动的实例不会热重载注册表
activate 函数不是启动即执行，而是懒加载入口
VSCode 默认不预加载所有插件，activate 只在对应 activationEvents 触发时才调用。如果你在 package.json 里写的是 "onCommand:myExtension.doSomething"，那直到用户第一次执行该命令前，activate 根本不会运行——意味着里面注册的监听器、状态变量、Webview 实例全都没初始化。
这直接影响功能可靠性：比如你想监听 onDidSaveTextDocument，但把它写在 activate 外部或没配对的 activationEvents 下，保存文件时什么都不会发生。
- 常用
activationEvents：onCommand:xxx（最轻量）、onLanguage:json（打开 JSON 文件时激活）、*（启动即激活，慎用，影响启动性能） - 不要在
activate外部写业务逻辑，也不要在deactivate里释放未在activate中创建的资源 - 调试时留意输出面板的 “Extension Host” 日志，能看到某插件是否已 activate
编辑器操作必须检查 activeTextEditor 是否存在
vscode.window.activeTextEditor 是 null 的情况远比想象中多：编辑器窗口未聚焦、用户打开了空文件夹、当前是调试控制台或输出面板、甚至只是快速切换了 tab。直接链式调用 .edit(...) 会抛 Cannot read property 'edit' of undefined 错误，且不提示具体位置。
这不是边界情况，而是日常高频发生的问题。很多新手示例代码省略了判空，导致插件在真实场景下频繁崩溃。
- 每次访问前必须加判断：
if (editor && editor.document) - 插入文本时注意光标位置是否合法：
editor.selection.start在文档末尾外会失败，建议用editor.selection.isEmpty区分插入 vs 替换 - 批量修改多个编辑器？别循环调用
editor.edit，要用vscode.workspace.textDocuments遍历并逐个 await
deactivate 清理不彻底会导致热重载异常
F5 调试时 VSCode 会尝试卸载再重载插件，如果 deactivate 没返回清理函数，或返回的函数没取消所有监听器（比如漏掉 onDidChangeConfiguration），下次加载时旧监听器还在运行，新旧逻辑叠加可能造成重复弹窗、双倍日志、内存泄漏。
尤其 Webview 和事件订阅器这类长期存活对象，不手动 dispose 就等于“挂在那里等出事”。
-
deactivate应返回一个函数，内部调用所有Disposable实例的dispose()方法 - 用
vscode.window.createWebviewPanel创建的 panel 必须显式.dispose()，不能只靠用户关闭窗口 - 监听器建议统一存入数组：
const disposables: vscode.Disposable[] = []，最后disposables.forEach(d => d.dispose())
activationEvents 和 deactivate 的配对设计——它不像写个函数那么简单，而是一整套生命周期契约。写错一行配置，整个插件就卡在“半激活”状态，连 console.log 都看不到。 
