VS Code自定义脚本本质是通过扩展注册命令，需在package.json声明command并在extension.ts的activate中用vscode.commands.registerCommand实现，ID必须完全一致，且依赖activationEvents触发、调试窗口加载及TypeScript编译成功。
自定义脚本本质是注册命令，不是写普通 JS 文件
VS Code 插件里的“自定义脚本”不是指在项目里随便放个 script.js 就能跑，而是通过扩展（extension）注册一个可被触发的命令，再在回调里执行逻辑。你写的代码必须作为插件的一部分被加载，不能靠 node script.js 这种方式运行。
常见误解是：改了 keybindings.json 或加个 shell 脚本就能“运行自定义脚本”。实际不行——VS Code 不会执行外部脚本，也不允许未经沙盒验证的任意代码执行。
- 所有逻辑必须写在
src/extension.ts（或对应入口文件）中 - 必须用
vscode.commands.registerCommand显式注册，ID 与package.json中声明一致 - 命令只有在调试窗口（Extension Development Host）或已安装插件后才生效
命令注册必须配对 package.json + extension.ts
漏掉任一端，命令就搜不到。这是最常卡住的地方。
package.json 里要声明：
{
"contributes": {
"commands": [{
"command": "my-plugin.run-script",
"title": "Run My Script"
}]
}
}
extension.ts 里要实现：
vscode.commands.registerCommand('my-plugin.run-script', async () => {
const editor = vscode.window.activeTextEditor;
if (!editor) return;
const text = editor.document.getText();
// 比如把当前选中内容转成大写
const upper = text.toUpperCase();
await editor.edit(edit => {
edit.replace(editor.selection, upper);
});
});
-
command字符串必须完全一致，包括大小写、连字符、前缀 - 注册必须发生在
activate()函数内，且返回的Disposable要加入context.subscriptions - 如果想支持右键菜单触发，需额外在
package.json的menus字段配置"when": "editorTextFocus"等条件
读写文件、调用 CLI 都得走 VS Code API
不能直接用 fs.readFile 或 child_process.exec —— 这些 Node.js 原生 API 在插件沙盒里默认不可用，或行为受限。
正确做法：
- 读写工作区文件：用
vscode.workspace.fs.readFile()/vscode.workspace.fs.writeFile() - 执行外部命令（如
git,curl）：用vscode.terminal.createTerminal().sendText()或vscode.env.openExternal()启动外部进程 - 需要真正调用本地 CLI 工具时，必须检查用户是否安装、路径是否正确，并捕获
ENOENT错误 - 异步操作务必
await，否则命令可能提前返回，导致 UI 卡顿或结果丢失
调试时命令不出现？先看这三件事
不是代码写错了，而是环境没到位。
- 没按
F5启动调试窗口——只有 “Extension Development Host” 窗口才加载你的插件逻辑 -
package.json缺"activationEvents": ["onCommand:my-plugin.run-script"]，扩展根本没激活 - TypeScript 没编译成功，
out/extension.js不存在或内容陈旧；检查终端是否有tsc报错
复杂点在于：命令注册本身不报错，但静默失败。最容易被忽略的是 activationEvents 配置缺失——它不像语法错误会红标，只是让你永远搜不到那个命令。
