我不知道的 VSCode 扩展:从零开始的奇妙之旅

395 字 9 min read
前端开发 VSCode 扩展开发 Debug Monorepo

引言

🚀 VSCode（Visual Studio Code）是一款强大的代码编辑器，它之所以如此受欢迎，很大程度上归功于其丰富的扩展生态。通过安装各种扩展，我们可以极大地增强 VSCode 的功能，使其更符合我们的开发习惯和需求。你是否想过，自己也能开发 VSCode 扩展，定制专属于你的开发工具呢？今天，就让我们一起踏上 VSCode 扩展开发的奇妙之旅，从零开始，打造你的第一个 VSCode 扩展！

准备工作

🛠️ 在开始扩展开发之前，我们需要先准备好开发环境。

  1. 安装 Node.js 和 npm:VSCode 扩展使用 Node.js 开发，因此需要先安装 Node.js 和 npm（Node Package Manager）。你可以从 Node.js 官网 下载并安装。安装完成后，在终端中运行 node -v 和 npm -v 检查是否安装成功。

  2. 安装 Yeoman 和 VSCode 扩展生成器:Yeoman 是一款脚手架工具，可以帮助我们快速生成 VSCode 扩展项目模板。在终端中运行以下命令安装 Yeoman 和 VSCode 扩展生成器:

    npm install -g yo generator-code

  3. 安装 VSCode:确保你已经安装了 VSCode 编辑器。

创建你的第一个扩展

✨ 环境准备就绪后，我们就可以开始创建第一个 VSCode 扩展了。

  1. 生成扩展项目:在终端中运行 yo code 命令，Yeoman 将会启动 VSCode 扩展生成器。根据提示，选择 "New Extension (TypeScript)"（或者 "New Extension (JavaScript)"，如果你更熟悉 JavaScript）。然后，按照提示填写扩展名称、描述等信息。

  2. 打开扩展项目:生成器会在你指定的目录下创建一个新的扩展项目。使用 VSCode 打开这个项目文件夹。

  3. Hello World 示例:打开 src/extension.ts（或 src/extension.js）文件，你会看到一个简单的 "Hello World" 示例代码。这个示例扩展会在 VSCode 启动时注册一个命令 extension.helloWorld，当你执行这个命令时，会在 VSCode 右下角弹出一个 "Hello World from xxx!" 的消息框。

    import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
    console.log('Congratulations, your extension "xxx" is now active!');
    let disposable = vscode.commands.registerCommand('extension.helloWorld', () => {
        vscode.window.showInformationMessage('Hello World from xxx!');
    });
    context.subscriptions.push(disposable);
}

export function deactivate() {}

  4. 运行和调试扩展:

    • 按下 F5 键，VSCode 将会启动一个扩展开发宿主（Extension Development Host）窗口。

    • 在新的宿主窗口中，按下 Ctrl+Shift+P（或 Cmd+Shift+P on macOS）打开命令面板，输入 Hello World，选择 Hello World 命令，你将看到右下角弹出的消息框。

    • Debug 调试:在 src/extension.ts（或 src/extension.js）文件中设置断点，例如在 vscode.window.showInformationMessage 这一行前面点击行号添加断点。再次按下 F5 运行扩展，当代码执行到断点处时，程序将会暂停，你可以查看变量的值，单步调试代码。

    • 修改 Debug 配置（Monorepo 场景）:默认情况下，VSCode 的 debug 配置已经可以满足大部分扩展开发的需求。但是，如果你的扩展项目位于 Monorepo（Monolithic Repository，单体仓库）中，或者你的扩展入口文件不是默认的 src/extension.ts（或 src/extension.js），你可能需要修改 debug 配置。

      1. 打开 launch.json 文件:在 VSCode 侧边栏点击 "运行和调试" 图标（小虫子图标），然后点击 "创建 launch.json 文件"，选择 "Extension Host"。VSCode 会在你的项目根目录下创建 .vscode/launch.json 文件。

      2. 修改配置:launch.json 文件是一个 JSON 格式的配置文件，用于配置 debug 启动项。默认配置通常如下所示:

        {
    "version": "0.2.0",
    "configurations": [
        {
            "type": "extensionHost",
            "request": "launch",
            "name": "Launch Extension",
            "runtimeExecutable": "${execPath}",
            "args": [
                "--extensionDevelopmentPath=${workspaceFolder}"
            ],
            "stopOnEntry": false,
            "sourceMaps": true
        }
    ]
}
        • runtimeExecutable:指定 VSCode 的可执行文件路径，通常使用默认值 ${execPath} 即可。
        • args:启动参数。
          • --extensionDevelopmentPath=${workspaceFolder}:指定扩展的开发路径为当前工作区根目录。在 Monorepo 场景下，如果你的扩展项目位于 Monorepo 的子目录中，你需要将 ${workspaceFolder} 修改为你的扩展项目所在的子目录的绝对路径。例如，如果你的 Monorepo 根目录是 /path/to/monorepo，你的扩展项目位于 /path/to/monorepo/extensions/my-extension，你需要将 ${workspaceFolder} 修改为 "/path/to/monorepo/extensions/my-extension"。
        • stopOnEntry:是否在扩展启动时暂停，默认为 false。
        • sourceMaps:是否启用 Source Maps，用于 debug TypeScript 代码，默认为 true。

      3. 保存并重启 Debug:修改 launch.json 文件后，保存文件。重新按下 F5 启动 Debug，VSCode 将会使用新的配置来启动扩展开发宿主窗口。

