VSCode插件从0到1开发与发布完整实战

摘要：本文手把手带你完成 VSCode 插件开发，包含环境搭建、脚手架生成项目、核心配置讲解、本地调试、打包 vsix、发布插件市场、常见踩坑汇总。适合前端开发者快速上手 VSCode 扩展开发。社区中文镜像扩展 API | Visual Studio Code 扩展 API - VSCode · AI 代码编辑器

前言

VSCode 强大的根源来自于海量第三方插件。我们可以基于官方 API 开发自定义插件，实现命令、右键菜单、代码补全、侧边栏、文本处理等能力。整个开发基于 TypeScript，打包后可以本地分发.vsix离线包，也可以发布到官方插件市场给全球开发者使用。

整体流程总览 环境准备 → 脚手架生成项目 → 理解核心文件package.json与extension.ts → F5 本地调试 → 打包生成.vsix离线包 → 本地安装验证 → 创建 Publisher 与 PAT 令牌 → vsce发布市场 → 管理后台查看插件。

编写和发布插件完整流程

一、环境准备

需要提前安装好 Node.js（推荐 18 + 版本）、npm。全局安装两个工具：

yo generator‑code：官方脚手架，一键生成插件模板
@vscode/vsce：打包、发布插件的命令行工具

css 复制代码

npm install -g yo generator-code
npm install -g @vscode/vsce

二、脚手架初始化插件项目

终端执行脚手架命令：

css 复制代码

yo code

交互式选择，新手直接选择New Extension (TypeScript)，依次填写：

Extension Name：插件名称
Identifier：插件唯一 ID，小写 + 横杠，不能中文、大写、空格
Description：插件描述
开启 TS 严格校验：Yes
是否初始化 git：Yes
是否使用 webpack：简单插件选 No

生成完成，进入目录，用 vscode 打开项目

bash 复制代码

cd my‑demo‑plugin
code .

目录结构说明

perl 复制代码

my‑demo‑plugin/
├── package.json         # ⭐最重要，插件清单，定义命令、激活事件、元信息
├── src/
│   └── extension.ts     # ⭐插件主入口，业务逻辑全部写在这里
├── tsconfig.json        # TS编译配置
├── README.md            # 插件市场展示文档
└── .vscode/             # 调试配置

三、核心文件讲解

1. package.json（插件清单）

VSCode 完全依靠这个文件识别插件能力，包含元信息、激活事件、贡献点（命令、菜单、配置）。

重点字段说明：

json 复制代码

{
  "name": "my-demo-plugin",
  "displayName": "我的演示插件",
  "version": "0.0.1",
  "publisher": "mypublisher", //发布者ID，发布市场必填，和后台保持一致
  "engines": {
    "vscode": "^1.85.0" //最低兼容vscode版本
  },
  "main": "./out/extension.js", //ts编译之后的入口文件
  "activationEvents": [
    "onCommand:my-demo-plugin.helloWorld"
  ],
  "contributes": {
    "commands": [
      {
        "command": "my-demo-plugin.helloWorld",
        "title": "HelloWorld演示命令"
      }
    ]
  },
  "scripts": {
    "compile": "tsc -p ./",
    "watch": "tsc -watch -p ./"
  }
}

activationEvents：插件激活时机 ，不建议填*（vscode 启动就加载，拖慢编辑器）；一般绑定命令事件。
contributes：贡献点，向 VSCode 注册命令、右键菜单、设置项、快捷键、侧边栏视图。
command ID：前后必须完全一致，大小写敏感 ，package.json和代码中注册命令 ID 要一模一样。

2. src/extension.ts（业务入口）

两个导出函数：

activate()：插件被激活的时候执行，注册命令、监听事件；
deactivate()：插件被卸载、禁用时执行，做资源清理。

示例最小 demo 代码：

javascript 复制代码

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
  //注册命令，ID与package.json完全匹配
  const disposable = vscode.commands.registerCommand(
    'my-demo-plugin.helloWorld',
    () => {
      vscode.window.showInformationMessage('Hello VSCode插件！');
    }
  );
  context.subscriptions.push(disposable);
}

export function deactivate() {}

四、本地调试插件

在当前插件项目，直接按下F5；
会弹出全新的【扩展开发宿主】VSCode 窗口；
在新窗口按快捷键 Ctrl+Shift+P，输入我们注册命令：HelloWorld演示命令；
执行，弹出提示框，代表插件运行成功。

