从 0 到 1 学会 VS Code 插件开发与发布：手把手实战教程（适合新手练习）

很多同学平时天天用 VS Code，但一提到“开发插件”，第一反应通常都是：

• 感觉门槛很高
• 不知道从哪里开始
• 做出来了也不会发布

其实，VS Code 插件开发没有想象中那么难。

如果你有一点 JavaScript 或 TypeScript 基础，那么完全可以在 1~2 小时内做出自己的第一个插件，并且把它发布到 VS Code Marketplace。

这篇文章我会带你完整走一遍整个流程，尽量按照“边学边练”的方式来写。你不需要先懂很多原理，只需要跟着步骤做一遍，就能真正跑通：

• 环境搭建
• 项目创建
• 本地调试
• 功能开发
• 插件打包
• 正式发布

对于初学者来说，最重要的不是一下子学很多概念，而是先把整个链路跑通一次。

---

一、为什么值得学 VS Code 插件开发？

先说一个很现实的问题：为什么要学这个？

因为你平时在 VS Code 里用到的很多能力，本质上都是插件提供的。

比如：

• 代码高亮
• 自动补全
• Git 增强
• 格式化工具
• 右键菜单命令
• 状态栏按钮
• 自定义侧边栏
• AI 编程助手

也就是说，学会 VS Code 插件开发之后，你不只是“会写一个小工具”，而是具备了把自己的开发习惯、工作流、想法做成产品的能力。

如果以后你想：

• 给自己做提效工具
• 给团队做内部开发辅助插件
• 发布到插件市场给别人使用
• 把插件项目写进简历或作品集

那么这项技能都很有价值。

---

二、开发前需要准备什么环境？

建议先安装下面这几个工具：

• VS Code
• Node.js，建议使用 18+
• Git

安装完成后，可以打开终端检查一下版本：

node -v
npm -v
git --version

如果都能正常输出版本号，说明基础环境已经没问题了。

为什么需要 Node.js？

因为 VS Code 插件的开发工具链、脚手架、打包发布工具，基本都依赖 Node.js 生态。

所以即使你不是前端开发，只要想开发 VS Code 插件，也绕不开它。

---

三、创建第一个 VS Code 插件项目

VS Code 官方提供了一套比较成熟的脚手架工具，新手直接用它就行。

1）安装脚手架

先执行下面这条命令：

npm install -g yo generator-code

这里：

• yo 是 Yeoman，用来生成项目脚手架
• generator-code 是专门用于生成 VS Code 插件项目的模板

安装完成后，执行：

yo code

2）按照提示创建项目

终端中一般会让你做一些选择。建议第一次这样选：

? What type of extension do you want to create? New Extension (TypeScript)
? What's the name of your extension? csdn-demo-extension
? What's the identifier of your extension? csdn-demo-extension
? What's the description of your extension? My first VS Code extension
? Initialize a git repository? Yes
? Which package manager to use? npm

这里推荐你优先选择 TypeScript 模板，而不是 JavaScript 模板，原因很简单：

• 类型更清晰
• 代码提示更友好
• 后面扩展功能更舒服
• 也是现在更主流的写法

创建完成后，进入项目目录：

cd csdn-demo-extension
npm install

到这里，项目就已经初始化好了。

---

四、先跑通：本地调试插件

很多初学者容易卡在这里：项目虽然创建出来了，但不知道怎么“运行插件”。

其实 VS Code 插件不是像普通网页那样打开浏览器运行，而是通过 VS Code 自己的调试机制来启动。

1）用 VS Code 打开项目

code .

2）按 F5 启动调试

按下 F5 之后，VS Code 会再打开一个新的窗口。

这个新窗口叫做：

你可以把它理解成一个“专门用来加载你当前插件的测试版 VS Code”。

3）测试默认命令

在这个新窗口里：

• 按 Ctrl + Shift + P 打开命令面板
• 输入 Hello World
• 执行它

