啟動事件

啟用事件 (Activation Events) 是一組您在 package.json 擴充功能資訊清單 (Extension Manifest) 的 activationEvents 欄位中所定義的 JSON 宣告。當啟用事件發生時，您的擴充功能就會被啟動。以下是所有可用啟用事件的列表：

我們也提供了 package.json 擴充功能資訊清單中所有欄位的參考資料。

onLanguage

當開啟解析為特定語言的檔案時，會觸發此啟用事件，並啟動相關的擴充功能。

"activationEvents": [
    "onLanguage:python"
]

onLanguage 事件接受一個語言識別碼 (language identifier) 值。

您可以在 activationEvents 陣列中使用多個 onLanguage 項目來宣告多種語言。

"activationEvents": [
    "onLanguage:json",
    "onLanguage:markdown",
    "onLanguage:typescript"
]

注意：自 VS Code 1.74.0 起，由您的擴充功能所貢獻的語言，不再需要對應的 onLanguage 啟用事件宣告即可啟動您的擴充功能。

此外，如果您的擴充功能需要在任何語言使用前啟動，您可以使用通用的 onLanguage 啟用事件來確保這一點。

"activationEvents": [
    "onLanguage"
]

注意：最佳做法是僅在使用者需要您的擴充功能時才進行啟動。如果您的擴充功能僅適用於部分語言，那麼列出該子集會比對所有語言都啟動更好。

onCommand

當呼叫命令時，會觸發此啟用事件，並啟動相關的擴充功能。

"activationEvents": [
    "onCommand:extension.sayHello"
]

注意：自 VS Code 1.74.0 起，由您的擴充功能所貢獻的命令，不再需要對應的 onCommand 啟用事件宣告即可啟動您的擴充功能。

onDebug

在啟動偵錯工作階段之前，會觸發此啟用事件，並啟動相關的擴充功能。

"activationEvents": [
    "onDebug"
]

以下是四個更細緻的 onDebug 啟用事件：

onDebugAdapterProtocolTracker

當即將啟動特定類型的偵錯工作階段且可能需要偵錯協定追蹤器時，會觸發 onDebugAdapterProtocolTracker。

onDebugDynamicConfigurations

當使用者透過 UI（例如透過「選取並開始偵錯」命令）要求動態偵錯設定時，此啟用事件會在呼叫 DebugConfigurationProvider 的 provideDebugConfigurations 方法之前觸發。

此啟用事件的存在是用來表示該擴充功能貢獻了動態偵錯設定。

onDebugInitialConfigurations

當需要建立 launch.json 等初始偵錯設定時，此啟用事件會在呼叫 DebugConfigurationProvider 的 provideDebugConfigurations 方法之前觸發。

onDebugResolve

onDebugResolve:type 會在呼叫指定類型的 DebugConfigurationProvider 的 resolveDebugConfiguration 方法之前觸發。

經驗法則：如果偵錯擴充功能的啟動負擔較輕，請使用 onDebug。如果啟動負擔較重，請根據 DebugConfigurationProvider 是否實作了 provideDebugConfigurations 和/或 resolveDebugConfiguration 等對應方法，來選擇使用 onDebugInitialConfigurations 和/或 onDebugResolve。請參閱使用 DebugConfigurationProvider 以取得這些方法的更多詳細資訊。

workspaceContains

當開啟資料夾且該資料夾包含至少一個符合 glob 模式的檔案時，會觸發 workspaceContains:path，並啟動相關的擴充功能。

"activationEvents": [
    "workspaceContains:**/.editorconfig"
]

onFileSystem

當讀取來自特定 scheme 的檔案或資料夾時，會觸發 onFileSystem:scheme，並啟動相關的擴充功能。這通常是 file-scheme，但隨著自訂檔案系統提供者的出現，會使用更多 scheme，例如 ftp 或 ssh。

"activationEvents": [
    "onFileSystem:sftp"
]

onView

當 VS Code 側邊欄中展開指定 ID 的檢視時，會觸發此啟用事件，並啟動相關的擴充功能。內建檢視不會觸發啟用事件。

當 ID 為 nodeDependencies 的檢視可見時，會觸發下方的啟用事件。

"activationEvents": [
    "onView:nodeDependencies"
]

注意：自 VS Code 1.74.0 起，由您的擴充功能所貢獻的檢視，不再需要對應的 onView 啟用事件宣告即可啟動您的擴充功能。

onUri

當開啟該擴充功能的系統全域 Uri 時，會觸發此啟用事件，並啟動相關的擴充功能。Uri scheme 固定為 vscode 或 vscode-insiders。Uri 的權限部分 (authority) 必須是該擴充功能的識別碼。Uri 的其餘部分則可任意設定。

"activationEvents": [
    "onUri"
]

如果 vscode.git 擴充功能定義 onUri 為啟用事件，當開啟下列任何一個 Uri 時，它將會被啟動：

vscode://vscode.git/init
vscode://vscode.git/clone?url=https%3A%2F%2Fgithub.com%2FMicrosoft%2Fvscode-vsce.git
vscode-insiders://vscode.git/init (適用於 VS Code Insiders)

onWebviewPanel

當 VS Code 需要復原具有對應 viewType 的 webview 時，會觸發此啟用事件，並啟動相關的擴充功能。

例如，下方的 onWebviewPanel 宣告：

"activationEvents": [
    "onWebviewPanel:catCoding"
]

