VSCode插件调试必须使用"type": "extensionHost"启动专用开发主机实例，而非普通Node.js配置；否则无法加载vscode API、触发activationEvents，导致模块找不到或断点不命中。
VSCode插件本身是用 TypeScript/JavaScript 开发的，调试它不是“运行插件看效果”，而是启动一个**专门用于加载你插件的 VS Code 实例（Extension Development Host）**，并在其中复现行为、设断点、检查 context 和 vscode API 调用。不理解这点，90% 的调试失败都源于环境没跑起来。
为什么 launch.json 里 type 必须是 "extensionHost"
这是最常被忽略的前提。VSCode 插件调试不是普通 Node.js 程序，不能用 node 或 pwa-node 类型配置。VSCode 调试器需要通过 extensionHost 类型启动一个隔离的、带完整 VS Code 运行时环境的子进程，才能正确加载 package.json 中声明的 activationEvents 和 contributes。
- 错误写法：
"type": "node"→ 报错Error: Cannot find module 'vscode'，因为没注入 VS Code 的全局 API 模拟层 - 正确写法：在
.vscode/launch.json中配置"type": "extensionHost"，且"request": "launch" - 必须指定
"runtimeExecutable"指向你的 VS Code 可执行文件（如"C:\Users\xxx\AppData\Local\Programs\Microsoft VS Code\Code.exe"），否则会 fallback 到系统默认安装路径，多用户或便携版容易出错
断点不命中？检查 extension.ts 的 activate 函数是否真被触发
很多新手在 activate 函数第一行打了断点，但调试启动后根本不停——说明插件压根没激活。原因几乎都出在 package.json 的 activationEvents 配置上。
-
onStartupFinished是最“懒”的激活时机，适合初始化逻辑，但调试时无法手动触发，断点难验证 - 推荐用
onCommand:myExtension.doSomething，然后在调试 Host 实例中按Ctrl+Shift+P输入命令名手动调用，确保流程可控 - 如果用了
onLanguage:python，但调试 Host 里没打开 .py 文件，activate就不会执行——别只盯着代码，要看触发条件是否满足 - 终端输出
console.log在调试 Host 的开发者工具（Help → Toggle Developer Tools）里才看得见，不是主窗口的终端
调试时修改代码后热更新失效怎么办
VSCode 插件开发默认不支持 HMR（热模块替换）。每次改完 src/extension.ts，必须重启整个 Extension Development Host 才能生效，这是常态，不是 bug。
- 快捷方式：按
Ctrl+R（Windows/Linux）或Cmd+R（macOS）在调试 Host 窗口里刷新，等同于重启该实例 - 不要依赖
npm run watch自动编译后就以为插件已更新——TypeScript 编译只是生成out/extension.js，但旧的调试 Host 进程仍运行着老代码 - 如果你改的是
package.json（比如新增 command），必须完全关闭再重开调试 Host，否则新声明不会注册 - 频繁重启卡顿？关掉调试 Host 里的其他无关插件（尤其是 ESLint、Prettier），避免干扰启动性能
常见报错：command 'myExtension.xxx' not found
这个错误表面是命令没注册，实际往往发生在两个阶段：注册失败，或执行时上下文丢失。
- 注册失败：确认
vscode.commands.registerCommand('myExtension.xxx', ...)确实写在activate函数内，且没有被 try/catch 吞掉异常（加个console.error包裹回调函数） - 上下文丢失：在命令回调里访问
vscode.window.activeTextEditor前，先判断是否为null——调试 Host 启动时可能没打开任何文件，直接访问会抛Cannot read property 'document' of undefined - 拼写一致性：
package.json里contributes.commands[].command的值，必须和registerCommand第一个参数**完全一致**（包括大小写、中划线），VSCode 不做容错匹配 - 调试 Host 的扩展视图（
Ctrl+Shift+X）里搜你的插件名，看状态是不是 “Enabled”；如果是 “Disabled due to errors”，点开详情看具体哪行报错
插件调试真正的复杂点不在语法或配置，而在于你得同时跟踪三个上下文：你写的 TypeScript 逻辑、VS Code 运行时注入的 API 行为、以及 Extension Development Host 的生命周期状态。任何一个环节脱节，断点就成摆设。动手前，先花两分钟确认 launch.json 的 type 和 runtimeExecutable 是否真实有效，比反复重启省半小时。