开发技巧：开启监听编译 npm run watch，修改 ts 代码自动编译，不需要反复手动npm run compile。快捷键Shift+F5停止调试。

五、打包生成离线 vsix 包

不需要发布市场，可以直接打包.vsix文件，分发给同事本地安装。

perl 复制代码

#编译ts
npm run compile
#打包生成vsix
vsce package

项目根目录输出文件：my‑demo‑plugin‑0.0.1.vsix。

本地安装 vsix 包测试

两种方式：

VSCode 扩展面板 →右上角三个点 →Install from VSIX...，选择文件安装；
命令行安装：

css 复制代码

code --install-extension ./my-demo-plugin-0.0.1.vsix

发布前一定要本地安装 vsix 包测试，避免线上发布之后才发现 bug。

六、发布插件到 VSCode 官方市场

前置准备

微软账号，或者 Github 账号登录marketplace.visualstudio.com/manage
创建Publisher发布者 ID（一旦创建不能修改，package.json 的 publisher 字段必须和这个 ID 完全一致）
微软账号、或者 Github 账号首次登录 Azure DevOps Services | Microsoft Azure。打开 Azure DevOps，创建个人访问令牌 PAT，权限勾选Marketplace → Manage，复制保存 token，只显示一次。

终端登录发布者

bash 复制代码

vsce login 你的PublisherID
#按提示粘贴刚才复制的PAT token

执行发布

复制代码

vsce publish

注意：每一次发布，package.json的version版本号必须递增，不能重复发布同一个版本号。

直接在官方插件市场中通过网页端将自己本地打包生成的 vsix 包直接上传进行发布。

七、如何找到自己已经发布的插件

管理后台（立刻可见） 访问：marketplace.visualstudio.com/manage，登录同一个微软账号，左侧选择 Publisher，即可看到全部插件。点击View Extension打开插件公开页面，复制链接分享给别人。

完整插件 URL 格式： https://marketplace.visualstudio.com/items?itemName=publisherID.插件name

网页市场搜索：访问marketplace.visualstudio.com/vscode，搜索插件 ID 或者展示名称。
VSCode 编辑器扩展面板（Ctrl+Shift+X）搜索完整插件 ID。

⚠️重要提示：

vsce publish显示发布成功，不代表立刻全网搜索得到，CDN 缓存，一般等待 3‑10 分钟。管理后台已经出现插件就是发布成功，只是全网同步延迟。

八、插件迭代更新流程

修改业务代码，修复 bug 或者新增功能；
修改package.json中version版本号，遵循语义化版本major.minor.patch；
npm run compile；
本地打包vsce package，安装 vsix 包做本地验证；
vsce publish直接发布新版本；
用户 VSCode 会收到插件更新提示。

九、高频踩坑汇总

现象	解决方案
命令面板找不到注册的命令	检查`package.json`和代码中 command ID 完全一致；检查`activationEvents`配置；F5 重启调试宿主窗口。
vsce package 打包报错	`name`必须小写 + 横杠，不能中文、大写、空格；version 严格语义化版本`x.y.z`；icon 图片路径真实存在，不支持 svg 图标。
发布成功，VSCode 搜不到插件	等待 CDN 缓存 3‑15 分钟，先看管理后台；确认登录的微软账号、PAT token、publisher 三者匹配。
插件不会激活	不要随便写`"activationEvents":["*"]`，绑定对应的 onCommand 事件，按需加载提升性能。
README 图片不显示	README 内图片链接必须为 https，不支持本地相对路径图片。

十、两种分发模式对比

模式	说明	适用场景
离线`.vsix`包	不需要微软市场账号，手动发给别人本地安装	企业内部自用插件，不对外公开
发布 Marketplace 市场	全球开发者可以搜索安装下载，有下载统计评分	开源工具插件，对外分享

写在最后

VSCode 插件能力非常强大，除简单命令外，还可以开发自定义侧边栏 Webview、代码提示补全、语法校验、文件处理等复杂功能。官方文档地址：code.visualstudio.com/api。

拓展：插件开发中常用 API：弹窗消息vscode.window、编辑器操作vscode.window.activeTextEditor、配置项contributes.configuration、右键菜单contributes.menus。