如何为 VSCode 编写你自己的第一个扩展（Extension）？

betcha

发布时间：2025-09-21 15:35:01

361人浏览过

来源于php中文网

原创

答案是利用Yeoman生成器快速搭建VSCode扩展项目骨架，并通过理解activate/deactivate生命周期与核心API实现功能，使用F5调试并发布到Marketplace。

如何为 vscode 编写你自己的第一个扩展（extension）？

编写你的第一个 VSCode 扩展，核心其实就是利用微软提供的 Yeoman 生成器，配合 JavaScript 或 TypeScript 语言，快速搭建一个项目骨架，然后深入理解 VSCode 的 API 接口，实现你想要的功能。这听起来可能有点技术性，但说实话，一旦你上手了，你会发现整个过程比想象中要友好得多。

解决方案

要为 VSCode 编写你的第一个扩展，我们通常会从一个脚手架工具开始，这能省去很多繁琐的配置工作。我个人觉得，直接动手是最好的学习方式。

首先，你需要确保你的开发环境已经准备就绪。这意味着你的机器上得有 Node.js 和 npm（或者 yarn，看你个人喜好）。这些是扩展开发的基础。

接下来，我们需要安装 Yeoman 和 VSCode 扩展的生成器。打开你的终端或命令行工具，输入：

npm install -g yo generator-code

yo

是 Yeoman 的命令行工具，而

generator-code

则是专门用来生成 VSCode 扩展项目的模板。安装好之后，你就可以开始创建你的扩展了。

在一个你喜欢的项目目录下，运行：

yo code

此时，

yo

会引导你完成一系列选择，比如你想创建哪种类型的扩展（比如一个新的 TypeScript 扩展、JavaScript 扩展，或者只是一个主题），你的扩展名称、描述、发布者等等。对于初学者，我通常会推荐选择 "New Extension (TypeScript)"，因为 TypeScript 提供了类型检查，能有效减少一些低级错误，让开发体验更顺畅。

完成这些选择后，

yo

就会为你生成一个完整的项目结构。你会看到类似这样的文件：

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

其中，

src/extension.ts

是你扩展的核心代码文件，

package.json

则是扩展的清单文件，它定义了扩展的元数据、贡献点（比如命令、视图、语言支持等）以及激活事件。

打开

src/extension.ts

，你会看到两个重要的函数：

activate

和

deactivate

。

// The module 'vscode' contains the VS Code extensibility API
// Import the module and reference it with the alias vscode
import * as vscode from 'vscode';

// This method is called when your extension is activated
// Your extension is activated the very first time the command is executed
export function activate(context: vscode.ExtensionContext) {
    // Use the console to output diagnostic information (console.log) and errors (console.error)
    // This line of code will only be executed once when your extension is activated
    console.log('Congratulations, your extension "my-first-extension" is now active!');

    // The command has been defined in the package.json file
    // Now provide the implementation of the command with registerCommand
    // The commandId parameter must match the command field in package.json
    let disposable = vscode.commands.registerCommand('my-first-extension.helloWorld', () => {
        // The code you place here will be executed every time your command is executed
        // Display a message box to the user
        vscode.window.showInformationMessage('Hello World from My First Extension!');
    });

    context.subscriptions.push(disposable);
}

// This method is called when your extension is deactivated
// Your extension is deactivated when VS Code is closed
export function deactivate() {}

默认生成的代码已经包含了一个

helloWorld

命令的实现。这个命令会在扩展激活时注册，当你通过命令面板（Ctrl+Shift+P 或 Cmd+Shift+P）执行

Hello World

命令时，它就会弹出一个信息提示框。

要运行和调试你的扩展，你只需要在 VSCode 中打开这个项目，然后按下

F5

键。这会打开一个新的 VSCode 窗口，也就是所谓的 "Extension Development Host"。在这个新窗口中，你的扩展就已经加载并运行了。你可以在这里测试你的命令，或者在

extension.ts

中设置断点进行调试。

说实话，第一次看到这些，可能会觉得有点多，但只要你跟着步骤走，跑起来第一个 "Hello World"，那种成就感还是挺不错的。

理解 VSCode 扩展的生命周期与核心 API 是关键吗？

我觉得，这绝对是关键。就像你造房子，你得知道地基怎么打，水管电线怎么走。VSCode 扩展也一样，你不理解它的生命周期和核心 API，很多时候你会感觉自己在盲人摸象。

生命周期：扩展的生命周期主要体现在

activate

和

deactivate

这两个函数上。

