VS Code 插件开发终极指南：从 Hello World 到 Marketplace 上架

码农突围NO.1

已于 2025-04-07 12:40:25 修改

阅读量1.3k

点赞数 26

文章标签： vscode

于 2025-04-07 12:33:34 首次发布

本文链接：https://blog.csdn.net/m0_46833693/article/details/147041162

版权

Visual Studio Code（VS Code）是目前最受欢迎的代码编辑器之一，其强大的扩展性让开发者可以自定义功能。本指南将带你从零开发一个VS Code插件，并详细介绍关键API，最终发布到官方市场。

1. 环境准备

在开始开发前，确保已安装：

Node.js（建议最新LTS版本）
VS Code（最新稳定版）
Yeoman（脚手架工具）和 VS Code Extension Generator（插件生成器）

# pnpm 、npm都可以
pnpm install -g yo generator-code

2. 创建插件项目

使用Yeoman生成插件模板：

yo code

按提示选择：

Extension Type（JavaScript 或 TypeScript）
Extension Name（插件名称）
Description（描述）
Initialize Git（可选）
构建工具选择Esbuild即可

生成的项目结构如下：

├── .vscode/          # VS Code调试配置
├── src/
│   ├── extension.ts  # 插件入口文件
├── package.json      # 插件配置
├── README.md         # 插件文档

项目调试

在extension.ts文件，使用F5，启动调试，会出现新窗口。

使用ts开发，需要先编译

pnpm run compile

编译完成后，F5启动调试

3. 核心开发流程

3.1 `package.json` 配置

{
  "name": "my-extension", // 插件ID（全小写，无空格，需唯一）
  "displayName": "My Awesome Extension", // 插件显示名称
  "description": "A VS Code extension to boost your productivity!", // 描述（Marketplace 展示）
  "version": "1.0.0", // 语义化版本号
  "publisher": "your-name", // 发布者ID（需与Azure DevOps一致）
  "engines": {
    "vscode": "^1.85.0" // 最低支持的VS Code版本
  },
  "icon": "images/icon.png", // 插件图标（128x128像素，PNG格式）
  "license": "MIT", // 开源协议（可选：MIT、Apache-2.0等）
  "keywords": ["productivity", "snippets", "formatting"], // 关键词（便于搜索）
  "categories": ["Formatters", "Snippets"], // 分类（官方允许值：https://code.visualstudio.com/api/references/extension-manifest#categories）
  "main": "./out/extension.js", // 插件入口文件（编译后路径）
  "activationEvents": [
    "onCommand:myExtension.helloWorld", // 按命令激活
    "onLanguage:javascript", // 打开JS文件时激活
    "workspaceContains:package.json" // 工作区包含特定文件时激活
  ],
  "contributes": {
    "commands": [
      {
        "command": "myExtension.helloWorld",
        "title": "Hello World",
        "category": "Extension" // 命令分类（可选）
      }
    ],
    "keybindings": [
      {
        "command": "myExtension.helloWorld",
        "key": "ctrl+shift+h", // 快捷键绑定
        "mac": "cmd+shift+h",
        "when": "editorTextFocus" // 触发条件
      }
    ],
    "menus": {
      "editor/context": [
        {
          "command": "myExtension.helloWorld",
          "group": "navigation", // 右键菜单分组
          "when": "editorLangId == javascript" // 仅JS文件显示
        }
      ]
    },
    "configuration": {
      "title": "My Extension",
      "properties": {
        "myExtension.enableFeature": {
          "type": "boolean",
          "default": true,
          "description": "Enable/disable the extension's main feature."
        }
      }
    }
  },
  "scripts": {
    "vscode:prepublish": "npm run compile", // 发布前编译
    "compile": "tsc -p ./", // TypeScript编译（如果是JS可省略）
    "watch": "tsc -watch -p ./", // 监听模式编译
    "lint": "eslint src --ext .ts", // 代码检查（可选）
    "package": "vsce package" // 本地打包
  },
  "devDependencies": {
    "@types/vscode": "^1.85.0", // VS Code API类型定义
    "@types/node": "^20.0.0", // Node.js类型定义
    "typescript": "^5.0.0", // TypeScript编译器
    "eslint": "^8.0.0" // 代码检查工具（可选）
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/your-name/my-extension.git" // 源码仓库
  },
  "bugs": {
    "url": "https://github.com/your-name/my-extension/issues" // 问题反馈链接
  },
  "homepage": "https://github.com/your-name/my-extension#readme" // 项目主页
}

