第一个插件实战：Hello World

纸上谈兵不如亲手写一个。本节用最经典的 Hello World 插件，走通「脚手架生成 → 编写代码 → 调试运行 → 理解日志」的完整闭环，建立插件开发的整体手感。

目标

实现一个 Hello World 插件：

• 命令面板输入命令 → 弹出问候消息
• 状态栏显示插件状态
• 输出面板打印运行日志

第一步：脚手架生成

在空目录执行：

yo code

交互选择：

1. 选择 New Extension (TypeScript)
2. 输入插件名称：hello-world
3. 输入显示名称、描述（可回车使用默认）
4. 其他选项保持默认

生成的项目结构：

hello-world/
├── .vscode/
│   ├── launch.json
│   └── tasks.json
├── src/
│   └── extension.ts
├── package.json
├── tsconfig.json
└── README.md

第二步：编写代码

打开 src/extension.ts，脚手架默认内容已实现基本命令，我们完整改造它：

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
  // 日志：插件激活时打印（进入 Extension Host 日志）
  console.log('Hello World 插件已激活');

  // 注册命令
  const helloCommand = vscode.commands.registerCommand(
    'hello-world.helloWorld',
    () => {
      // 弹出信息消息
      vscode.window.showInformationMessage(
        'Hello World from hello-world!'
      );
      // 输出面板打印
      console.log('命令已执行');
    }
  );

  // 创建状态栏项
  const statusBar = vscode.window.createStatusBarItem(
    vscode.StatusBarAlignment.Right,
    100
  );
  statusBar.text = '$(smiley) Hello World';
  statusBar.tooltip = '我的第一个插件';
  statusBar.show();

  // 全部注册加入 subscriptions
  context.subscriptions.push(helloCommand, statusBar);
}

export function deactivate() {
  console.log('Hello World 插件已停用');
}

第三步：运行与调试

按 F5 启动调试：

1. 自动执行 npm run watch 编译
2. 打开新的 Extension Development Host 窗口
3. 新窗口已加载 hello-world 插件

第四步：命令面板调用

在 Extension Development Host 窗口：

1. 按 Ctrl+Shift+P 打开命令面板
2. 输入 Hello World
3. 看到命令 「Hello World」，回车执行
4. 右下角弹出问候消息

命令的来源：package.json 的 contributes.commands 声明让它出现在命令面板，registerCommand 让它被真正执行。

第五步：状态栏显示

执行命令后，观察新窗口右下角状态栏：

• 出现笑脸图标 + Hello World 文本
• 悬停显示「我的第一个插件」
• 这是 createStatusBarItem + show() 的成果

第六步：输出面板打印

理解 console.log 的去向——它输出到 Extension Host 日志：

1. 菜单 Help → Toggle Developer Tools 打开开发者工具
2. Console 面板查看 console.log 输出
3. 或在命令面板执行 Developer: Open Extension Logs Folder 查看

console.log 不会出现在 VS Code 普通终端，只出现在 Extension Host 的控制台。

理解 Extension Host 日志

输出位置	内容	查看方式
Extension Host Console	插件的 console.log	Developer Tools
输出面板（Output）	OutputChannel 输出	视图 → 输出
开发者日志	VS Code 内部诊断	命令面板 → Developer

插件调试推荐用 输出面板（OutputChannel）展示业务日志：

import * as vscode from 'vscode';

const output = vscode.window.createOutputChannel('Hello World');

export function activate(context: vscode.ExtensionContext) {
  output.appendLine('插件已激活');

  const helloCommand = vscode.commands.registerCommand(
    'hello-world.helloWorld',
    () => {
      output.appendLine('执行 hello 命令');
      vscode.window.showInformationMessage('Hello World!');
    }
  );
  context.subscriptions.push(helloCommand);
}

修改 package.json 命令标题

脚手架默认命令标题为「Hello World」，可自定义分类：

{
  "contributes": {
    "commands": [
      {
        "command": "hello-world.helloWorld",
        "title": "Hello World",
        "category": "HelloWorld 插件"
      }
    ]
  }
}

修改后命令面板中显示为「HelloWorld 插件: Hello World」，重启调试窗口生效。

常见问题

问题	处理
命令面板找不到命令	确认 contributes.commands 已声明
点击命令报错	检查 registerCommand 的 ID 与声明一致
console.log 看不到	打开 Developer Tools 的 Console
修改代码不生效	重启调试（Ctrl+Shift+F5）

验证清单

• 命令面板能调出 Hello World 命令
• 执行后弹出信息消息
• 状态栏显示插件图标
• Output 面板能看到插件日志

第一个插件跑通后，你已掌握「声明 → 注册 → 调试 → 查看日志」的完整循环。接下来用文件操作工具，把插件能力扩展到真实业务场景。