插件开发

VSCode插件开发(一)-最简单的一个插件

VSCode插件开发-最简单的一个插件

Visual Studio Code（VSCode）作为目前最受欢迎的代码编辑器之一，其强大的插件生态系统功不可没。本文将带你从零开始，创建一个简单的VSCode插件，并介绍完整的开发流程。最后我们会完成一个简单的可以在VSCode快速修改图片尺寸的插件并发布到Marketplace。

注意我是在Windows 11的WSL环境下进行开发的，所以一些命令可能会与Windows环境下不同。Windows下WSL开发环境配置

1. 环境搭建

1.1 安装必要工具

首先，确保你的电脑已安装以下工具：

  1. Node.js：VSCode插件开发基于Node.js环境，建议安装LTS版本

    1
    2
    # 下载并安装Node.js LTS版本
    # 访问 https://nodejs.org/ 下载对应操作系统的安装包

  2. Yeoman和VS Code扩展生成器：用于快速创建插件项目模板

    1
    npm install -g yo generator-code

  3. VSCode：当然，你需要安装最新版本的VSCode编辑器

1.2 创建插件项目

打开终端，运行以下命令创建一个新的VSCode插件项目：

1
2
# 创建一个新的插件项目
yo code

运行上述命令后，会出现一系列选项，你可以根据需要进行选择：

1
2
3
4
5
6
7
? What type of extension do you want to create? New Extension (TypeScript)
? What's the name of your extension? 图片快修
? What's the identifier of your extension? letsdoit-image
? What's the description of your extension? 可以vscode中快速的对图片做些修改
? Initialize a git repository? Yes
? Bundle the source code with webpack? No
? Which package manager to use? npm

1.3 项目结构解析

创建完成后，你会得到一个基本的项目结构，主要文件包括：

1
2
3
4
5
6
7
8
9
10
11
12
hello-world/
├── .vscode/           # VSCode配置文件
│   ├── launch.json    # 调试配置
│   ├── tasks.json     # 任务配置
│   └── extensions.json # 推荐扩展
├── src/               # 源代码目录
│   ├── extension.ts   # 插件入口文件
│   └── test/          # 测试文件
├── package.json       # 项目配置和依赖
├── tsconfig.json      # TypeScript配置
├── README.md          # 项目说明
└── CHANGELOG.md       # 更新日志

现在，我们只需要关心两个重要的文件：

  1. src/extension.ts：这是插件的入口文件，包含了插件的生命周期钩子和命令注册。
  2. package.json：项目配置文件，包含了插件的元数据和依赖。

2. 编写我们的第一个插件

2.1 配置命令和菜单

在 package.json 文件中，我们需要配置命令和菜单项：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
    ...
    "contributes": {
        "commands": [
            {
                "command": "letsdoit-image.resizeImage",
                "title": "Resize Image"
            }
        ],
        "menus": {
            "explorer/context": [
                {
                "command": "letsdoit-image.resizeImage",
                "group": "navigation",
                "when": "resourceExtname == .webp || resourceExtname == .jpg || resourceExtname == .jpeg || resourceExtname == .png"
                }
            ]
        }
    },
    ...
}

这里我们申明了一个命令 letsdoit-image.resizeImage，并将其添加到了资源管理器的上下文菜单中。当用户在资源管理器中右键点击图片文件时，会显示 Resize Image 选项。我们在 when 条件中指定了图片文件的扩展名，只有当用户在资源管理器中右键点击图片文件时，才会显示 Resize Image 选项。

注意：这个命令的ID letsdoit-image.resizeImage 必须是全局唯一的，不能与其他插件的命令ID重复。

2.2 注册并实现该命令

打开 src/extension.ts 文件，这是插件的入口文件，包含了插件的生命周期钩子，我们需要在 activate 函数中注册我们的命令 letsdoit-image.resizeImage。让我们修改代码，创建一个简单的命令，当用户在资源管理器中右键点击图片时，会出现Resize Image选项，点击后会提示用户输入图片的宽度，然后将调整后的图片存入一个新文件，并加上了-resized后缀。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

const disposable = vscode.commands.registerCommand('letsdoit-image.resizeImage', async (uri) => {
	let selectedFile = uri;
	if (!selectedFile) {
		selectedFile = vscode.window.activeTextEditor?.document.uri;
	}
	if (!selectedFile) {
		vscode.window.showErrorMessage('Please select an image file.');
		return;
	}

	const widthInput = await vscode.window.showInputBox({
		prompt: 'Enter the width of the image (in pixels)',
		placeHolder: 'e.g. 800',
		validateInput: (value) => {
			if (!value) {
				return 'Please enter a width.';
			}
			if (isNaN(Number(value))) {
				return 'Please enter a valid number.';
			}
			return null;
		}
	});
	if (widthInput) {
		const resizedImagePath = selectedFile.fsPath.replace(/\.(webp|jpg|jpeg|png)$/, '-resized.$1');
		const image = await Jimp.read(selectedFile.fsPath);
		image.resize({ w: Number(widthInput) });
		await image.write(resizedImagePath);
	}

});

