应使用 workspace.onDidSaveTextDocument 响应保存事件，防抖需手动实现；命令注册 ID 必须与 package.json 严格一致；activate 中禁止 await，异步操作需用 then 或 IIFE；调试须在 Extension Development Host 窗口打开 DevTools。
onDidChangeTextDocument 触发太频繁，不是我想要的“保存后”
这个事件监听的是任意编辑操作，每敲一个键、删一个字、粘贴一段内容都会触发一次，根本不是“文件保存”的钩子。很多人误配后发现控制台狂刷日志，还以为是插件卡死。
实操建议：
- 真要响应保存动作，请改用
workspace.onDidSaveTextDocument - 如果确实需要防抖处理编辑变更（比如自动格式化），自己加
setTimeout+clearTimeout缓存逻辑，别指望事件本身会节流 - 监听前务必检查
event.document.uri.scheme === 'file'，否则会对设置页、终端输出、REPL 结果等非磁盘文件误触发
命令注册了但命令面板里找不到
最常见原因是 registerCommand 的 ID 和 package.json 里 contributes.commands.command 字段值不一致——大小写、空格、连字符错一位都不行，VSCode 就直接忽略。
实操建议：
-
package.json中定义命令时，统一用小写+连字符风格，例如"command": "my-extension.toggle-feature" -
extension.ts中注册时必须完全复刻该字符串：vscode.commands.registerCommand('my-extension.toggle-feature', ...) - 注册后记得把返回的
Disposable推入context.subscriptions，否则调试重启时旧监听可能残留，导致行为不可预测
activate 函数里 await 异步操作直接报错
VSCode 要求 activate 必须同步返回，里面写 await loadConfig() 或 await fetch() 会导致插件激活失败，控制台显示 Extension activation failed。
实操建议：
- 初始化异步逻辑必须包裹在
then或asyncIIFE 内，例如：loadConfig().then(...) - 如果依赖配置结果才能注册命令或监听器，就把这些操作移到
then回调里执行 - 不要在
activate里直接return await，它不是 Promise 返回点，而是生命周期入口点
断点灰掉、console.log 不见、日志写不到文件
八成是因为你打开的 DevTools 是主窗口的，而插件实际跑在「Extension Development Host」进程里，两者内存隔离、API 隔离、日志隔离。
实操建议：
- 按
F5启动插件调试，等新窗口弹出且标题栏含[Extension Development Host]，再在这个窗口里按Ctrl+Shift+I（Win/Linux）或Cmd+Option+I（macOS）开 DevTools -
console.log输出位置取决于执行时机：模块加载时报错出现在主窗口 DevTools；activate()里才输出到开发主机窗口的 DevTools - 最可靠的方式是写文件日志：
require('fs').appendFileSync('./debug.log', `[${new Date().toISOString()}] ${msg}\n`)，尤其适合查activate()前的初始化失败
