🚀 在 VS Code 中！

在 VS Code 中格式化 Python

格式化通过强制执行特定的规则和约定（例如行距、缩进和运算符周围的空格）使源代码更易于人类阅读，代码变得在视觉上更有条理且更易于理解。您可以在 autopep8 页面上查看示例。请记住，格式化不会影响代码本身的功能。

代码检查 通过分析代码中常见的语法、样式和功能错误以及非常规的编程实践，帮助防止错误。尽管格式化和代码检查之间存在少量重叠，但这两种功能是互补的。

选择格式化程序

在 VS Code 市场 中搜索您选择的格式化程序扩展。

Microsoft 发布了以下格式化扩展

格式化程序 扩展
autopep8 https://marketplace.visualstudio.com/items?itemName=ms-python.autopep8
Black Formatter https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter

社区提供的格式化程序扩展

格式化程序 扩展
Ruff https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff
yapf https://marketplace.visualstudio.com/items?itemName=eeyore.yapf

此外，以下是支持导入排序的格式化程序扩展

格式化程序 扩展
Ruff https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff
isort https://marketplace.visualstudio.com/items?itemName=ms-python.isort

注意：如果您在上面表格或 Marketplace 中找不到您首选的格式化程序，您可以通过扩展添加对其的支持。您可以使用 Python 扩展模板 将新的 Python 工具集成到 VS Code 中。

设置默认格式化程序

安装格式化程序扩展后，您可以按照以下步骤在 VS Code 中将其选择为 Python 文件的默认格式化程序

  1. 在 VS Code 中打开一个 Python 文件。
  2. 右键单击编辑器以显示上下文菜单。
  3. 选择使用...格式化文档。
  4. 从下拉菜单中选择配置默认格式化程序...。
  5. 从列表中选择您首选的格式化程序扩展。

或者，您可以通过在 User settings.json 文件中的 [python] 作用域下设置 "editor.defaultFormatter"，将其设置为所有 Python 文件的默认格式化程序。您可以使用首选项：打开用户设置 (JSON) 命令打开 settings.json。

例如，要将 Black Formatter 设置为默认格式化程序，请将以下设置添加到您的 User settings.json 文件

  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter"
  }

为了将格式化程序扩展设置为导入排序器，您可以在 User settings.json 文件或 Workspace settings.json 文件中的 [python] 作用域下，在 "editor.codeActionsOnSave" 下设置您的首选项。您可以使用首选项：打开用户设置 (JSON) 和首选项：打开工作区设置 (JSON) 命令分别打开这些 settings.json 文件。这将为所有 Python 文件启用保存时导入排序。

例如，要将 Ruff 设置为您首选的导入排序器，您可以将以下设置添加到您的 User settings.json 或您的 Workspace settings.json 文件

{
  "[python]": {
    "editor.codeActionsOnSave": {
      "source.organizeImports.ruff": "explicit"
    }
  }
}

格式化你的代码

您可以通过右键单击编辑器并选择格式化文档来格式化您的代码，或者使用 ⇧⌥F (Windows Shift+Alt+F, Linux Ctrl+Shift+I) 键盘快捷键。

您还可以将以下设置添加到您的 User settings.json 文件，以启用保存时格式化您的代码

  "[python]": {
    "editor.formatOnSave": true
  }

常规格式化设置

您可以参考每个格式化程序扩展的 README，以获取有关支持设置的更多详细信息。大多数格式化程序扩展都支持以下设置

设置后缀
 默认值 描述
args [] 要传递给格式化程序的参数。每个参数都应作为数组中的单独字符串传递。
例如
black-formatter.args: ["--line-length", "100"]
importStrategy useBundled 设置为 useBundled 时，扩展使用它附带的工具版本。设置为 fromEnvironment 时，它会尝试首先从您选择的 Python 环境加载，否则会回退到捆绑版本。
path "" 要用于格式化的格式化程序二进制文件的路径。注意： 使用此选项可能会减慢格式化速度。
interpreter [] 设置为 Python 可执行文件的路径时，扩展将使用该路径来启动格式化程序服务器及其子进程。
showNotifications off 控制扩展何时显示通知。支持的值为 off、always、onError 和 onWarning。

排查格式化问题

如果格式化失败，请检查以下可能的原因

问题 解决方案
有多个格式化程序可用于 Python 文件。 按照上面的部分中的说明设置默认格式化程序。
没有“使用...格式化文档”选项可用。 如果您在上下文菜单中看不到此选项，则可能是您没有在 VS Code 中安装或启用格式化程序扩展。参考选择格式化程序部分，了解如何安装 Python 格式化程序扩展。
格式化程序的自定义参数不正确。 检查相应的 <formatter>.path 设置是否不包含参数，以及 <formatter>.args 是否包含单个顶级参数元素的列表。
显示“您有已弃用的代码检查或格式化设置”通知。 如果您看到此通知，则表示您在 VS Code 中有 python.linting 或 python.formatting 等设置。Python 扩展不再支持这些设置，因为 代码检查和格式化支持已迁移到工具扩展。
使用 Black Formatter 时，格式化选定内容命令失败。 black 不支持格式化代码段。要解决此限制，您可以禁用粘贴时格式化，并将 formatOnSave 设置为使用以下设置格式化整个文件："[python]": {"editor.formatOnPaste": false, "editor.formatOnSaveMode": "file"}。
即使我安装了格式化程序扩展，格式化也不起作用。 格式化可能会因多种原因而失败，例如代码中的语法问题、使用了不受支持的 Python 版本或格式化程序配置不正确。检查格式化程序扩展的“输出”通道以了解格式化程序失败的原因（在命令面板中运行输出：聚焦于输出命令，然后选择格式化程序扩展通道）。

注意：如果您在上面未找到您首选的格式化程序，则可以通过扩展添加支持。Python 扩展模板 使将新的 Python 工具集成到 VS Code 中变得容易。

后续步骤

  • 调试 - 了解如何在本地和远程调试 Python。
  • 测试 - 配置测试环境，发现、运行和调试测试。
  • 基本编辑 - 了解功能强大的 VS Code 编辑器。
  • 代码导航 - 在源代码中快速移动。
  • Python 扩展模板 - 创建一个扩展以将您最喜欢的代码检查器集成到 VS Code 中。
02/06/2025