🔜想开发 vscode 插件却不知从何入手?超速入门,助力你弹射起步

309 阅读10分钟

前言

哈喽大家好!我是 嘟老板。作为 vscode 重度用户,一直以来都是处于用的阶段,恰好最近在开发自动切换项目 node 版本的插件,就顺便整理一下 vscode 插件从准备到发布的完整流程,供同样有需求,但不知从何入手的小伙伴们参考。

阅读本文您将收获:

  1. vscode 插件应用场景。
  2. vscode 开发过程,从构建、编码、运行、调试到最终发布整个过程。
  3. 等等...

喜欢实战的小伙伴,可移步 💯What?维护新老项目频繁切换node版本太恼火?开发一个vscode插件自动切换版本,从此告别烦恼

本文内容默认小伙伴已了解 VSCode,不会对其做过多介绍。

简介

什么是 vscode 插件?

VSCode 是一款高度可扩展的编辑器,我们可以通过插件对 VSCode 进行定制和增强。

打开 VSCode 编辑器,在左侧工具栏可以查看和安装可用的插件。

image.png

实际上,VSCode 的许多核心功能都是作为插件构建的。

若想查找更多已发布的插件,可前往插件市场

vscode 插件能做些什么?

几乎 VSCode 所有的部分都可以通过插件进行增强,包括但不限于以下几种场景:

  • 主题

    • 颜色主题:创建和应用自定义的颜色主题,改变编辑器、侧边栏、状态栏等界面元素的颜色。
    • 文件图标主题:自定义文件和文件夹的图标,使项目结构更加直观和个性化。
  • 扩展工作台

    • 自定义组件:在 VSCode 的 UI 中添加新控件,如按钮、输入框、下拉菜单等。
    • 自定义视图:创建新视图来展示特定的信息或工具,如项目管理器、数据查看器等。
  • Webview

    • 创建Webview:使用 HTML、CSS 和 JavaScript 创建自定义网页,在 VSCode 中以 Webview 形式展示。
    • 交互式内容:创建交互式的用户界面,如图表、动态数据展示等。
  • 语言扩展概览 :支持新的编程语言。

    • 语法高亮:为代码添加语法高亮,以更容易地阅读和编写代码。
    • 代码补全:提供智能提示和代码补全功能,提高编码效率。
    • 代码导航:如跳转到定义、查找引用等。
    • 代码格式化:确保代码风格一致。
  • 调试器扩展 :支持特定运行时的调试。

    • 断点管理:设置断点,以在调试时暂停程序执行。
    • 变量查看:在调试过程中查看和修改变量的值。
    • 调用堆栈:展示调用堆栈,帮助理解程序的执行流程。
    • 调试控制:提供控制程序执行的命令,如继续、单步、跳出等。
  • 其他...

开发过程,创建-调试-集成测试-发布

本文以 auto-nvm 项目为例,演示过程,至于 auto-nvm 插件的内部逻辑不做介绍。

初始化插件项目

初始化项目需要用到 Yeoman 和 vscode 插件生成器 两个工具。

  1. 全局安装 Yeoman 和 vscode 插件生成器

终端输入以下命令,回车执行:

npm install --global yo generator-code
  1. 初始化项目

终端输入以下命令,回车执行:

yo code

若考虑后续不会再使用 Yeoman 和 vscode 插件生成器,不想全局安装,可通过终端执行以下命令来初始化:

npx --package yo --package generator-code -- yo code

结合个人需求,完成问答环节,即可完成创建。

image.png

工具会自动安装相关依赖,执行完成后直接 vscode 打开即可。

image.png

项目结构介绍

初始化的插件项目包含以下结构:

image.png

重点文件介绍

挑几个重点文件说一说:

  • .vscode

    • extensions.json
    • launch.json
    • tasks.json
  • src

    • test
    • extension.ts
  • .vscode-test.mjs

  • .esbuild.js

  • package.json

    "contributes": {
        "commands": [
          {
            "command": "auto-nvm.helloWorld",
            "title": "Hello World"
          }
        ]
    },
    
  • 其他

