vscode插件开发指南(一)-理论篇

一、vscode插件是什么，可以做什么

VSCode 全称 Visual Studio Code，是微软出的一款轻量级代码编辑器，免费、开源而且功能强大。它支持几乎所有主流的程序语言的语法高亮、智能代码补全、自定义热键、括号匹配、代码片段、代码对比 Diff、GIT 等特性，支持插件扩展，并针对网页开发和云端应用开发做了优化。软件跨平台支持 Win、Mac 以及 Linux。已经成了越来越多人会选择的代码编辑器。

而vscode插件其实就是类似于一个npm包的vsix文件，其可以实现的功能大概可以分为以下几类：

1）不受限的本地磁盘访问

2）自定义命令、快捷键、菜单

3）自定义跳转、自动补全、悬浮提示

4）自定义插件设置、自定义插件欢迎页

5）自定义WebView

6）自定义左侧功能面板

7）自定义颜色、图标主题

8）新增语言支持（代码高亮、语法解析、折叠、跳转、补全等）

9）Markdown增强

10）其他（比如状态栏修改、通知提示、编辑器控制、git源代码控制、任务定义、Language Server、Debug Adapter等等）

是不是感觉很有意思，当你了解其可以实现哪些功能后，说不定就会找到目前工作中可以提高效率的场景点，接下来我们就来看一下到底怎么来写一个插件。

二、手把手教你写一个插件

2.1 搭建项目

微软官方提供了脚手架，可以帮助你快速搭建一个项目

2.1.1 安装脚手架

// 安装脚手架
npm install -g yo generator-code

2.2.2 使用脚手架创建项目

// 创建项目
yo code

2.2.2.1 创建项目会开启一个交互命令行，会让你选择你想创建的插件类型，目前支持以下几种类型：

1）New Extension (TypeScript) ：ts语法的项目，基础版，内置了hello world的命令

2） New Extension (JavaScript) : js语法的项目，基础版，内置了hello world的命令

3）New Color Theme ：主题项目，内置了主题，可用来自定义主题

4）New Language Support：语言支持项目，内置了语法支持配置，可用来支持特殊语言

5）New Code Snippets：代码片段项目，内置了代码片段配置，可用来配置代码片段，输入触发字符，快速生成代码片段

6）New Keymap：快捷键项目，内置了快捷键配置，可用来自定义快捷键行为

7）New Extension Pack：插件集合项目，内置了插件集合配置，可用于定制插件集，达到快速安装一组插件

8）New Language Pack (Localization)：目前官方文档暂未查到localizations贡献的场景点，待补充

2.2.2.2 接着依次录入插件名称、插件标识、插件描述、是否初始化为git仓库、是否需要webpack打包、使用包管理器（npm/yarn）

2.2.2.3 按照步骤配置后，则会创建好以插件标识(identifier)命名的项目文件夹，里面包含了初始化好的项目文件

2.2.3 以New Extension (TypeScript) 类型讲解一下项目架构

├── .eslintrc.json // eslint配置
├── .vscode // vscode调试配置
|  ├── extensions.json
|  ├── launch.json
|  ├── settings.json
|  └── tasks.json
├── .vscodeignore // 发布忽略内容
├── CHANGELOG.md // 修改日志
├── README.md // 插件发布后，插件主页内容
├── package-lock.json
├── package.json // vscode从这里识别插件贡献点
├── src // 核心源码内容
|  ├── extension.ts // 入口文件
|  └── test //测试文件
├── tsconfig.json // ts配置文件
├── vsc-extension-quickstart.md 
└── webpack.config.js // wepack配置

这里面有几个核心的内容，重点展开讲一下

1）package.json

其中最基本的字段：

这里面比较复杂的就是contributes以及activationEvents的配置，后面实战内容我会重点再实例。