```
activate(context: vscode.ExtensionContext)
```
：这个函数在你的扩展被激活时调用。什么时候激活呢？这由
```
package.json
```
里的
```
activationEvents
```
字段决定。比如，如果你设置了
```
"onCommand:my-first-extension.helloWorld"
```
，那么只有当用户第一次执行
```
my-first-extension.helloWorld
```
这个命令时，你的
```
activate
```
函数才会被调用。你所有的资源注册、事件监听、命令注册等初始化工作，都应该放在这里。
```
context
```
对象则提供了一个存储空间，你可以用它来管理你的订阅（
```
context.subscriptions
```
），确保在扩展停用时能正确清理资源，避免内存泄漏。
```
deactivate()
```
：当你的 VSCode 窗口关闭，或者扩展被手动禁用时，这个函数会被调用。这是一个清理资源的最后机会。虽然在大多数情况下，VSCode 会帮你处理好，但如果你有一些持久化的资源或者需要手动关闭的连接，这里就是你处理它们的地方。

核心 API： VSCode 提供了非常丰富的 API，都暴露在

vscode

模块下。我个人觉得，初学者最常用、也最需要了解的有这么几类：

```
vscode.commands
```
：用于注册和执行命令。我们前面看到的
```
vscode.commands.registerCommand
```
就是它的一个应用。
```
vscode.window
```
：用于与 VSCode UI 进行交互，比如显示信息、警告、错误消息（
```
showInformationMessage
```
,
```
showWarningMessage
```
,
```
showErrorMessage
```
），或者打开文件选择器（
```
showOpenDialog
```
），创建新的文本编辑器（
```
showTextDocument
```
），甚至创建自定义的 Webview 面板。
```
vscode.workspace
```
：用于与工作区文件和设置进行交互。你可以用它来读取文件内容，监听文件变化，访问工作区配置（
```
getConfiguration
```
），甚至创建和管理新的文件。
```
vscode.languages
```
：如果你想为某种语言提供语法高亮、代码补全、诊断信息等，这个 API 就派上用场了。
```
vscode.TreeView
```
/
```
vscode.WebviewPanel
```
：如果你需要创建更复杂的 UI，比如侧边栏视图或者完全自定义的网页面板，这些是你的工具。

理解这些，能让你在遇到问题时，知道去哪里找解决方案，而不是漫无目的地搜索。它们是构建任何有意义扩展的基石。

开发过程中常遇到的坑和调试技巧有哪些？

说实话，开发过程中遇到 "坑" 是家常便饭，谁不是踩着坑一路走过来的呢？我个人在开发 VSCode 扩展时，也遇到过不少让人头疼的问题，但掌握一些调试技巧能大大提高效率。

SiteDynamic企业网站管理系统1.7.7 标准版

SiteDynamic企业网站管理系统采用较为成熟的ASP+ACCESS编写，是迄今为止国内较先进的ASP语言企业网站管理系统。系统为企业级网站提供一个框架，能满足企业的基本应用，同时系统开放全部源码，用户可以根据自己的需求扩展出自己需求的模块，如：单页面、新闻、产品展示、下载、友情链接、电子商务、广告、会员、在线支付、人才招聘等。整套系统的设计构造，完全考虑大中小企业类网站的功能要求，网站的后台

下载

常见的 "坑"：

激活事件（
activationEvents
）不触发：这是新手最常遇到的问题之一。你写好了代码，但扩展就是不运行。通常是因为
```
package.json
```
中的
```
activationEvents
```
配置不对。比如，你期望某个命令能激活扩展，但命令 ID 写错了；或者你期望在打开特定文件类型时激活，但
```
onLanguage
```
或
```
onStartupFinished
```
配置有误。仔细检查
```
package.json
```
和你的实际代码中的命令 ID 是否匹配，以及激活条件是否满足。
package.json
配置错误：
```
contributes
```
部分是定义扩展贡献点的核心，比如命令、菜单项、视图容器、语言配置等。一个小的拼写错误或者 JSON 格式问题，都可能导致你的贡献点无法正确显示或工作。VSCode 的输出面板（Output Panel）通常会给出一些提示。
异步操作处理不当： JavaScript/TypeScript 异步操作无处不在，尤其是在文件读写、网络请求等场景。如果忘记使用
```
await
```
或者没有正确处理 Promise，你的扩展可能会出现意想不到的行为，比如数据未加载完成就尝试使用，导致
```
undefined
```
错误。
UI 更新不及时或不生效： 如果你创建了自定义视图（如
```
TreeView
```
或
```
Webview
```
），有时会发现数据更新了，但 UI 没有刷新。这通常需要你手动触发 UI 的更新机制，比如
```
treeDataProvider.onDidChangeTreeData.fire()
```
或者向
```
Webview
```
发送消息。
内存泄漏： 如果你在
```
activate
```
函数中注册了大量的事件监听器，但没有在
```
deactivate
```
或通过
```
context.subscriptions
```
妥善管理它们，长时间运行后可能会导致内存占用过高。