如果弹出了提示框，就说明你的第一个 VS Code 插件已经成功跑起来了。

这一步非常重要，因为它证明了你的开发环境、项目结构和调试流程都是通的。

---

五、先看懂插件项目结构

项目生成后，目录里文件不少，但新手一开始只需要重点关注几个核心文件：

• package.json
• src/extension.ts
• tsconfig.json
• README.md

下面分别解释一下。

1）package.json

它是插件的“配置中心”，主要负责声明：

• 插件名称
• 插件版本
• 入口文件
• 命令列表
• 菜单位置
• 支持的 VS Code 版本
• 发布信息

你可以把它理解成：

我这个插件有什么功能，要怎么告诉 VS Code。

2）src/extension.ts

它是插件的主入口文件，主要负责真正执行逻辑。

比如：

• 注册命令
• 响应用户点击
• 获取编辑器内容
• 弹出提示框
• 操作文件
• 创建面板

你可以把它理解成：

用户触发插件功能后，具体要做什么。

3）tsconfig.json

这是 TypeScript 编译配置文件，一般新手前期不用改太多，知道它是编译配置就够了。

4）README.md

这是插件说明文档，后面如果你要发布到 Marketplace，README 的内容会直接影响别人对你插件的第一印象。

---

六、实战练习：做一个“统计选中文本信息”的插件

只跑通默认的 Hello World 还不够，因为那只是脚手架给你的示例。

接下来我们自己做一个真正能用的小功能：

当用户选中文本后，右键执行命令，统计以下信息：

• 选中了多少行
• 一共多少字符
• 去掉空白后还有多少字符

这个功能不复杂，但它能帮你掌握 VS Code 插件开发最常见的一条主线：

• 注册命令
• 读取编辑器内容
• 获取用户选区
• 处理文本
• 展示结果
• 把命令挂到右键菜单

这条链路学会之后，你就算真正入门了。

---

七、第一步：修改 src/extension.ts

打开 src/extension.ts，把里面的示例代码替换成下面这段：

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
	const disposable = vscode.commands.registerCommand(
		'csdn-demo-extension.countSelection',
		() => {
			const editor = vscode.window.activeTextEditor;

			if (!editor) {
				vscode.window.showInformationMessage('请先打开一个文件');
				return;
			}

			const selection = editor.selection;
			const text = editor.document.getText(selection);

			if (!text) {
				vscode.window.showInformationMessage('请先选中文本后再执行此命令');
				return;
			}

			const lineCount = text.split(/\r?\n/).length;
			const charCount = text.length;
			const noWhitespaceCount = text.replace(/\s/g, '').length;

			vscode.window.showInformationMessage(
				`统计结果：${lineCount} 行，${charCount} 个字符，去空白后 ${noWhitespaceCount} 个字符`
			);
		}
	);

	context.subscriptions.push(disposable);
}

export function deactivate() {}

这段代码做了什么？

别急着背，先理解它的结构：

1）activate

export function activate(context: vscode.ExtensionContext)

这是插件激活时执行的入口函数。

也就是说，当 VS Code 判断你的插件需要运行时，就会调用这里。

2）注册命令

vscode.commands.registerCommand(...)

这表示我们注册了一个命令。之后用户在命令面板、菜单、快捷键里触发这个命令时，回调函数就会执行。

3）获取当前编辑器

const editor = vscode.window.activeTextEditor;

它代表当前正在操作的编辑器。

如果用户连文件都没打开，那自然没法统计文本，所以这里需要先做判空处理。

4）获取选中的内容

const selection = editor.selection;
const text = editor.document.getText(selection);

这里先拿到用户的选区，再根据选区取出对应文本。

5）统计信息

const lineCount = text.split(/\r?\n/).length;
const charCount = text.length;
const noWhitespaceCount = text.replace(/\s/g, '').length;

这几行就是普通的字符串处理逻辑：

