我不知道的 VSCode 扩展:生命周期的奥秘

引言

⏳ 在前面的文章中，我们学习了 VSCode 扩展开发的基础知识、用户界面元素、交互方式以及强大的 API。今天，我们将深入幕后，探索 VSCode 扩展的生命周期。理解扩展的生命周期对于开发高质量、高性能的 VSCode 扩展至关重要。它关系到扩展何时被激活、何时加载资源、何时开始运行、以及何时被卸载。掌握扩展生命周期的奥秘，你将能够更好地管理扩展的运行状态，优化扩展性能，避免潜在的错误和资源泄漏。现在，就让我们一起揭开 VSCode 扩展生命周期的神秘面纱！

什么是 VSCode 扩展生命周期？

🔄 VSCode 扩展生命周期 指的是一个 VSCode 扩展从启动到结束的整个过程，包括激活 (Activation)、加载 (Loading)、运行 (Running) 和 卸载 (Deactivation) 等阶段。每个阶段都有特定的触发条件和执行逻辑。理解这些阶段以及它们之间的关系，可以帮助开发者更好地控制扩展的行为，并在合适的时机执行相应的操作。

扩展激活 (Activation)

🎬 激活 (Activation) 是 VSCode 扩展生命周期的第一个重要阶段。当满足特定条件时，VSCode 会激活你的扩展，并执行你在 extension.ts (或其他入口文件) 中定义的 activate() 函数。激活是扩展开始工作的起点。

激活事件 (Activation Events)

🔑 激活事件 (Activation Events) 定义了什么情况下 VSCode 应该激活你的扩展。你需要在 package.json 文件的 activationEvents 数组中声明激活事件。VSCode 提供了多种激活事件，常用的包括:

onStartupFinished: VSCode 启动完成后激活。这是最常用的激活事件，表示扩展在 VSCode 启动后立即激活。
onLanguage:${languageId}: 当打开指定语言的文件时激活。例如 onLanguage:python 表示当打开 Python 文件时激活。${languageId} 需要替换为具体的语言 ID，例如 python, javascript, markdown 等。
onCommand:${commandId}: 当执行指定命令时激活。例如 onCommand:extension.helloWorld 表示当执行 extension.helloWorld 命令时激活。${commandId} 需要替换为你定义的命令 ID。
onFileSystem:${scheme}: 当访问指定文件系统方案的文件时激活。例如 onFileSystem:file 表示当访问本地文件系统文件时激活，onFileSystem:git 表示当访问 Git 文件系统文件时激活。${scheme} 需要替换为文件系统方案，例如 file, git, ftp 等。
onView:${viewId}: 当显示指定视图时激活。例如 onView:myTreeView 表示当显示 ID 为 myTreeView 的树视图时激活。${viewId} 需要替换为你定义的视图 ID。
onWebviewPanel:${viewType}: 当创建指定类型的 Webview 面板时激活。例如 onWebviewPanel:myWebview 表示当创建类型为 myWebview 的 Webview 面板时激活。${viewType} 需要替换为你定义的 Webview 类型。
*: 通配符，表示在 VSCode 启动后立即激活，类似于 onStartupFinished。但不推荐使用，因为它会导致扩展在不必要的情况下被激活，影响 VSCode 性能。

你可以在 package.json 中配置多个激活事件，当任何一个事件被触发时，扩展都会被激活。

{
  "name": "my-extension",
  "version": "0.0.1",
  "activationEvents": [
    "onStartupFinished",
    "onLanguage:python",
    "onCommand:extension.helloWorld",
    "onView:myTreeView"
  ],
  // ...
}

上面的配置表示，当 VSCode 启动完成、打开 Python 文件、执行 extension.helloWorld 命令或显示 myTreeView 视图时，my-extension 扩展会被激活。

`activate()` 函数

⚙️ activate() 函数是扩展激活时执行的函数，它在 extension.ts 文件中定义 (通常是 src/extension.ts)。activate() 函数接收一个 vscode.ExtensionContext 类型的参数 context，通过 context 对象，你可以访问 VSCode 提供的各种 API，注册命令、视图、事件监听器等，并管理扩展的资源。

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
    console.log('Congratulations, your extension "xxx" is now active!');

    // 注册命令
    let disposable = vscode.commands.registerCommand('extension.helloWorld', () => {
        vscode.window.showInformationMessage('Hello World from xxx!');
    });
    context.subscriptions.push(disposable);

    // 创建状态栏项目
    const statusBarItem = vscode.window.createStatusBarItem(vscode.StatusBarAlignment.Right, 100);
    statusBarItem.text = '$( Smiley ) Hello Status Bar';
    statusBarItem.tooltip = 'This is a status bar item';
    statusBarItem.command = 'extension.helloWorld';
    statusBarItem.show();
    context.subscriptions.push(statusBarItem);

    // ... 其他激活时需要执行的代码 ...
}

在 activate() 函数中，你需要完成扩展初始化和资源注册等操作。例如:

