在 VS Code 中试用！

在 Visual Studio Code 中编辑 Python

Visual Studio Code 是一个强大的 Python 源代码编辑工具。编辑器包含各种功能，可帮助你在编写代码时提高效率。有关在 Visual Studio Code 中编辑的更多信息，请参阅基本编辑和代码导航。

在本概述中，我们将介绍由 Python 扩展提供的特定编辑功能，包括如何通过用户和工作区设置来自定义这些功能的步骤。

自动补全和智能感知

智能感知是与代码补全相关的代码编辑功能的通用术语。请看下面的示例。当键入 print 时，请注意智能感知如何填充自动补全选项。当用户开始键入名为 greeting 的变量时，也会提供一个选项列表。

Hello World Example for IntelliSense

自动补全和智能感知适用于当前工作文件夹中的所有文件。它们也适用于安装在标准位置的 Python 包。

Pylance 是 VS Code 中 Python 的默认语言服务器，它与 Python 扩展一起安装，以提供智能感知功能。

Pylance 基于 Microsoft 的 Pyright 静态类型检查工具，利用类型存根（.pyi 文件）和惰性类型推断，提供高性能的开发体验。

有关智能感知的更多信息，请参阅智能感知。

提示：查看适用于 VS Code 的 IntelliCode 扩展。IntelliCode 为 Python 中的智能感知提供了一系列 AI 辅助功能，例如根据当前代码上下文推断最相关的自动补全。有关更多信息，请参阅适用于 VS Code 的 IntelliCode 常见问题。

自定义智能感知行为

默认情况下启用全部智能感知功能可能会导致开发体验变慢，因此 Python 扩展启用了一组最少的功能，使你能够在保持高性能体验的同时提高生产力。但是，你可以通过多种设置根据自己的喜好自定义分析引擎的行为。

启用自动导入

Pylance 为工作区中的模块以及环境中安装的包提供自动导入建议。在编辑器中键入时，可能会获得补全建议。接受建议后，自动导入会自动将相应的导入语句添加到文件中。

你可以通过在设置中将 python.analysis.autoImportCompletions 设置为 true 来启用自动导入。默认情况下，自动导入是禁用的。

Completion with auto import displayed on the suggestion list

为自定义包位置启用智能感知

要为安装在非标准位置的包启用智能感知，请将这些位置添加到 settings.json 文件中的 python.analysis.extraPaths 集合（默认集合为空）。例如，如果你使用 Flask，Google App Engine 可能安装在自定义位置，并在 app.yaml 中指定。在这种情况下，你可以按如下方式指定这些位置

Windows

"python.analysis.extraPaths": [
    "C:/Program Files (x86)/Google/google_appengine",
    "C:/Program Files (x86)/Google/google_appengine/lib/flask-0.12"]

macOS/Linux

"python.analysis.extraPaths": [
    "~/.local/lib/Google/google_appengine",
    "~/.local/lib/Google/google_appengine/lib/flask-0.12" ]

有关可用智能感知控件的完整列表，你可以参考 Python 扩展的代码分析设置和自动补全设置。

你还可以自定义自动补全和智能感知的通用行为，甚至完全禁用这些功能。你可以在自定义智能感知中了解更多信息。

使用 AI 增强补全

GitHub Copilot 是一款由 AI 驱动的代码补全工具，可帮助你更快、更智能地编写代码。你可以在 VS Code 中使用 GitHub Copilot 扩展来生成代码，或从其生成的代码中学习。

GitHub Copilot extension in the VS Code Marketplace

GitHub Copilot 为多种语言和各种框架提供建议，并且它在 Python、JavaScript、TypeScript、Ruby、Go、C# 和 C++ 中表现尤为出色。

你可以在Copilot 文档中了解有关如何开始使用 Copilot 的更多信息。

导航

编辑时，你可以右键单击不同的标识符，以利用多个便捷命令

  • 转到定义（F12）将你的代码跳转到定义对象的代码中。此命令在处理库时很有用。

  • 查看定义（⌥F12（Windows Alt+F12，Linux Ctrl+Shift+F10））类似，但直接在编辑器中显示定义（在编辑器窗口中留出空间，以避免遮挡任何代码）。按 Escape 关闭查看窗口，或使用右上角的 x。

  • 转到声明 跳转到代码中声明变量或其他对象的位置。

  • 查看声明 类似，但直接在编辑器中显示声明。同样，使用 Escape 或右上角的 x 关闭查看窗口。