會導致當 VS Code 需要復原 viewType 為 catCoding 的 webview 時啟動擴充功能。viewType 是在呼叫 window.createWebviewPanel 時設定的，您需要另一個啟用事件（例如 onCommand）來最初啟動您的擴充功能並建立 webview。

onCustomEditor

當 VS Code 需要建立具有對應 viewType 的自訂編輯器 (custom editor) 時，會觸發此啟用事件，並啟動相關的擴充功能。

例如，下方的 onCustomEditor 宣告：

"activationEvents": [
    "onCustomEditor:catCustoms.pawDraw"
]

會導致當 VS Code 需要復原 viewType 為 catCustoms.pawDraw 的自訂編輯器時啟動擴充功能。viewType 是在 customEditors 貢獻點中設定，並透過 registerCustomEditorProvider 繫結至提供者。

注意：自 VS Code 1.74.0 起，由您的擴充功能所貢獻的自訂編輯器，不再需要對應的 onCustomEditor 啟用事件宣告即可啟動您的擴充功能。

onAuthenticationRequest

當擴充功能請求具有對應 providerId 的驗證工作階段（透過 authentication.getSession() API）時，會觸發此啟用事件，並啟動相關的擴充功能。

例如，下方的 onAuthenticationRequest 宣告：

"activationEvents": [
    "onAuthenticationRequest:github"
]

會導致當 VS Code 需要擷取類型為 github 的 AuthenticationSession 時啟動擴充功能。

注意：自 VS Code 1.74.0 起，由您的擴充功能所貢獻的驗證提供者，不再需要對應的 onAuthenticationRequest 啟用事件宣告即可啟動您的擴充功能。

onStartupFinished

此啟用事件會在 VS Code 啟動一段時間後觸發，相關的擴充功能將會啟動。這類似於 * 啟用事件，但它不會拖慢 VS Code 的啟動速度。目前，此事件是在所有 * 啟用後的擴充功能完成啟動後才觸發。

"activationEvents": [
    "onStartupFinished"
]

onTaskType

當需要列出或解析特定類型的任務時，會觸發 onTaskType:type。

"activationEvents": [
    "onTaskType:npm"
]

注意：自 VS Code 1.76.0 起，由您的擴充功能所貢獻的任務，不再需要對應的 onTaskType 啟用事件宣告即可啟動您的擴充功能。

onEditSession

當以給定的 scheme 存取編輯工作階段時，會觸發 onEditSession:scheme。

"activationEvents": [
    "onEditSession:file"
]

onSearch

當在具有給定 scheme 的資料夾中開始搜尋時，會觸發 onSearch:scheme。

"activationEvents": [
    "onSearch:file"
]

onOpenExternalUri

當開啟外部 URI（例如 http 或 https 連結）時觸發的啟用事件。

"activationEvents": [
    "onOpenExternalUri"
]

onNotebook

當開啟指定的 Notebook 文件類型時，會觸發 onNotebook:type。

"activationEvents": [
    "onNotebook:jupyter-notebook",
    "onNotebook:interactive"
]

onRenderer

當使用 Notebook 輸出渲染器時，會觸發 onRenderer:id。

"activationEvents": [
    "onRenderer:ms-toolsai.jupyter-renderers"
]

onTerminal

當開啟具有給定 Shell 類型的特定終端機時，會觸發 onTerminal:shellType。

"activationEvents": [
  "onTerminal:bash"
]

onTerminalProfile

當啟動特定的終端機設定檔時，會觸發 onTerminalProfile:id。

"activationEvents": [
    "onTerminalProfile:terminalTest.terminal-profile"
]

onTerminalShellIntegration

當具有給定 Shell 類型的終端機啟用 Shell 整合時，會觸發 onTerminalShellIntegration:shellType。

"activationEvents": [
    "onTerminalShellIntegration:bash"
]

onWalkthrough

當開啟指定的引導說明 (walkthrough) 時，會觸發 onWalkthrough:id。

"activationEvents": [
    "onWalkthrough:nodejsWelcome"
]

onIssueReporterOpened

當開啟問題回報器 (issue reporter) 時（例如透過說明：回報問題），會觸發此啟用事件。

"activationEvents": [
    "onIssueReporterOpened"
]

onChatParticipant

當呼叫指定的聊天參與者時觸發的啟用事件。

"activationEvents": [
    "onChatParticipant:my-chat-participant"
]

onLanguageModelTool

當呼叫指定的語言模型工具時觸發的啟用事件。

"activationEvents": [
    "onLanguageModelTool:my-language-model-tool"
]

啟動 (Start up)

當 VS Code 啟動時，會觸發 * 啟用事件，並啟動相關的擴充功能。

注意：為了確保良好的使用者體驗，請僅在您的應用場景中沒有其他啟用事件組合適用時，才在擴充功能中使用此啟用事件。

"activationEvents": [
    "*"
]

注意：擴充功能可以監聽多個啟用事件，這比僅監聽 "*" 更為理想。

注意：擴充功能必須從其主模組導出一個 activate() 函式，當觸發任何指定的啟用事件時，該函式將由 VS Code 僅呼叫一次。此外，擴充功能應該從其主模組導出一個 deactivate() 函式，以在 VS Code 關閉時執行清理工作。如果清理過程是非同步的，擴充功能必須從 deactivate() 回傳一個 Promise。如果清理過程是同步執行的，擴充功能則可以從 deactivate() 回傳 undefined。

5/28/2026