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
  1. 创建新项目：
yo code
  1. 选择配置选项：
    • 选择 “New Extension (TypeScript)”
    • 输入扩展名称
    • 输入标识符
    • 输入描述
    • 选择是否初始化 git 仓库
    • 选择是否安装依赖

方法二：手动创建

  1. 创建项目目录并初始化：
mkdir my-vscode-extension
cd my-vscode-extension
npm init -y
  1. 安装必要依赖：
npm install --save-dev @types/vscode typescript eslint
  1. 创建基础文件结构：
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 的详细用法、参数说明和示例代码。

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!

---

技能提升

本文涉及的技术，这些课程讲得更深入：

posted @ 2026-01-31 20:56  clnchanpin  阅读(301)  评论(0)    收藏  举报