快速修复

添加导入

使用 Pylance 时，“添加导入”快速修复使你能够快速补全环境中已安装模块的导入语句。当你在编辑器中开始键入包名时，会出现一个代码操作，以自动补全源代码行。将鼠标悬停在文本（用波浪线标记）上，然后选择代码操作灯泡。然后你可以从潜在导入列表中进行选择。

Add import code action

此代码操作还识别以下常见 Python 包的一些常用缩写：numpy 为 np，tensorflow 为 tf，pandas 为 pd，matplotlib.pyplot 为 plt，matplotlib 为 mpl，math 为 m，scipi.io 为 spio，scipy 为 sp，panel 为 pn，以及 holoviews 为 hv。

Common package abbreviations

导入建议列表显示置信度最高的前 3 个导入选项，其优先级基于：最近使用的导入、来自同一模块的符号、来自标准库的符号、来自用户模块的符号、来自第三方包的符号，最后按模块和符号名称排序。

搜索其他导入匹配项

默认情况下，“添加导入”快速修复仅显示 3 个高置信度导入选项。如果它们没有列出你要查找的内容，你可以使用 Pylance 的搜索其他导入匹配项快速修复来解决缺少导入错误。此快速修复会显示一个快速选择菜单，使你能够搜索与缺少导入符号前缀匹配的导入选项。

Search for additional import matches Code Action

更改拼写

当未解析的变量或缺少导入诊断很可能是由拼写错误引起时，Pylance 会显示更改拼写快速修复。此代码操作会根据工作区中找到的最接近匹配项，建议正确的符号拼写。

Change spelling code action on missing import due to a typo

注意: 对于用户符号，这些快速修复仅会建议从定义它们的文件中导入。不支持从用户符号为外部或已导入的文件中提供导入建议。

另请注意，对于来自已安装包的符号（通常位于 Python 环境的 site-packages 文件夹下），这些快速修复仅建议在包的根文件夹中定义的符号，例如在其 __init__.py 文件中定义的符号。你可以通过 python.analysis.packageIndexDepths 设置为特定包自定义此行为，但请注意，这可能会影响 Pylance 的性能。

重构

Python 扩展通过 Pylance 扩展添加了以下重构功能：提取变量、提取方法、重命名模块、移动符号和实现所有继承的抽象类。它还支持实现附加重构功能的扩展，例如排序导入。

提取变量

提取当前作用域中选定文本的所有相似出现项，并将其替换为新变量。

你可以通过选择要提取为变量的代码行来调用此命令。然后选择旁边显示的灯泡图标。

Refactoring a variable

提取方法

提取当前作用域中选定表达式或块的所有相似出现项，并将其替换为方法调用。

你可以通过选择要提取为方法的代码行来调用此命令。然后选择旁边显示的灯泡图标。

Refactoring code into a method

重命名模块

Python 文件/模块重命名后，Pylance 可以找到所有可能需要更新的实例，并为你提供所有更改的预览。

要自定义需要更新的引用，你可以在重构预览中切换行或文件级别的复选框。做出选择后，你可以选择应用重构或放弃重构。

Renaming a module

移动符号

Pylance 扩展提供了两种代码操作，以简化将符号移动到不同文件的过程

  • 将符号移动到...：显示文件选择器以选择要移动符号的目标文件。
  • 将符号移动到新文件：创建一个与符号同名的新文件，位于调用代码操作的源文件所在的同一目录下。

你可以通过将鼠标悬停在要移动的符号上，然后选择所需操作旁边出现的灯泡图标来访问这些代码操作。或者，你可以右键单击符号并从上下文菜单中选择重构...。

Move Symbol refactoring options

实现所有继承的抽象类

在 Python 中，抽象类充当其他类的“蓝图”，通过促进清晰的结构和子类必须遵守的要求来帮助构建模块化、可重用的代码。要在 Python 中定义抽象类，你可以创建一个继承自 abc 模块中的 ABC 类的类，并使用 @abstractmethod 装饰器注释其方法。然后，你可以创建继承自此抽象类的新类，并定义基本方法的实现。

Pylance 提供了一个代码操作来简化创建这些类的过程。当你定义一个继承自抽象类的新类时，现在可以使用实现所有继承的抽象类代码操作来自动实现父类的所有抽象方法和属性

Implement inherited abstract classes

排序导入

