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

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	提高可信度，方便用户查看源码。

---

图标与资源

1. 图标文件：
   • 路径：./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. 调试插件

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

---

6. 发布插件

6.1 打包插件

安装 vsce（VS Code Extension Manager）：

npm install -g @vscode/vsce

打包：

vsce package

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

6.2 发布到 Marketplace

1. 注册 Azure DevOps 账号（https://aka.ms/SignupAzureDevOps）。

2. 创建 Personal Access Token (PAT)（需 Marketplace > Manage 权限）。

3. 登录并发布：

   vsce login <publisher-name>
   vsce publish
   

   也可以直接拖到new Extension位置
   

4. 等待审核通过后，插件会出现在 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 插件并分享给全球开发者了！