VSCode 插件开发完整指南：从零到发布

VSCode 插件开发完整指南：从零到发布

前言

VSCode 作为当今最受欢迎的代码编辑器之一，其强大的扩展生态系统为开发者提供了无限的可能性。本文将带你从零开始，学习如何使用 TypeScript 开发一个 VSCode 插件，并最终发布到 Marketplace。

一、开发环境准备

必需工具

• Node.js：建议使用 LTS 版本（16.x 或更高）
• npm 或 yarn：包管理工具
• VSCode：最新版本
• TypeScript：用于插件开发的主要语言

VSCode 插件开发 SDK

开发 VSCode 插件主要需要以下核心依赖：

{
  "devDependencies": {
    "@types/vscode": "^1.74.0",
    "@typescript-eslint/eslint-plugin": "^5.45.0",
    "@typescript-eslint/parser": "^5.45.0",
    "eslint": "^8.28.0",
    "typescript": "^4.9.4"
  }
}

核心 SDK 说明：

• @types/vscode：VSCode API 的 TypeScript 类型定义，这是最重要的依赖
• typescript：TypeScript 编译器
• eslint 相关包：代码质量检查工具

二、项目创建

方法一：使用官方脚手架（推荐）

1. 安装 Yeoman 和 VSCode 扩展生成器：

npm install -g yo generator-code

2. 创建新项目：

yo code

3. 选择配置选项：
   • 选择 "New Extension (TypeScript)"
   • 输入扩展名称
   • 输入标识符
   • 输入描述
   • 选择是否初始化 git 仓库
   • 选择是否安装依赖

方法二：手动创建

1. 创建项目目录并初始化：

mkdir my-vscode-extension
cd my-vscode-extension
npm init -y

2. 安装必要依赖：

npm install --save-dev @types/vscode typescript eslint

3. 创建基础文件结构：

   my-extension/
   ├── src/
   │ └── extension.ts
   ├── package.json
   ├── tsconfig.json
   └── README.md

三、TypeScript 开发核心概念

1. 扩展入口点

每个 VSCode 扩展都有两个核心函数：

import * as vscode from 'vscode';

// 扩展激活时调用
export function activate(context: vscode.ExtensionContext) {
    console.log('扩展已激活');
    
    // 注册命令
    let disposable = vscode.commands.registerCommand('extension.helloWorld', () => {
        vscode.window.showInformationMessage('Hello World!');
    });
    
    context.subscriptions.push(disposable);
}

// 扩展停用时调用
export function deactivate() {
    console.log('扩展已停用');
}

2. VSCode API 核心模块

• vscode.window：窗口相关操作（显示消息、输入框等）
• vscode.workspace：工作区操作（文件、配置等）
• vscode.commands：命令注册和执行
• vscode.languages：语言服务相关
• vscode.extensions：扩展管理

📚 API 详细文档

所有 VSCode API 的详细文档可以在以下位置找到：

• 官方 API 文档 ：https://code.visualstudio.com/api/references/vscode-api
• 扩展开发指南 ：https://code.visualstudio.com/api
• TypeScript 类型定义 ：在项目中安装 @types/vscode 后，可以通过 IDE 的智能提示查看完整的类型定义和方法说明

建议在开发过程中经常查阅官方文档，里面包含了每个 API 的详细用法、参数说明和示例代码。

3. 常用开发模式

// 获取当前活动编辑器
const editor = vscode.window.activeTextEditor;
if (editor) {
    const document = editor.document;
    const selection = editor.selection;
    
    // 获取选中的文本
    const selectedText = document.getText(selection);
    
    // 替换文本
    editor.edit(editBuilder => {
        editBuilder.replace(selection, '新文本');
    });
}

四、配置文件详解

package.json 关键配置

{
  "name": "my-extension",
  "displayName": "My Extension",
  "description": "扩展描述",
  "version": "0.0.1",
  "engines": {
    "vscode": "^1.74.0"
  },
  "categories": ["Other"],
  "activationEvents": [
    "onCommand:extension.helloWorld"
  ],
  "main": "./out/extension.js",
  "contributes": {
    "commands": [{
      "command": "extension.helloWorld",
      "title": "Hello World"
    }]
  },
  "scripts": {
    "vscode:prepublish": "npm run compile",
    "compile": "tsc -p ./",
    "watch": "tsc -watch -p ./"
  }
}

