python

关注公众号 jb51net

关闭
首页 > 脚本专栏 > python > VSCode Black格式化Python代码

在VS Code中使用Black格式化Python代码详细说明

作者：Tipriest_

格式化使源代码更容易被人类阅读,下面这篇文章主要介绍了在VS Code中使用Black格式化Python代码的相关资料,文中通过代码介绍的非常详细,需要的朋友可以参考下

Black 是目前 Python 社区最流行的自动格式化工具之一，它的特点是“极少配置、强制风格”：你把代码交给 Black，它按照一套统一规则帮你排版，从此团队不用再纠结“空格还是换行”。

一、Black 简介

Black 的核心理念：

在 VS Code 中使用 Black 的典型流程是：

二、安装 Black

在 VS Code 中使用 Black，底层还是依赖系统/虚拟环境中的 black 命令。因此第一步是安装 Black。

2.1 在项目虚拟环境中安装（推荐）

# 创建虚拟环境（示例）
python -m venv .venv

# 激活虚拟环境（Windows）
.\.venv\Scripts\activate

# 激活虚拟环境（macOS / Linux）
source .venv/bin/activate

# 安装 black
pip install black

这样做的好处：

2.2 全局安装（不太推荐，但可以）

pip install --user black

适合个人简单脚本项目，但团队协作时，还是建议使用虚拟环境或者在 pyproject.toml 中锁定 Black 版本。

三、VS Code 基础配置：启用 Python 扩展

在 VS Code 中使用 Black 之前，需要先装好 Python 扩展。

  1. 打开 VS Code
  2. 左侧点击「扩展（Extensions）」图标
  3. 搜索 Python，安装 Microsoft 官方的 Python 扩展
  4. 推荐同时安装 Pylance 扩展（类型提示、补全更好）

安装好后，VS Code 会自动识别 .py 文件的 Python 语言特性。

四、在 VS Code 中选择解释器（指向 Black 所在环境）

如果你把 Black 安装在虚拟环境里，需要让 VS Code 知道用哪个 Python 解释器（也就是哪个虚拟环境）。

  1. 打开 Python 项目
  2. 按 Ctrl+Shift+P（macOS 上 Cmd+Shift+P）打开命令面板
  3. 输入并选择：Python: Select Interpreter
  4. 在列表中选择你创建的虚拟环境，比如：
    • .venv
    • venv
    • 或其他你自定义的名字

选择正确解释器后：

五、将 Black 设置为默认格式化工具

VS Code 支持多个格式化工具（如 autopep8、yapf、Black），需要显式告诉 VS Code：Python 用 Black 来格式化。

5.1 通过设置图形界面配置（适合初学）

  1. 打开设置：
    • 方式一：左下角齿轮 → Settings
    • 方式二：快捷键 Ctrl+, / Cmd+,
  2. 右上角搜索框中输入：Python Formatting Provider
  3. 在下拉选项中选择：black

若搜索不到该选项，可以搜索 formatting provider 或换成中文关键字（如“格式化”），确保 Python 扩展已安装。

5.2 直接编辑settings.json（适合熟悉 VS Code 配置的人）

  1. Ctrl+Shift+P / Cmd+Shift+P
  2. 输入：Preferences: Open Settings (JSON)
  3. 在 JSON 中添加或修改如下内容（注意逗号语法）：
{
    // ... 其他设置 ...

    // 使用 Black 作为 Python 格式化工具
    "python.formatting.provider": "black"
}

保存后生效。

六、启用「保存时自动格式化」

为了真正“无感”使用 Black，建议开启保存即自动格式化。

6.1 全局启用保存自动格式化（所有语言）

  1. 设置中搜索：Format On Save
  2. 勾选：Editor: Format On Save（editor.formatOnSave）

这意味着所有支持格式化的文件在保存时都会被对应的格式化工具处理。

6.2 只针对 Python 启用（更精细控制）

如果只希望 Python 自动格式化，可以在 settings.json 中使用语言特定配置：