关键字段说明

字段	作用
`icon`	插件图标（需放在项目根目录的 `images` 文件夹下，推荐 128x128 PNG）。
`categories`	官方分类（如 `Programming Languages`、`Linters`、`Themes` 等）。
`activationEvents`	控制插件何时被加载（避免启动时占用资源）。
`contributes`	注册命令、菜单、快捷键、配置项等扩展能力。
`configuration`	定义插件的可配置参数（用户可在设置中修改）。
`repository`	提高可信度，方便用户查看源码。

图标与资源

图标文件：

路径：./images/icon.png（推荐 128x128 像素，透明背景PNG）。

示例：

project-root/
  ├── images/
  │   └── icon.png
  ├── package.json
  └── src/

3.2 插件入口（`extension.ts`）

默认生成的 extension.ts 包含一个简单的命令示例：

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
  console.log('插件已激活！');
  
  // 注册命令
  const disposable = vscode.commands.registerCommand('myExtension.helloWorld', () => {
    vscode.window.showInformationMessage('Hello World from My Extension!');
  });

  context.subscriptions.push(disposable);
}

export function deactivate() {
  console.log('插件已卸载');
}

activate：插件启动时执行。
deactivate：插件卸载时执行（可选）。

4. 关键 VS Code API 介绍

4.1 `vscode.window`（窗口交互）

显示信息提示：

vscode.window.showInformationMessage('Hello!');
vscode.window.showErrorMessage('Error!');

输入框：

const name = await vscode.window.showInputBox({ prompt: 'Enter your name' });

状态栏：

const statusBarItem = vscode.window.createStatusBarItem(vscode.StatusBarAlignment.Right, 100);
statusBarItem.text = "Ready";
statusBarItem.show();

4.2 `vscode.workspace`（文件与编辑器操作）

获取当前文件：

const editor = vscode.window.activeTextEditor;
const text = editor?.document.getText();

监听文件变化：

vscode.workspace.onDidChangeTextDocument((e) => {
  console.log('文件内容变化:', e.document.getText());
});

4.3 `vscode.commands`（自定义命令）

注册命令：

vscode.commands.registerCommand('myExtension.doSomething', () => {
  // 执行逻辑
});

执行已有命令：

vscode.commands.executeCommand('editor.action.formatDocument');

4.4 `vscode.languages`（语言支持）

代码补全：

vscode.languages.registerCompletionItemProvider('javascript', {
  provideCompletionItems() {
    return [new vscode.CompletionItem('console.log')];
  }
});

5. 调试插件

按 F5 或点击 Run > Start Debugging，VS Code 会打开一个扩展开发窗口。
在调试窗口按 Ctrl+Shift+P 输入你的命令（如 Hello World）测试功能。

6. 发布插件

6.1 打包插件

安装 vsce（VS Code Extension Manager）：

npm install -g @vscode/vsce

打包：

vsce package

生成 .vsix 文件，可用于本地安装或发布。

6.2 发布到 Marketplace

注册 Azure DevOps 账号（https://aka.ms/SignupAzureDevOps）。
创建 Personal Access Token (PAT)（需 Marketplace > Manage 权限）。
登录并发布：
```
vsce login <publisher-name>
vsce publish
```
也可以直接拖到new Extension位置
等待审核通过后，插件会出现在 VS Code Marketplace。

7. 进阶优化

添加图标：在 package.json 中配置 icon 字段。
国际化支持：使用 package.nls.json 提供多语言支持。
测试：使用 vscode-test 进行单元测试。

8. 总结

开发流程：yo code 创建项目 → 编写逻辑 → 调试 → 发布。
关键API：vscode.window、vscode.workspace、vscode.commands、vscode.languages。
发布：vsce package 打包，vsce publish 发布。

🚀 现在，你可以开发自己的 VS Code 插件并分享给全球开发者了！