撰寫 Python 擴充功能

注意：如果您是 VS Code 擴充功能開發的新手，建議您先閱讀您的第一個擴充功能 (Your First Extension) 教學課程，並嘗試建立一個簡單的 Hello World 擴充功能。

Python 擴充功能為其他擴充功能提供 API，以便與使用者電腦上的 Python 環境進行互動。請查看 @vscode/python-extension npm 套件，其中包含從您的擴充功能存取這些 API 所需的型別與輔助工具。

Python 擴充功能範本

Python 擴充功能範本可協助您開始為您喜愛的 Python 工具建置 Visual Studio Code 擴充功能。這可以是一個 linter（語法檢查工具）、格式化工具、程式碼分析工具，或是整合上述所有功能的工具。該範本將為您提供將工具整合至 VS Code 所需的基本構件，且它已經具備存取上述 Python API 的能力。

程式語言與框架

此擴充功能範本分為兩部分：擴充功能部分與語言伺服器部分。擴充功能部分使用 TypeScript 編寫，而語言伺服器部分則使用 Python 並基於 pygls (Python language server) 函式庫編寫。

使用此範本時，您大部分的工作會集中在 Python 程式碼部分。您將會使用語言伺服器協定 (Language Server Protocol) 將您的工具與擴充功能部分進行整合。pygls 目前適用於 LSP 3.16 版本。

TypeScript 部分負責處理與 VS Code 及其 UI 的互動。擴充功能範本內建了一些可供您的工具使用的設定。如果您需要新增設定以支援您的工具，則必須編寫部分 TypeScript 程式碼。該範本中包含了一些設定範例，您也可以查看我們團隊針對熱門工具開發的擴充功能作為參考。

必要條件

VS Code 1.64.0 或更高版本
Python 3.7 或更高版本
node >= 14.19.0
npm >= 8.3.0 (npm 隨 node 一併安裝，請檢查 npm 版本，若需更新請使用 npm install -g npm@8.3.0)
VS Code 的 Python 擴充功能

您應該具備建立及使用 Python 虛擬環境的相關知識。

入門指南

若要開始，請依照範本 README 中的說明進行。您將學會如何使用該範本建立您的儲存庫，以及如何安裝必要的工具（例如 nox 工作執行器）與選用依賴項（測試支援）。

README 包含最新的說明，並詳細介紹瞭如何自訂擴充功能的 package.json 預留位置（例如 <pythontool-module>、<pythontool-display-name> 等）。

範本功能

透過範本建立擴充功能後，它將包含以下擴充功能貢獻。假設 <pytool-module> 已替換為 mytool，且 <pytool-display-name> 已替換為 My Tool：

一個名為 My Tool: Restart Server 的指令（指令 ID：mytool.restart）。
下列設定：
- mytool.logLevel
- mytool.args
- mytool.path
- mytool.importStrategy
- mytool.interpreter
- mytool.showNotification
下列擴充功能啟動觸發條件：
- 語言為 python 時。
- 在開啟的工作區中發現 .py 副檔名的檔案時。
- 執行 mytool.restart 指令時。
用於記錄的輸出頻道：Output > My Tool。

整合您的工具

產生的 bundled/tool/server.py 檔案是您進行大部分修改的地方。檔案中的 TODO 註解標註了各個自訂點。此外，也請搜尋範本中其他位置（如其他 Python 和 Markdown 檔案）的 TODO 註解。即使您打算維持 MIT 授權，仍建議您檢閱 LICENSE 檔案。

範例

以下是幾個由該範本建立的實作範例：

Pylint - 在檔案 開啟 (open)、儲存 (save) 及 關閉 (close) 時實作語法檢查 (linting) 與程式碼動作 (Code Actions)。
Flake8 - 實作語法檢查與程式碼動作。
Black Formatter - 整合 Black 格式化工具。
autopep8 - 整合 autopep8 格式化工具。
isort - 新增用於排序匯入項目的程式碼動作。

您也可以查閱語言伺服器協定規範，以更深入了解 pygls 語言伺服器的整合方式。

擴充功能開發

範本 README 詳細介紹了範本內含的開發週期支援。範本中包含各種指令與設定，讓您可以建置、執行、偵錯及測試您的擴充功能。

如果您在開發過程中遇到問題，可以參考疑難排解 (Troubleshooting) 章節以解決常見問題。

封裝與發佈

在發佈擴充功能之前，您需要更新擴充功能的 package.json 欄位（例如 publisher 和 license）以符合您的專案。同時也建議您更新輔助的 Markdown 檔案（CODE_OF_CONDUCT.md、CHANGELOG.md 等）。

當您的擴充功能準備好發佈時，可以使用 nox 的 build-package 任務來建立 .vsix 檔案，隨後即可將其上傳至您的擴充功能管理頁面。

如果您是 VS Code 擴充功能開發的新手，建議您遵循 VS Code 主題擴充功能撰寫 (extension authoring) 中概述的最佳實踐。您可以在該處找到相關指南，協助您的擴充功能在 Marketplace 上呈現最佳樣貌，並了解如何成為經過驗證的發佈者，讓使用者能安心安裝您的擴充功能。

5/28/2026