• 按换行拆分得到行数
• 直接读取长度得到字符数
• 把空白字符去掉后再统计长度

6）弹出结果

vscode.window.showInformationMessage(...)

这会在 VS Code 右下角弹出一个提示框，把统计结果展示给用户。

---

八、第二步：修改 package.json

仅仅写好 extension.ts 还不够，因为 VS Code 还不知道你的插件提供了什么命令。

所以你还需要在 package.json 中声明它。

找到 contributes 部分，修改为下面这样：

{
  "activationEvents": [
    "onCommand:csdn-demo-extension.countSelection"
  ],
  "main": "./out/extension.js",
  "contributes": {
    "commands": [
      {
        "command": "csdn-demo-extension.countSelection",
        "title": "统计选中文本信息"
      }
    ],
    "menus": {
      "editor/context": [
        {
          "command": "csdn-demo-extension.countSelection",
          "when": "editorHasSelection",
          "group": "navigation"
        }
      ]
    }
  }
}

这几个配置分别是什么意思？

1）activationEvents

"onCommand:csdn-demo-extension.countSelection"

表示当这个命令被触发时，插件才激活。

这样做的好处是：

• 更节省资源
• 启动更合理
• 插件不会无意义提前加载

2）commands

这里定义了插件提供的命令。

其中：

• command 是命令的唯一标识
• title 是展示给用户看的名称

注意：command 必须和 extension.ts 中注册时的命令 ID 保持一致，否则命令会失效。

3）menus.editor/context

这里表示把命令放到编辑器右键菜单中。

4）when

"when": "editorHasSelection"

这个条件表示：只有在编辑器里选中了文本时，这个菜单项才会显示。

这样用户体验会更好，因为没选中文本时显示这个命令没意义。

---

九、第三步：重新编译并调试运行

代码和配置改完之后，执行：

npm run compile

然后按 F5 再次启动调试窗口。

接下来在新的 Extension Development Host 窗口中操作：

1. 新建一个文本文件
2. 输入几行内容
3. 选中其中一段文本
4. 右键
5. 点击 统计选中文本信息

如果你看到了类似这样的提示：

统计结果：3 行，28 个字符，去空白后 21 个字符

那就说明你已经真正写出了自己的第一个可用插件。

别小看这一步，这已经不再是“看懂教程”，而是“真正跑通了插件开发流程”。

---

十、到这里你已经学会了什么？

很多人学技术时容易只看概念，结果看完一堆文章，还是不会自己做。

但如果你跟着上面的步骤实际敲完，其实你已经掌握了 VS Code 插件开发最基础、也最核心的一条主线：

• 创建插件项目
• 理解项目结构
• 注册命令
• 读取编辑器内容
• 获取选中文本
• 处理文本数据
• 把命令放到右键菜单
• 在 VS Code 中调试运行

这条主线一旦走通，后面很多功能其实都是在它的基础上做增强。

比如你后续完全可以继续扩展：

• 统计整个文件
• 统计英文单词数
• 结果显示到状态栏
• 把结果写入新文件
• 做成侧边栏工具面板

---

十一、如何打包 VS Code 插件？

开发完本地功能之后，下一步就是把插件打成安装包。

现在常用的打包工具是 vsce。

1）安装 vsce

执行：

npm install -g @vscode/vsce

2）补充 package.json 里的必要信息

在正式打包前，建议把插件信息补完整，例如：

{
  "name": "csdn-demo-extension",
  "displayName": "CSDN Demo Extension",
  "description": "A simple VS Code extension for text statistics",
  "version": "0.0.1",
  "publisher": "你的发布者名称",
  "engines": {
    "vscode": "^1.90.0"
  },
  "categories": [
    "Other"
  ]
}

这里有几个字段你要特别注意：

• name：插件包名，建议英文小写、短横线连接
• displayName：插件显示名称
• description：插件简介
• version：版本号
• publisher：发布者名称
• engines.vscode：支持的 VS Code 版本范围