这里以脚手架创建的项目先简单说明一下

  "activationEvents": [
    "onCommand:TypeScript.helloWorld" // 当触发TypeScript.helloWorld命令时启动插件
  ],
  "main": "./dist/extension.js", // 入口文件
  "contributes": {
      "commands": [ // 注册命令
        {
          "command": "TypeScript.helloWorld", // 命令唯一标识，命令名
          "title": "Hello World" // 命令在vcode中的展示标题
        }
      ]
    }

2）入口文件

// ./dist/extension.js"
import * as vscode from 'vscode';
​
// 当插件被激活触发
export function activate(context: vscode.ExtensionContext) {
​
  console.log('Congratulations, your extension "TypeScript" is now active!');
​
  // 调用vscode注册命令API，注册了一个名（命令唯一标识）为TypeScript.helloWorld的命令
  let disposable = vscode.commands.registerCommand('TypeScript.helloWorld', () => {
    // 执行命令，会在右下角展示提示信息
    vscode.window.showInformationMessage('Hello World from TypeScript!');
  });
​
  context.subscriptions.push(disposable);
}
​
// 当插件停用时触发
export function deactivate() {}

3）效果

按下shift+command+p，输入命令标题查询，并点击我们写的命令

vscode右下角会展示提示信息

2.2 如何开发调试

以上面New Extension (TypeScript) 类型举例，借由vscode自带的调试功能，脚手架已经自动为我们配置好了，也就是.vscode目录下的内容

实际上，执行的package.json配置的watch命令

"watch": "webpack --watch"

1）点击运行Run Extension后，会自动打开一个新的vscode界面，此时这个新打开的vscode，会自动安装我们开发的插件，vscode头部会展示[Extension Development Host]

2）此时我们在这个界面调试插件功能，如果需要测试代码，我们可以在此vscode新建一个本地项目或者打开已有项目测试

3）我们写的console相关日志，可以在DEBUG CONSOLE面板中查看，也可以在运行过程中增删断点，如下：

4）如果修改了插件内容，webpack会自动监听并编译

5）打开的[Extension Development Host]的vscode调试页面如何更新修改呢？

• 方法一：断开并重新执行
• 方法二：在此界面按住command+R，则会自动重启并应用，推荐

2.3 如何发布、更新

2.3.1 发布方式

• 方法一：直接把文件夹发给别人，让别人找到vscode的插件存放目录并放进去，然后重启vscode，一般不推荐；
• 方法二：打包成vsix插件，然后发送给别人安装，如果你的插件涉及机密不方便发布到应用市场，可以尝试采用这种方式；
• 方法三：注册开发者账号，发布到官网应用市场，这个发布和npm一样是不需要审核的。

2.3.2 打包

npm i vsce -g
// 打包成vsix文件，项目根目录下会生成一个vsix文件
vsce package

2.3.3 发布到应用市场

1）注册账号发布（这里可以详细阅读blog.haoji.me/vscode-plug…）

• 首先访问 login.live.com/, 登录你的Microsoft账号，没有的先注册一个
• 然后访问： aka.ms/SignupAzure…， 点击继续，默认会创建一个以邮箱前缀为名的组织
• 创建令牌，这里需要注意的是创建令牌成功后你需要本地记下来，因为网站是不会帮你保存的
• 获得个人访问令牌后，使用vsce以下命令创建新的发布者

vsce create-publisher your-publisher-name

• 发布

// 发布
vsce publish
// 增量发布， 版本号：major.minor.patch
vsce publish patch
vsce publish minor
vsce publish major

2）撤销发布

需要注意的是，此操作并不会撤销某一版本的发布，而是直接删除插件，谨慎使用！

vsce unpublish (publisher name).(extension name)

3）用户如何更新（从应用市场安装）

vscode的插件是热更新的模式，用户安装过一次之后，会自动检测是否有新版本并安装，用户基本是无感知，这些检测时机包括：搜索插件、重启vscode等

如果插件发布更新后，vscode自动检测机制还未触发，可手动搜索插件一次或重启一下vscode，需要注意的是，插件更新之后如果想要生效，也是需要重启vscode的

三、参考资料

• vscode官方API
• 翻译文档
• VSCode插件开发全攻略: 这里重点推荐，小白入门神教程