{
    // 全局不自动格式化
    "editor.formatOnSave": false,

    "[python]": {
        "editor.formatOnSave": true,
        "editor.defaultFormatter": "ms-python.python"  // 使用 Python 扩展的格式化
    },

    "python.formatting.provider": "black"
}

说明：

保存 settings.json 后，打开一个 .py 文件，试着写点不规整的代码，然后保存，看是否会被 Black 重新排版。

七、手动触发 Black 格式化

即使不开保存自动格式化，你也可以随时手动触发格式化：

如果出现弹窗提示「选择格式化程序」：

  1. 选择 Python 格式化（一般会有 Python 或 Black 等选项）
  2. 如果没看到 Black，需要确认上面几步是否已正确安装 / 配置。

八、配置 Black 的行为（行宽等）

Black 的设计理念是“少配置”，但仍然提供了几个核心参数，最常用的是 line-length（最大行宽）。

Black 支持以下配置文件之一：

8.1 在pyproject.toml中配置 Black（推荐）

在项目根目录创建或编辑 pyproject.toml：

[tool.black]
line-length = 100
target-version = ["py310"]
skip-string-normalization = true

常见选项说明：

Black 在运行时会自动从当前目录向上查找 pyproject.toml 中的 [tool.black] 配置段。

8.2 不建议在 VS Code 里直接改 Black 命令参数

以前的 Python 扩展支持通过 python.formatting.blackArgs 添加 Black 参数，例如：

"python.formatting.blackArgs": [
    "--line-length", "100"
]

在新版本中，更推荐通过 pyproject.toml 来管理 Black 的配置，实现“编辑器/CI 一致”，避免 VS Code 和命令行用到不同的格式规则。

九、在命令行与 VS Code 中保持一致

如果你在 CI 或命令行也会运行 Black，强烈建议：

  1. 在项目根目录使用 pyproject.toml 统一配置 Black。
  2. VS Code 只是调用安装在虚拟环境里的那个 Black，可自动读取同一份配置。

命令行示例：

# 在项目根目录
black .
# 或者只格式化某些目录
black src tests

VS Code 保存时用的规则会和命令行一致。

十、常见问题与排错

10.1 保存时没有自动格式化

排查步骤：

  1. 确认 Black 已安装在当前项目使用的解释器中：
    which python  # 或 py -V 环境检查
python -m pip show black
  2. 在 VS Code 中确认已选择正确解释器（Python: Select Interpreter）。
  3. 查看 settings.json 中：
    • "python.formatting.provider": "black" 是否正确。
    • editor.formatOnSave 或 [python].editor.formatOnSave 是否为 true。
  4. 手动执行「Format Document」，看看是否有错误提示。

10.2 VS Code 提示找不到 Black

10.3 Black 修改了很多代码，看不习惯

建议的过渡策略：

  1. 先在一个小项目或新模块上试用 Black，熟悉风格。
  2. 在老项目中，可以先对单个目录或文件手动格式化，而不是一次性改全仓库。
  3. 团队协作建议一次性全局格式化并单独提一个 PR，让后续代码评审不被大量“格式 diff”干扰。

十一、总结步骤速查

如果你只想快速配置好，可以按下面 checklist 操作：

  1. 在项目虚拟环境中安装 Black：
    python -m venv .venv
source .venv/bin/activate  # 或对应平台命令
pip install black
  2. 打开 VS Code，选择虚拟环境为 Python 解释器（Python: Select Interpreter）。
  3. 安装 VS Code 的 Python 扩展（ms-python.python）。
  4. 在设置中选择 Black 为格式化器：
    "python.formatting.provider": "black"
  5. 启用保存自动格式化（推荐）：
    "[python]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "ms-python.python"
}
  6. 在 pyproject.toml 中添加 Black 配置（可选但推荐）：
    [tool.black]
line-length = 100
target-version = ["py310"]

配置完成后，写一段乱排版的 Python 代码，按 Ctrl+S 保存，你就能看到 Black 自动把它“修理得整整齐齐”。

总结

到此这篇关于在VS Code中使用Black格式化Python代码的文章就介绍到这了,更多相关VSCode Black格式化Python代码内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

您可能感兴趣的文章:
阅读全文