注册命令 (commands): 使用 vscode.commands.registerCommand() 注册命令，使其可以在命令面板、菜单、快捷键等地方被调用。
注册视图 (views): 使用 vscode.window.registerTreeDataProvider() 或 vscode.window.registerWebviewViewProvider() 注册树视图或 Webview 视图。
注册语言特性 (language features): 使用 vscode.languages.registerCompletionItemProvider(), vscode.languages.registerHoverProvider() 等注册代码补全、悬停提示等语言特性。
创建状态栏项目 (status bar items): 使用 vscode.window.createStatusBarItem() 创建状态栏项目，用于在状态栏显示扩展信息或提供快捷操作。
注册事件监听器 (event listeners): 监听 VSCode 的各种事件，例如编辑器事件、文件系统事件、配置变化事件等，以便在特定事件发生时执行相应的操作。
初始化扩展状态: 加载扩展的配置、缓存数据等，初始化扩展的运行状态。

重要: 在 activate() 函数中注册的所有可销毁资源 (例如命令、视图、状态栏项目、事件监听器等)，都需要添加到 context.subscriptions 数组中。当扩展被卸载时，VSCode 会自动销毁 context.subscriptions 中的所有资源，避免资源泄漏。

扩展加载 (Loading) 和运行 (Running)

🚀 加载 (Loading) 和 运行 (Running) 阶段紧随激活之后。

加载 (Loading): 当扩展被激活后，VSCode 会加载扩展的代码和资源，例如 JavaScript 文件、CSS 文件、图片、本地化资源等。这个阶段主要是将扩展的代码和资源加载到内存中，为后续的运行做准备。
运行 (Running): 加载完成后，扩展就开始进入运行状态。在运行状态下，扩展可以响应用户操作、执行命令、提供语言特性、与 VSCode API 交互等。扩展会一直保持运行状态，直到 VSCode 关闭或扩展被卸载。

需要注意的是，加载和运行阶段通常是自动进行的，开发者无需显式地编写代码来控制加载和运行过程。 你只需要在 activate() 函数中编写扩展的初始化逻辑，VSCode 会负责加载和运行你的扩展。

扩展卸载 (Deactivation)

🚪 卸载 (Deactivation) 是 VSCode 扩展生命周期的最后一个阶段。当 VSCode 关闭、扩展被禁用或卸载时，VSCode 会尝试卸载你的扩展，并执行你在 extension.ts 文件中定义的 deactivate() 函数 (如果定义了的话)。卸载是扩展生命周期的终点。

`deactivate()` 函数

🚪 deactivate() 函数是扩展卸载时执行的函数，它是可选的。如果你需要在扩展卸载时执行一些清理工作，例如释放资源、保存状态、清理临时文件等，你可以在 extension.ts 文件中定义 deactivate() 函数。

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
    console.log('Congratulations, your extension "xxx" is now active!');
    vscode.window.showInformationMessage('Extension "xxx" is now active!');

    // ... (activate 函数中的其他代码) ...
}

export function deactivate() {
    console.log('Your extension "xxx" is now deactivated!');
    vscode.window.showInformationMessage('Extension "xxx" is now deactivated!');

    // 在控制台输出卸载信息 (仅在开发时可见)
    // 你可以在 deactivate 函数中执行任何扩展清理逻辑
    // 例如:释放资源、保存状态、清理临时文件等
}

deactivate() 函数的执行时机

deactivate() 函数会在以下情况下被调用:

VSCode 关闭: 当用户关闭 VSCode 窗口时，所有激活的扩展都会被卸载，并执行 deactivate() 函数。
扩展被禁用: 当用户在 VSCode 扩展面板中禁用你的扩展时，扩展会被卸载，并执行 deactivate() 函数。
扩展被卸载: 当用户在 VSCode 扩展面板中卸载你的扩展时，扩展会被卸载，并执行 deactivate() 函数。
工作区关闭: 当用户关闭 VSCode 工作区时，某些工作区级别的扩展可能会被卸载 (取决于扩展的激活事件和配置)。

deactivate() 函数的注意事项

deactivate() 函数是可选的: 如果你的扩展不需要在卸载时执行任何清理工作，可以不定义 deactivate() 函数。
deactivate() 函数的执行时间有限: VSCode 不会无限期地等待 deactivate() 函数执行完成。如果 deactivate() 函数执行时间过长，可能会被 VSCode 强制终止。因此，deactivate() 函数中应该只执行必要的快速清理操作，避免执行耗时操作，例如网络请求、大量数据处理等。
资源释放: 最重要的是在 deactivate() 函数中释放所有在 activate() 函数中创建的资源，特别是那些没有添加到 context.subscriptions 中的资源。 虽然添加到 context.subscriptions 中的资源会在扩展卸载时自动释放，但如果你的扩展在 activate() 函数中创建了一些没有添加到 context.subscriptions 中的资源 (例如全局变量、定时器等)，则需要在 deactivate() 函数中手动释放这些资源，防止资源泄漏。

总结

🎉 恭喜你，完成了 VSCode 扩展生命周期的探索之旅！我们深入了解了扩展的 激活 (Activation)、加载 (Loading)、运行 (Running) 和 卸载 (Deactivation) 四个主要阶段，以及每个阶段的关键概念和注意事项。掌握扩展生命周期，你将能够更好地控制扩展的行为，优化扩展性能，避免潜在的错误和资源泄漏，开发出更加健壮和高效的 VSCode 扩展。在接下来的学习中，建议你结合实际扩展开发，不断实践和深入理解扩展生命周期的各个方面。相信你一定能够成为 VSCode 扩展开发高手！

引言