用官方工具创建第一个 Hello World 扩展

这一页开始进入真正的实操。我们不再停留在“扩展能做什么”的概念层面，而是直接使用微软官方提供的脚手架工具，生成一个可以运行、可以调试、也可以继续改造的 Hello World 扩展示例。

完成本页后，你会得到这些结果：

  • 知道如何安装 VS Code 扩展官方脚手架
  • 能用 yo code 创建一个 TypeScript 扩展项目
  • 看懂生成后的基础目录结构
  • 能在 VS Code 中启动扩展调试宿主并执行 Hello World 命令

先准备好这些环境

开始之前，请先确认本机已经具备以下环境：

  • 已安装 Visual Studio Code
  • 已安装 Node.js LTS 版本
  • 能在终端里正常使用 npm
  • 建议提前安装 pnpm，本文示例会选择它作为包管理器

如果你还没有安装 pnpm，可以先执行：

npm install -g pnpm

安装微软官方脚手架

VS Code 扩展最常见的官方初始化方式，是使用微软维护的 generator-code，它通过 yo code 命令交互式生成项目骨架。

先在终端执行：

npm install -g yo generator-code

安装完成后，你就可以通过下面的命令创建扩展项目：

yo code

用 yo code 创建 Hello World 项目

执行 yo code 后，终端会进入一组交互式问题。对于第一个练手项目，建议按下面的思路来选择：

  1. What type of extension do you want to create? 选择 New Extension (TypeScript)
  2. What's the name of your extension? 建议填写 helloworld
  3. What's the identifier of your extension? 可以继续填写 helloworld
  4. What's the description of your extension? 可以填写 My first VS Code extension
  5. Initialize a git repository? 建议选择 Yes
  6. Which bundler to use? 选择 esbuild
  7. Which package manager to use? 本文示例选择 pnpm

下面这两张图可以帮助你建立直观印象：第一张展示的是 yo code 的交互式创建过程，第二张展示的是项目生成完成并自动安装依赖后的结果。

需要注意的是，generator-code 的问题顺序、默认值和具体文案可能会随着版本变化而略有不同，所以这里的截图更适合作为流程参考，而不是逐项严格对照。

使用 yo code 创建 VS Code 扩展项目的交互过程

yo code 完成依赖安装后的输出结果

为什么建议这样选

  • TypeScript：官方示例最完整，后续学习资料也最多
  • esbuild：构建速度快，后面调试和打包体验更顺手
  • pnpm：安装速度快、磁盘占用更友好，适合后面管理更多示例项目

一个常见提示

如果你在安装依赖后看到了类似下面的提示：

Ignored build scripts: esbuild.
Run "pnpm approve-builds" to pick which dependencies should be allowed to run scripts.

这通常不是项目创建失败，而是 pnpm 出于安全策略拦截了部分构建脚本。后续如果你遇到构建异常，可以按提示执行：

pnpm approve-builds

然后允许 esbuild 的相关脚本执行。

生成后的项目长什么样

项目创建完成后，你会看到一个类似下面的目录结构：

Hello World 扩展项目目录结构

第一次接触扩展开发时，不需要把所有文件都看懂，先抓住这几个最关键的入口即可：

  • package.json：扩展清单，声明命令、激活事件、显示名称、构建脚本等
  • src/extension.ts：扩展主入口，真正的业务代码通常从这里开始
  • src/test/extension.test.ts：自动化测试示例
  • .vscode/launch.json：调试配置，按 F5 时会用到
  • vsc-extension-quickstart.md：脚手架自动生成的官方说明

先理解这两个核心文件

对于 Hello World 示例来说，最值得先看的其实只有两个文件：package.json 和 src/extension.ts。

package.json 在做什么

这个文件不是普通的 Node.js 项目配置那么简单。对于 VS Code 扩展来说，它还是一份“扩展声明文件”，里面通常会定义：

  • 扩展名称、版本、描述
  • 激活事件 activationEvents
  • 命令列表 contributes.commands
  • 构建、编译、测试脚本

也就是说，命令为什么会出现在命令面板里，扩展会在什么时候被加载，很多信息都不是写在业务代码里，而是先声明在 package.json 里。

src/extension.ts 在做什么

脚手架生成的 Hello World 示例，会在这里完成一件非常重要的事：注册命令。

它的基本思路是：

  1. 扩展被激活
  2. 调用 vscode.commands.registerCommand(...)
  3. 注册一个命令处理函数
  4. 当你从命令面板执行该命令时，弹出一个提示消息

你现在不用急着完全记住 API 细节，只需要先建立一个最小认知：

package.json 负责声明 -> extension.ts 负责实现 -> F5 启动后在调试宿主里验证结果

运行这个 Hello World 扩展

创建完项目后，接下来请用 VS Code 打开这个新生成的扩展目录，然后执行下面的步骤：

  1. 打开项目根目录
  2. 按 F5
  3. 等待 VS Code 启动一个新的“扩展开发宿主”窗口
  4. 在新窗口中按 Ctrl+Shift+P
  5. 搜索并执行 Hello World

如果一切正常，你会看到一个消息提示，内容类似：

Hello World from helloworld!

到这里为止，你已经真正跑通了第一个 VS Code 扩展。

这一步背后到底发生了什么

很多初学者第一次跑通后，虽然看到了弹窗，但并不知道它为什么能工作。你可以先用下面这条链路理解：

  1. package.json 中声明了一个命令
  2. package.json 中还声明了与这个命令相关的激活时机
  3. 你在调试宿主里执行命令时，VS Code 激活扩展
  4. src/extension.ts 中的 activate() 被调用
  5. 命令注册成功
  6. 命令执行后弹出提示

这一条链路非常重要。后面无论你是做 Webview、Tree View、状态栏按钮还是语言功能，本质上都离不开“声明 + 激活 + 实现 + 调试验证”这套基础工作流。

现在你最应该改哪里

跑通默认示例后，推荐你马上做两个最小修改，帮助自己真正理解项目结构：

修改提示文案

打开 src/extension.ts，把默认的提示文本改成你自己的内容，例如：

vscode.window.showInformationMessage("Hello World from my first extension!");

再次按 F5 启动调试宿主，然后重新执行命令，确认修改已经生效。

修改命令标题

打开 package.json，找到 contributes.commands，你会看到类似 Hello World 的命令标题。把它改成更容易识别的名字，例如：

{
  "command": "helloworld.helloWorld",
  "title": "运行我的第一个命令"
}

这样你再次打开命令面板时，就能明显感受到：命令的展示名称来自 package.json，而不是来自 extension.ts。

这一页学到的核心内容

如果你刚完成了上面的操作，至少已经建立了这几个非常关键的基础认知：

  • VS Code 扩展可以通过微软官方脚手架快速生成
  • 第一个示例项目并不复杂，核心入口只有 package.json 和 src/extension.ts
  • 扩展开发不是“改完代码直接运行网页”，而是通过调试宿主验证功能
  • 一个命令能跑起来，依赖的是“声明、激活、实现、调试”整条链路都正确

下一步

建议你接下来继续做两件事：

  • 回头再看一次 概述页面，把今天跑通的 Hello World 放进整体知识地图里理解
  • 进入后续 API 文档，重点先学习命令、激活事件、贡献点和调试相关内容