如何为 VSCode 编写你自己的第一个扩展（Extension）？-VSCode-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 扩展时，也遇到过不少让人头疼的问题，但掌握一些调试技巧能大大提高效率。

一览AI编剧

创意生成+情节生成+脚本生成，AI编剧3步走，AI自动帮你搞定剧情！

查看详情

常见的 "坑"：

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