3）打包生成 .vsix

执行：

vsce package

执行成功后，当前目录会生成一个类似下面的文件：

csdn-demo-extension-0.0.1.vsix

这个 .vsix 文件就是你的插件安装包。

---

十二、如何本地安装 .vsix 进行测试？

如果你还不想立刻发布到 Marketplace，也可以先手动安装测试。

操作步骤如下：

1. 打开 VS Code
2. 进入扩展面板
3. 点击右上角 ...
4. 选择 Install from VSIX...
5. 选择刚刚打包生成的 .vsix 文件

安装完成后，你就可以像普通插件一样在自己的 VS Code 中使用它。

这个步骤非常适合在正式发布前做最后验证。

---

十三、如何发布到 VS Code Marketplace？

如果你希望别人也能在 VS Code 插件市场里搜到你的插件，就需要把它发布到 Marketplace。

整个流程并不复杂，主要分成 3 步。

第 1 步：创建 Publisher

你需要先到 Visual Studio Marketplace 创建一个发布者（Publisher）。

创建成功后，你会得到一个唯一的发布者名称。

然后把它填到 package.json 里：

"publisher": "你的publisher名称"

注意，这个名称必须和你实际创建的 Publisher 保持一致。

第 2 步：创建 Personal Access Token

发布插件时，通常需要用到 Token 来完成身份验证。

常见做法是到 Azure DevOps 中创建 Personal Access Token，并赋予 Marketplace 相关权限。

创建好之后，在终端中执行登录：

vsce login 你的publisher名称

然后按提示粘贴你的 Token。

第 3 步：执行发布

首次发布：

vsce publish

如果后续只是小改动，最常见的做法是：

vsce publish patch

它会自动把版本号从：

0.0.1 -> 0.0.2

如果是新增功能，可以用：

vsce publish minor

如果是重大更新，可以用：

vsce publish major

---

十四、发布前建议补齐哪些内容？

很多人第一次发布插件时，只关心“能不能发上去”，却忽略了插件页面展示质量。

如果你希望你的插件看起来更专业，发布前建议至少补齐下面这些内容。

1）完善 README.md

README 最好写清楚：

• 插件是做什么的
• 适合谁使用
• 怎么安装
• 怎么使用
• 运行效果截图
• 后续更新计划

因为 Marketplace 页面会直接展示 README，所以它其实就是你的“产品说明页”。

2）配置插件图标

可以在 package.json 中增加：

"icon": "images/icon.png"

一个清晰的图标，能显著提升插件的完整度。

3）配置代码仓库地址

如果你把项目放在 GitHub 上，建议加上仓库信息：

"repository": {
  "type": "git",
  "url": "https://github.com/你的用户名/你的仓库名"
}

这样别人更容易信任你的项目，也方便看源码和提 Issue。

4）增加关键词

可以补充：

"keywords": [
  "vscode",
  "extension",
  "text",
  "statistics"
]

关键词会影响搜索结果，更方便别人找到你的插件。

---

十五、新手最容易踩的几个坑

下面这些问题，是初学者在练习时非常容易遇到的。

1）命令注册了，但在命令面板里搜不到

通常是以下几个原因：

• package.json 中的命令 ID 和 extension.ts 中不一致
• 代码改完之后没有重新编译
• 调试窗口没有重启
• 插件没有正确激活

排查时先重点看命令 ID 是否完全一致。

2）右键菜单不显示

如果你配置了：

"when": "editorHasSelection"

那么只有在“真的选中了文本”的时候，这个右键菜单才会显示。

如果没选中文本，自然是看不到的。

3）发布时报权限错误

这类问题通常和下面几点有关：

• publisher 名称写错
• Token 权限不够
• 没有先执行 vsce login

4）发布失败提示版本重复

Marketplace 不允许重复版本号。

也就是说，每次发布新版本前，你都必须保证 version 比上一个版本更高。

