编写 Python 扩展

注意：如果您是 VS Code 扩展开发的新手，建议先阅读您的第一个扩展教程，并尝试创建一个简单的 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 时。
用于记录日志的输出通道：输出 > My Tool。

集成您的工具

生成的 bundled/tool/server.py 文件是您进行大部分修改的地方。文件中的 TODO 注释指出了各个自定义点。此外，请在模板的其他位置（例如其他 Python 和 Markdown 文件）搜索 TODO 注释。即使您想保留 MIT 许可证，也建议查阅 LICENSE 文件。

示例

有几个基于该模板创建的实现示例：

Pylint - 在文件 打开、保存 和 关闭 时实现代码检查和代码操作。
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 主文档中扩展开发主题下概述的最佳实践。在那里，您可以找到相关指南，帮助您的扩展在插件市场中获得良好的展示效果，并了解如何成为受信任的发布者，让用户放心地安装您的扩展。

4/8/2026