在 VS Code 中使用 Black 格式化 Python 代码

在 VS Code 中使用 Black 格式化 Python 代码的详细指南

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

这篇文章会详细说明：

1. Black 是什么、适合做什么
2. 安装 Black（虚拟环境 / 全局）
3. 在 VS Code 中配置 Black 为默认格式化工具
4. 保存时自动格式化
5. 配置 Black 参数（行宽等）
6. 常见问题与排错

一、Black 简介

Black 的核心理念：

• 只做格式，不改语义。
• 尽量减少可配置项，以统一风格。
• 通过命令行或编辑器扩展自动格式化。

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

• 保存文件 → 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 

这样做的好处：

• 每个项目可以使用各自版本的 Black，避免项目之间互相影响。
• 便于在 requirements.txt 或 pyproject.toml 中记录依赖版本。

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
   • 或其他你自定义的名字

选择正确解释器后：

• VS Code 使用该环境运行 Black、lint 工具、调试等。
• 若 Black 在此环境中安装成功，后面配置就能正常工作。

五、将 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" } 

说明：

• "[python]" 里的配置只对 Python 文件生效。
• editor.defaultFormatter 指定该语言由哪个扩展来执行格式化，ms-python.python 是官方 Python 扩展的 ID。

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

七、手动触发 Black 格式化

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

• 快捷键：
  • Windows / Linux：Shift+Alt+F
  • macOS：Shift+Option+F
• 或右键代码编辑区 → 选择「Format Document」

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

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

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

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

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

• pyproject.toml（推荐，现代项目标配）
• pyproject.toml 中 [tool.black] 段落

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

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

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

常见选项说明：

• line-length：最大行宽，默认 88，可改为如 100、120 等。
• target-version：目标 Python 版本，影响一些语法支持。
• skip-string-normalization：默认为 false，Black 会统一把字符串引号改为双引号。如果不想改引号，可以设为 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. 在 VS Code 中确认已选择正确解释器（Python: Select Interpreter）。
2. 查看 settings.json 中：
   • "python.formatting.provider": "black" 是否正确。
   • editor.formatOnSave 或 [python].editor.formatOnSave 是否为 true。
3. 手动执行「Format Document」，看看是否有错误提示。

确认 Black 已安装在当前项目使用的解释器中：

which python # 或 py -V 环境检查 python -m pip show black 

10.2 VS Code 提示找不到 Black

• 如果在 VS Code 自带的终端中运行找不到，但在系统终端中能找到，很可能是：
  • VS Code 当前使用的解释器不同；
  • 或 PATH 没有指向 Black 安装位置。
• 解决：
  • 重新选择解释器（Python: Select Interpreter），选中安装了 Black 的那个环境。
  • 尽量使用项目内虚拟环境，并在 VS Code 终端中激活它。

检查终端中是否能运行：

black --version 

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

建议的过渡策略：

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

十一、总结步骤速查

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

1. 打开 VS Code，选择虚拟环境为 Python 解释器（Python: Select Interpreter）。
2. 安装 VS Code 的 Python 扩展（ms-python.python）。

在 pyproject.toml 中添加 Black 配置（可选但推荐）：

[tool.black] line-length = 100 target-version = ["py310"] 

启用保存自动格式化（推荐）：

"[python]": { "editor.formatOnSave": true, "editor.defaultFormatter": "ms-python.python" } 

在设置中选择 Black 为格式化器：

"python.formatting.provider": "black" 

在项目虚拟环境中安装 Black：

python -m venv .venv source .venv/bin/activate # 或对应平台命令 pip install black 

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