extension.ts 逻辑介绍

由上述介绍可以看出,插件的核心逻辑都是在 src/extension.ts 中编写,所以我们先来看看初始化的插件逻辑是怎么样的,以便理解后续的操作步骤:

import * as vscode from 'vscode';

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

export function deactivate() {}

除去注释,以上就是 src/extension.ts 所有的代码了,内容很少是不是,我们来简单分析一下。

  1. activatedeactivate

    extension.ts 道出了两个函数,分别是 activatedeactivate,这并不是随便导出的,而是 vscode 插件指定的导出函数。其中,activate 函数会在插件激活时(首次执行命令时会激活扩展程序)调用;deactivate 函数会在插件停用时调用。

  2. const disposable = vscode.commands.registerCommand('auto-nvm.helloWorld', () => {})

    借助 vscode.commands.registerCommand api 注册 helloWorld 命令及执行函数。

    上面介绍 package.json 时有提到 contributes.commands 配置项可以配置插件提供的执行命令,比如:

    "contributes": {
        "commands": [
            {
                "command": "auto-nvm.helloWorld",
                "title": "Hello World"
            }
        ]
    },
    

    可以发现 command 配置和这里 registerCommand api 的第一个参数一致,也就是说这段代码就是为 Hello World 命令注册具体的执行逻辑。

  3. vscode.window.showInformationMessage('Hello World from auto-nvm!');

    借助 vscode.window.showInformationMessage api 弹出提示消息。

    当我们通过快捷键(Ctrl+Shift+P(Windows)/Cmd+Shift+P(Mac))执行 Hello World 命令时,会在 vscode 编辑器右下角弹出提示信息。

  4. context.subscriptions.push(disposable);

    context 是 activate 函数的参数,提供了插件运行时的上下文信息和一些实用工具。context.subscriptions 是一个数组,用来管理插件所有的订阅(如事件监听器、定时器等),确保插件的资源被适当管理和释放。这里就是将 disposable 命令订阅管理起来。

运行

1. 打开测试窗口

快捷键 F5(或 fn + F5),会打开一个新的 vscode 编辑器窗口,该窗口会加载本地 auto-nvm 插件,可以正常执行 auto-nvm 提供的命令。

若插件逻辑涉及到代码,可以在测试窗口内打开相关代码工程。
比如 auto-nvm 需要项目包含 .nvmrc 文件,所以调试时会在测试窗口打开一个 vue 项目。

2. 执行命令

快捷键(Ctrl+Shift+P(Windows)/Cmd+Shift+P(Mac)),会在窗口展示可执行的命令,搜索 Hello World,点击或回车确认。

image.png

会发现,编辑器右下角弹出提示信息 “Hello World from auto-nvm!”

image.png

3.断点调试

vscode 内置了调试功能,只需要在代码左侧空白区域点击一下鼠标,便可完成断点设置。

image.png

后续执行到该断点时,vscode 会暂停执行。

image.png

另外,我们可以在编辑器下方-「调试控制台」查看执行日志:

image.png

多说一嘴

简单介绍下上面一排调试按钮的执行效果:

  1. image.png:继续,执行当前断点的后续代码,知道遇到下一个断点时停止。

  2. image.png:单步跳过(也叫逐过程),跳过当前断点,执行当前文件的下一行代码。若下一行代码调用了其他文件或函数,会直接执行完成,不会进入。

  3. image.png:单步调试,跳过当前断点,执行下一行代码。若下一行代码调用了其他文件或函数,会进入。

  4. image.png:单步跳出,当调试陷入某个循环时,跳过当前循环。

  5. image.png:重新启动调试。

  6. image.png:关闭调试。

集成测试

什么是集成测试?集成测试有了 vscode 实例的参与,相对于单元测试来说,是跟进一步的测试。

vscode 运行集成测试时,会启动一个叫做 “扩展开发主机(Extension Development Host)” 的 vscode 实例,以保证可以完全访问 vscode 提供的 api。