5）装上插件了，但功能没反应

这种情况一般要从三个方向查：

• 插件是否激活
• 命令是否注册成功
• 回调函数中是否有报错

建议打开 开发人员工具 或调试控制台查看报错信息。

---

十六、如果你想继续深入，下一步应该学什么？

当你把这篇文章的小插件完整做出来之后，其实已经具备继续深入学习的基础了。

接下来建议按这个顺序继续学。

路线 1：继续做工具型插件

这个阶段最适合巩固基础，因为功能直观、成就感强。

可以尝试做：

• 一键生成注释
• 批量处理文本
• JSON / XML / Markdown 格式转换
• 自动插入模板代码
• 快速复制文件路径

路线 2：学习编辑器增强能力

当你想做更“像插件”的插件时，可以开始研究：

• 自动补全（Completion）
• 悬停提示（Hover）
• 诊断信息（Diagnostics）
• 快速修复（Code Action）

路线 3：学习界面型插件

如果你想做更有产品感的扩展，可以继续学：

• Tree View 侧边栏
• Status Bar 状态栏
• Webview 自定义页面

路线 4：学习语言服务和 LSP

如果你想做真正复杂的语言插件，比如：

• 语法高亮
• 跳转定义
• 查找引用
• 智能补全

那么后面就要进一步学习 Language Server Protocol，也就是常说的 LSP。

---

十七、本文小结

到这里，你已经完整走通了 VS Code 插件开发和发布最核心的一条链路：

• 会搭建基础开发环境
• 会使用脚手架创建插件项目
• 会在 VS Code 中本地调试插件
• 会注册命令并处理用户操作
• 会把功能挂到右键菜单里
• 会打包生成 .vsix
• 会发布到 VS Code Marketplace

对于初学者来说，这已经不是“了解一下插件开发”了，而是真正意义上的入门闭环。

我特别建议你一定要自己动手把这个练习敲一遍，因为 VS Code 插件开发最重要的不是概念，而是你有没有真的跑通过：

创建 -> 编写 -> 调试 -> 打包 -> 发布

只要这条链路你亲手走通一次，后面的很多进阶内容就不会再觉得陌生。

---

十八、建议你顺手做的 3 个小扩展练习

如果你想把这篇文章学得更扎实，建议做完后继续补下面 3 个练习。

练习 1：统计整个文件内容

不要只统计选中部分，而是统计当前整个文件：

• 行数
• 字符数
• 单词数

这个练习可以帮助你继续熟悉 editor.document.getText()。

练习 2：把结果显示到状态栏

不要只弹提示框，而是在 VS Code 底部状态栏显示统计结果。

这个练习可以让你开始接触 VS Code 的 UI 扩展能力。

练习 3：给命令添加快捷键

在 package.json 中为命令配置快捷键。

这样你会进一步理解：

• 命令系统
• 菜单系统
• 快捷键系统

其实都可以围绕同一个功能组织起来。

---

十九、本文练习命令清单

为了方便你边看边练，我把文中用到的命令整理成一份清单。

创建项目

npm install -g yo generator-code
yo code
cd csdn-demo-extension
npm install

编译与调试

npm run compile

然后在 VS Code 中按：

F5

打包插件

npm install -g @vscode/vsce
vsce package

登录与发布

vsce login 你的publisher名称
vsce publish

如果你想自动升级补丁版本后发布：

vsce publish patch

---

二十、结语

如果你是第一次接触 VS Code 插件开发，不要想着一开始就做很复杂的东西。

最好的入门方式，就是先把一个小而完整的插件做出来。

哪怕它的功能只是“统计选中文本信息”，只要你真的完成了：

• 项目创建
• 代码编写
• 本地调试
• 打包测试
• 正式发布

那你就已经超过了很多只停留在“看教程”阶段的人。

真正的学习，不是收藏了多少文章，而是你有没有把一个流程亲手做通。