扩展的核心概念

💡 在开发扩展的过程中，你需要了解一些核心概念。

  • 激活事件（Activation Events）:定义扩展在什么情况下被激活。例如，onCommand:extension.helloWorld 表示当 extension.helloWorld 命令被执行时激活扩展。常见的激活事件还有 onLanguage（当打开指定语言的文件时激活）、onStartupFinished（VSCode 启动完成后激活）等。
  • 命令（Commands）:扩展可以注册命令，用户可以通过命令面板、菜单、快捷键等方式执行命令。
  • API:VSCode 提供了丰富的 API，扩展可以通过 API 访问 VSCode 的各种功能，例如编辑器操作、窗口操作、文件系统访问、任务管理、调试等。
  • Contribution Points:通过 package.json 文件中的 contributes 字段，扩展可以向 VSCode 贡献各种功能，例如菜单项、设置项、视图、语言支持等。

部署你的扩展到 MarketPlace

📦 当你完成扩展开发并测试通过后，就可以将扩展发布到 VSCode MarketPlace，让全世界的开发者都能使用你的扩展。

  1. 注册 Azure DevOps 组织:发布 VSCode 扩展需要 Azure DevOps 组织。如果你还没有，可以访问 Azure DevOps 官网 注册一个免费组织。

  2. 安装 vsce 工具:vsce（Visual Studio Code Extensions）是 VSCode 官方提供的扩展发布工具。在终端中运行以下命令安装 vsce:

    npm install -g vsce

  3. 创建 Publisher:在 VSCode MarketPlace 上，扩展需要发布到一个 Publisher 下。Publisher 类似于一个开发者或组织账号。你需要在 VSCode MarketPlace Publisher 管理页面 创建一个 Publisher。

  4. 获取 Personal Access Token（PAT）:在 Azure DevOps 组织中，创建一个 Personal Access Token（PAT），用于 vsce 工具的身份验证。创建 PAT 时，需要授予 "Marketplace (Publish)" 权限。

  5. 登录 vsce:在终端中，切换到你的扩展项目根目录，运行 vsce login <your-publisher-name> 命令，并输入你的 PAT。

  6. 发布扩展:运行 vsce publish 命令，vsce 工具会将你的扩展打包并发布到 VSCode MarketPlace。你可以选择发布新版本，或者更新现有版本。

总结

🎉 恭喜你，完成了你的第一个 VSCode 扩展！虽然这只是一个简单的 "Hello World" 示例，但它为你打开了 VSCode 扩展开发的大门。通过学习和实践，你可以利用 VSCode 提供的丰富 API 和贡献点，开发出各种强大的扩展，定制专属于你的 VSCode，提升你的开发效率和体验。快去探索 VSCode 扩展开发的无限可能吧！