Python 扩展支持实现了排序导入功能的扩展，例如 isort 和 Ruff。此命令将来自同一模块的特定导入合并到一个 import 语句中，并按字母顺序组织 import 语句。

你可以通过安装支持排序导入的扩展，然后打开命令面板（⇧⌘P（Windows、Linux Ctrl+Shift+P））并运行组织导入来调用此功能。

提示：你可以为 editor.action.organizeImports 命令分配键盘快捷方式。

Sorting import statements

故障排除

有关常见智能感知和 Python 编辑问题的帮助，请查看下表

问题 原因 解决方案
添加导入时，Pylance 仅提供顶层符号选项。 默认情况下，仅索引顶层模块（深度=1）。
例如，你可能会看到 import matplotlib 作为建议，但默认情况下不会看到 import matplotlib.pyplot。		 尝试通过 python.analysis.packageIndexDepths 增加 Pylance 可以索引已安装库的深度。请查看代码分析设置。
Pylance 未自动添加缺失的导入 自动导入补全设置可能已禁用。 请查看启用自动导入部分。
自动导入已启用，但 Pylance 未自动导入工作区中其他文件中定义的符号。 用户定义的符号（非来自已安装包或库的符号）只有在编辑器中打开的文件中已使用时才会被自动导入。
否则，它们将只能通过添加导入快速修复获得。		 使用添加导入快速修复，或者确保首先在工作区中打开相关文件。
处理大型工作区时，Pylance 似乎很慢或消耗过多内存。 Pylance 分析是在给定工作区中的所有文件上完成的。 如果你知道某些子文件夹可以从 Pylance 的分析中排除，你可以将它们的路径添加到 python.analysis.exclude 设置中。另外，你也可以尝试将 python.analysis.indexing 设置为 false 以禁用 Pylance 的索引器（注意：这也会影响补全和自动导入的体验。在代码分析设置中了解更多关于索引的信息）。
你无法将自定义模块安装到你的 Python 项目中。 自定义模块位于非标准位置（未使用 pip 安装）。 将该位置添加到 python.autoComplete.extraPaths 设置中，然后重新启动 VS Code。

Pylance 诊断

Pylance 默认在“问题”面板中为 Python 文件提供诊断信息。

以下列表是 Pylance 提供的一些最常见的诊断信息以及如何修复它们。

importResolveSourceFailure

当 Pylance 能够找到导入包的类型存根，但无法找到包本身时，会发生此错误。当你要导入的包未安装在选定的 Python 环境中时，可能会发生这种情况。

如何修复

  • 如果包已安装在不同的解释器或内核中，请选择正确的解释器。
  • 如果包未安装，你可以在已激活的终端中运行以下命令来安装它：python -m pip install {package_name}。

importResolveFailure

当 Pylance 无法找到你正在导入的包或模块，也无法找到其类型存根时，会发生此错误。

如何修复

  • 如果你正在导入模块，请确保它存在于你的工作区中，或者存在于 python.autoComplete.extraPaths 设置中包含的位置。
  • 如果你正在导入未安装的包，你可以在已激活的终端中运行以下命令来安装它：python -m pip install {package_name}。
  • 如果你正在导入已安装在不同解释器或内核中的包，请选择正确的解释器。
  • 如果你正在使用可编辑安装，并且它目前设置为使用导入钩子，请考虑改用仅包含文件路径的 .pth 文件，以增强兼容性并确保更流畅的导入行为。在Pyright 文档中了解更多信息。

importCycleDetected

当 Pylance 检测到两个或多个模块之间存在循环依赖时，会发生此错误。

如何修复

尝试重新排序你的导入语句以打破循环依赖。

Pylance 诊断的严重性可以通过 python.analysis.diagnosticSeverityOverrides 设置进行自定义。有关更多信息，请查看设置参考。

后续步骤

  • 代码检查 - 启用、配置和应用各种 Python 代码检查器。
  • 调试 - 学习本地和远程调试 Python。
  • 测试 - 配置测试环境，发现、运行和调试测试。
  • 基本编辑 - 了解功能强大的 VS Code 编辑器。
  • 代码导航 - 快速浏览源代码。
  • 智能感知 - 了解智能感知功能。
  • Jupyter 支持 - 了解如何开始使用 Jupyter Notebook。
  • Python 扩展模板 - 创建一个扩展以集成你喜欢的 Python 工具。
06/12/2025