使用 Yeoman 和 vscode 插件生成器 初始化的插件工程,默认创建了集成测试相关文件,即上文介绍过的 src/test 目录。

在插件工程控制台执行 pnpm test 命令,即可运行集成测试。该命令会执行以下才操作:

  • 下载并解压最新版本的 vscode。
  • 运行 Mocha 工具执行集成测试。

以下是执行日志,感兴趣的小伙伴可以自己操作瞅瞅:

image.png

注:
Mocha 是一个测试框架,可以编写和运行测试用例。vscode 扩展测试运行器脚本指定 Mocha 来编写和执行测试,以确保扩展的功能按预期工作。

发布

插件验证无误后,便可着手发布了,只有发布之后,才能在 vscode 插件市场查找、下载并安装到编辑器。

准备工作

package.json

需要在 package.json 中配置以下几个属性:

  • displayName: 插件展示名称,默认已配置。
  • description: 插件描述。
  • categories: 插件分类,默认 Other
  • keywords: 关键词。
  • publisher: 发布者 Name,详细看下文「创建 publisher」部分。
  • icon: 插件图标。
  • repository: 代码仓库,若有。

分别对应以下展示位置:

image.png

创建组织
  1. 登录 Azure DevOps

  2. 选择“ 新建组织”。

注:
若首次登录,原本无任何组织,登录成功后会首先跳转“新建组织”页面。

image.png

  1. 确认信息,然后选择“ 继续”。

image.png

填写组织名称和验证码,点击 continue 即可创建。

组织创建完成!!!

创建 Access Token
  1. 在上一步创建的组织主页,点击右上角的用户设置弹窗,选中 Personal access tokens

image.png

  1. 点击 New Token,打开创建 token 弹窗。

image.png

  1. 创建 token 弹窗中,填入必要信息,点击 create 即可。

image.png

注:
可以在 "Scopes" 处自定义当前 token 作用域,勾选 “Custom defined” 即可。我为了省事,直接勾选了 "Full access"

Person Access Token 创建完成。

注意!!!生成的 token 要手动复制保存,否则无法再次查看。

创建 publisher

publisher 是将插件发布到 vscode 市场的身份。每个插件都需要在其 package.json 文件中包含 publisher 标识符。

{
    "publisher": "SuperYing",
}
  1. 点击前往 vscode 市场发布者管理页面,使用上一步创建 Access Token 的 Microsoft 账号登录。

  2. 点击 “Create publisher”。

image.png

  1. 创建 publisher 页面,填写必需的 Name 和 ID,其他内容按需填写。

image.png

插件发布后,Name 和 ID 分别用于以下位置:

image.png

  1. 点击 create 即可。

publisher 创建完成!!!

打包发布

发布插件需要一个命令行工具 - vsce(Visual Studio Code Extensions),用来打包、发布和管理插件。

安装 vsce

终端输入以下命令,回车执行全局安装。

npm install -g @vscode/vsce
登录

使用上一步创建的 publisher 登录,格式如下:

vsce login <publisher id>

登录时会要求输入 AccessToken,将之前保存的 Token 复制过来即可。

image.png

发布

终端执行 vsce publish 即可。

image.png

个人踩坑

使用 pnpm 作为包管理器打包时会报错,一堆依赖缺失。

image.png

删除 node_modules 目录,重新使用 npm i 安装依赖即可。

结语

本文重点介绍了 vscode 插件的应用场景,以及从前期准备到测试再到最终发布的整个流程,旨在帮助同学们快速入门 vscode 插件开发。希望对您有所帮助!

文中提到的 auto-nvm 插件发布到插件市场,且迭代多个版本,希望有同样需要的小伙伴们安装使用、多多反馈,感谢。

如您对文章内容有任何疑问或想深入讨论,欢迎评论区留下您的问题和见解。

技术简而不凡,创新生生不息。我是 嘟老板,咱们下期再会。


往期干货