context.subscriptions.push(disposable);

这里我们用到了一个第三方库 Jimp，用于处理图片。你需要先安装它：

1
npm install jimp

2.3 调试插件

  1. 在VSCode中打开项目文件夹
  2. 按 F5 或点击”运行 > 启动调试”
  3. 这将打开一个新的VSCode窗口（扩展开发主机）
  4. 在新窗口中，按 Ctrl+Shift+P(或 Cmd+Shift+P on macOS) 打开命令面板
  5. 在资源管理器中右键点击图片文件，选择Resize Image选项
  6. 输入图片的宽度，例如800
  7. 插件会在当前目录下创建一个新文件，文件名加上了-resized后缀，例如image-resized.jpg

3. 打包

3.1 安装打包工具

VSCode插件需要使用 vsce（Visual Studio Code Extension）工具进行打包：

1
npm install -g vsce

3.2 编译TypeScript代码

在打包之前，需要将TypeScript代码编译为JavaScript：

1
npm run compile

3.3 完善基本信息

在 package.json 文件中，确保填写了插件的基本信息，例如版本号、作者、许可证等：

1
2
3
4
5
6
7
8
9
10
11
{
    ...
    "version": "0.0.1",
    "icon": "icon.png",
    "license": "MIT",
    "repository": {
        "type": "git",
        "url": "https://github.com/letsdoit-today/letsdoit-image.git"
    },
    ...
}

3.4 打包插件

运行以下命令将插件打包为 .vsix 文件：

1
vsce package

我们也可以在package.json的scripts中添加一个命令，用于打包插件：

1
2
3
4
5
6
7
{
    ...
    "scripts": {
        "package": "vsce package"
    },
    ...
}

然后运行：

1
npm run package

成功后，你会在项目根目录下看到一个 .vsix 文件，例如 letsdoit-image-0.0.1.vsix。

3.5 本地安装测试

你可以在本地安装并测试打包好的插件：

  1. 在VSCode中，按 Ctrl+Shift+P 打开命令面板
  2. 输入”Extensions: Install from VSIX”
  3. 选择你刚刚创建的 .vsix 文件
  4. 重启VSCode以加载插件

4. 发布到Marketplace

4.1 创建Visual Studio Marketplace账户

  1. 访问 Visual Studio Marketplace
  2. 点击”Sign in”登录或创建新账户，可以用outlook或者hotmail账号登陆
  3. 登录后，访问 发布者管理页面

4.2 创建发布者

如果你是第一次发布插件，需要创建一个发布者：

  1. 在发布者管理页面，点击”Create Publisher”
  2. 填写发布者名称、显示名称和标识符
  3. 记下你的发布者名称，后续会用到

4.3 创建Personal Access Token

  1. 在发布者管理页面，点击”Personal Access Tokens”
  2. 点击”Create New Token”
  3. 输入Token名称（如”VSCode Publishing”）
  4. 选择所有账户（All accessible accounts）
  5. 选择权限范围（至少需要”Marketplace > Publish”）
  6. 复制生成的Token（注意保存，只显示一次）

4.4 登录并发布插件

  1. 在终端中，运行以下命令登录：
1
vsce login <你的发布者名称>

  1. 系统会提示输入Personal Access Token，粘贴上一步创建的Token

  2. 发布插件：

1
vsce publish

4.5 插件审核与发布

  1. 提交后，插件会进入审核流程，通常需要几分钟到几小时
  2. 审核通过后，插件将在Marketplace上可见
  3. 你可以在发布者管理页面查看插件的状态和下载统计

4.6 更新插件

当你需要更新插件时：

  1. 修改 package.json 中的版本号
  2. 重新编译和打包
  3. 再次运行 vsce publish 命令

总结

通过本文，你已经学会了如何从零开始创建一个简单的VSCode插件，包括环境搭建、代码编写、打包和发布到Marketplace的完整流程。下一篇文章将介绍如何创建一个更复杂的插件，用到Webview加React, Tailwindcss, Shadcn, Vite等技术栈构建一个用户友好的插件，实现图片快修的功能。

希望这篇文章能帮助你开启VSCode插件开发之旅！如果你有任何问题或建议，欢迎在评论区留言讨论。