tsconfig.json 配置

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "ES2020",
    "outDir": "out",
    "lib": ["ES2020"],
    "sourceMap": true,
    "rootDir": "src",
    "strict": true
  },
  "exclude": ["node_modules", ".vscode-test"]
}

五、调试与测试

本地调试

1. 在 VSCode 中打开项目
2. 按 F5 启动调试
3. 会打开一个新的 "Extension Development Host" 窗口
4. 在新窗口中测试你的扩展功能

单元测试

import * as assert from 'assert';
import * as vscode from 'vscode';

suite('Extension Test Suite', () => {
    test('Sample test', () => {
        assert.strictEqual(-1, [1, 2, 3].indexOf(5));
        assert.strictEqual(0, [1, 2, 3].indexOf(1));
    });
});

六、打包与发布

安装发布工具

npm install -g vsce

创建发布者账号

1. 访问 Azure DevOps
2. 创建个人访问令牌（PAT）
3. 在 VSCode Marketplace 创建发布者

发布流程

# 登录
vsce login <publisher-name>

# 打包
vsce package

# 发布
vsce publish

七、实战案例：VSCode Variable Formatter

项目介绍

VSCode Variable Formatter 是一个用于快速转换变量命名风格的扩展，支持以下转换：

• camelCase（驼峰命名）
• PascalCase（帕斯卡命名）
• snake_case（下划线命名）
• kebab-case（短横线命名）
• SCREAMING_SNAKE_CASE（大写下划线命名）

核心实现思路

// 命名转换核心逻辑
export class VariableFormatter {
    static toCamelCase(str: string): string {
        return str.replace(/[-_\s]+(\w)/g, (_, letter) => letter.toUpperCase())
                 .replace(/^[A-Z]/, letter => letter.toLowerCase());
    }
    
    static toPascalCase(str: string): string {
        return str.replace(/[-_\s]+(\w)/g, (_, letter) => letter.toUpperCase())
                 .replace(/^[a-z]/, letter => letter.toUpperCase());
    }
    
    static toSnakeCase(str: string): string {
        return str.replace(/([A-Z])/g, '_$1')
                 .replace(/[-\s]+/g, '_')
                 .toLowerCase()
                 .replace(/^_/, '');
    }
    
    static toKebabCase(str: string): string {
        return str.replace(/([A-Z])/g, '-$1')
                 .replace(/[_\s]+/g, '-')
                 .toLowerCase()
                 .replace(/^-/, '');
    }
}

使用方式

1. 选择要转换的变量名
2. 打开命令面板（Cmd+Shift+P 或 Ctrl+Shift+P）
3. 搜索 "Format Variable" 相关命令
4. 选择目标命名风格
5. 自动替换为转换结果

项目特色

• 🚀 快速转换：一键转换多种命名风格
• 🎯 智能识别：自动识别当前命名风格
• 📝 批量处理：支持多选文本同时转换
• ⚡ 高性能：基于正则表达式的高效转换算法

源码地址

项目已开源，欢迎查看源码和贡献：
GitHub : https://github.com/zeawhy/vscode-variable-formatter

八、最佳实践与建议

1. 代码质量

• 使用 TypeScript 严格模式
• 配置 ESLint 和 Prettier
• 编写单元测试
• 使用 Git 进行版本控制

2. 用户体验

• 提供清晰的命令名称
• 添加快捷键支持
• 实现撤销/重做功能
• 提供配置选项

3. 性能优化

• 避免阻塞主线程
• 使用异步操作
• 合理使用缓存
• 优化正则表达式

4. 文档完善

• 详细的 README
• 功能演示 GIF
• 更新日志 CHANGELOG
• 用户反馈渠道

九、常见问题与解决方案

Q1: 扩展无法激活

解决方案 ：检查 package.json 中的 activationEvents 配置是否正确。

Q2: TypeScript 编译错误

解决方案 ：确保 @types/vscode 版本与 engines.vscode 版本兼容。

Q3: 发布失败

解决方案：检查 PAT 权限，确保包含 Marketplace 管理权限。

结语

VSCode 插件开发是一个既有趣又实用的技能，通过 TypeScript 的强类型支持，我们可以构建出功能强大且稳定的扩展。希望本文能帮助你快速入门 VSCode 插件开发，并创造出属于自己的优秀扩展。

如果你对 VSCode Variable Formatter 感兴趣，欢迎访问项目仓库，给个 Star 支持一下！

项目地址 : https://github.com/zeawhy/vscode-variable-formatter

---

Happy Coding! 🚀