实用的调试技巧：

console.log
大法：最原始但也最有效的调试方式。在你的代码中插入
```
console.log()
```
，然后打开 "Extension Development Host" 窗口的 "Debug Console"（通常在 VSCode 的底部面板），你就能看到输出。对于快速检查变量值或代码执行路径非常有用。
VSCode 内置调试器（
F5
）：这是你的主要工具。当你按下
```
F5
```
运行扩展时，VSCode 会自动为你启动一个调试会话。你可以在
```
extension.ts
```
文件中设置断点，单步执行代码，检查变量，观察调用栈。
```
launch.json
```
文件（在
```
.vscode
```
目录下）定义了调试配置，通常
```
yo code
```
会为你生成一个默认的 "Run Extension" 配置。
"Extension Development Host" 的输出面板： 在 "Extension Development Host" 窗口中，打开 "Output" 面板，选择 "Log (Extension Host)" 或 "Log (Main)"。这里会输出 VSCode 扩展主机的一些内部日志，包括你的扩展可能抛出的错误信息，这对于排查一些底层问题非常有帮助。
检查
package.json
语法： VSCode 对
```
package.json
```
的格式要求很严格。如果怀疑是配置问题，可以尝试用一个在线 JSON 校验工具检查一下你的
```
package.json
```
文件。
隔离问题： 当遇到复杂问题时，尝试将问题范围缩小。比如，如果一个命令不工作，先确保
```
activate
```
函数被调用了，再确保命令被注册了，最后才检查命令的回调函数。一步步排除，会比一下子想解决所有问题更有效。
查看 VSCode API 文档： 微软的 VSCode API 文档非常详尽，遇到不清楚的 API 用法或功能时，直接查阅官方文档是最权威的。

记住，调试是开发不可分割的一部分。别害怕错误，它们是你进步的阶梯。

如何发布你的 VSCode 扩展并让更多人使用？

当你觉得你的扩展已经足够稳定，并且能解决一些实际问题时，下一步自然就是发布它，让更多人能用上。这个过程比你想象的要规范，但只要跟着步骤走，其实也挺直接的。

准备工作：

创建 Azure DevOps 组织和个人访问令牌（PAT）： 这是发布到 VSCode Marketplace 的前提。你需要去 Azure DevOps 注册一个组织（如果还没有的话），然后在组织设置里生成一个 PAT。这个 PAT 会作为你的身份凭证，用来上传扩展。记住，PAT 的权限至少要包含 "Marketplace (Publish)"。
安装
```
vsce
```
：
```
vsce
```
(VS Code Extension Manager) 是一个命令行工具，专门用于打包和发布 VSCode 扩展。
```
npm install -g vsce
```
完善
```
package.json
```
：在发布前，确保你的
```
package.json
```
里的信息是完整且准确的，包括：
- ```
name
```
  ：扩展的唯一 ID。
- ```
displayName
```
  ：在 Marketplace 中显示的名称。
- ```
description
```
  ：简短的描述。
- ```
version
```
  ：版本号。
- ```
publisher
```
  ：你的发布者 ID（需要在 Azure DevOps 中创建）。
- ```
repository
```
  ：你的代码仓库地址（GitHub 等）。
- ```
categories
```
  ：扩展所属的类别（如 "Programming Languages", "Themes"）。
- ```
icon
```
  ：一个 128x128 像素的图标路径。
撰写
```
README.md
```
、
CHANGELOG.md
和
LICENSE
：
- ```
README.md
```
  ：这是用户了解你扩展的第一扇窗。务必写清楚扩展的功能、如何安装、如何使用、截图示例等。一个好的
```
README
```
  对吸引用户至关重要。
- ```
CHANGELOG.md
```
  ：记录每个版本更新了什么，修复了什么 bug，增加了什么功能。这能让用户了解你的扩展在持续改进。
- ```
LICENSE
```
  ：选择一个合适的开源许可证，明确你的扩展的使用、修改和分发权限。

发布流程：

登录
vsce
：在你的项目根目录，运行：
```
vsce login 
```
它会提示你输入之前生成的 PAT。
打包扩展（可选但推荐）： 你可以先将扩展打包成一个
```
.vsix
```
文件，进行本地测试，确保一切正常。
```
vsce package
```
这会在你的项目目录下生成一个
```
.vsix
```
文件。你可以在 VSCode 中通过 "Install from VSIX..." 选项来安装它。
发布扩展： 当你确信一切就绪后，就可以发布了。
```
vsce publish
```
```
vsce
```
会自动读取
```
package.json
```
中的版本号，并将其发布到 VSCode Marketplace。如果这是你第一次发布，或者版本号有更新，它都会相应处理。