package.json的contributes.commands是插件功能的入口开关，必须显式声明命令ID且与registerCommand参数完全一致，否则逻辑不会执行；command值需严格匹配大小写和符号，title为面板显示名，activationEvents需同步配置触发条件。
package.json 的 contributes.commands 是插件逻辑的入口开关
VSCode 插件不靠“自动运行”，所有功能必须显式注册命令才能被触发。没在 package.json 的 contributes.commands 里声明，extension.ts 里写再多逻辑也永远不会执行。
常见错误是只改了 extension.ts 中的 registerCommand，却忘了同步更新 package.json —— 这会导致命令面板搜不到、快捷键无效、状态栏点击无响应。
-
command字段值（如"my-plugin.fetchData"）必须和vscode.commands.registerCommand()第一个参数完全一致，大小写、点号都不能错 -
title是命令面板中显示的中文名，可含空格；但command名建议全小写+短横线，避免特殊字符 - 如果插件需在编辑器打开时就生效（比如监听文件保存），得额外加
"onStartupFinished"到activationEvents，否则首次启动不会激活
extension.ts 中 registerCommand 的参数顺序决定调用方式
注册命令时传入的回调函数，参数由 VSCode 自动注入，不是你随便写个 (arg1, arg2) 就能拿到东西。
最常用的是单参数形式：registerCommand('my.cmd', (uri) => { ... })。此时若用户右键文件选择该命令，uri 就是当前文件路径；若从命令面板触发，uri 是 undefined。
- 想兼容两种触发方式？得先判空：
if (uri instanceof vscode.Uri) { ... } else { uri = vscode.window.activeTextEditor?.document.uri; } - 需要传多个自定义参数？不能靠函数签名，得用
vscode.commands.executeCommand('my.cmd', arg1, arg2)主动调用，且注册时回调必须写成(...args: any[]) => { ... } - 别在回调里直接写异步操作（如
fetch）却不await或returnPromise——VSCode 不会等它完成，可能中断后续流程
contributes.menus 控制命令在哪出现，影响用户实际使用路径
命令注册了，但用户找不到，等于没做。菜单配置决定了命令出现在右键菜单、编辑器标题栏、状态栏还是资源管理器里。
例如想让“格式化 JSON”只在 .json 文件右键出现，就得这样配：
{
"contributes": {
"menus": {
"editor/context": [{
"when": "resourceExtname == .json",
"command": "my-plugin.formatJson",
"group": "navigation"
}]
}
}
}
-
when条件表达式必须严格匹配，resourceLangId == javascript和resourceExtname == .js效果不同：前者看语言模式（可能被插件覆盖），后者看文件后缀 -
group决定排序位置，"navigation"靠前，"z_commands"靠后；自定义 group 名要带下划线，否则可能被忽略 - 状态栏项（
statusBar/primary）必须配合createStatusBarItem使用，且需手动.show()，否则注册了也不显示
调试时看不到 console.log？检查输出通道和激活时机
在 extension.ts 里写 console.log 却没输出，不是代码错了，而是日志被发到了 VSCode 的“输出”面板里，不是浏览器控制台。
- 按
Ctrl+Shift+P→ 输入 “Developer: Toggle Developer Tools”，再切到 Console 标签，才能看到未捕获异常；正常日志要去 “Output” 面板，选左上角下拉菜单里的你的插件名 - 如果连 Output 面板都看不到日志，大概率是插件根本没激活——检查
activationEvents是否漏配，或package.json里main指向的文件路径是否拼错（比如写成src/extension.js但实际编译后是out/extension.js） - 调试窗口（F5 启动的 Extension Development Host）里修改代码后，需手动重载（
Ctrl+R）才生效，热更新默认关闭
