告别代码风格之争：在 VS Code 中用 Black 一键格式化 Python

你写代码 5 分钟，调格式半小时？让 Black 帮你结束这场争论。

‍

一、为什么需要 Black

写 Python 的人多少都经历过这样的场景：Code Review 时，功能逻辑一句没挑，缩进、空行、引号风格倒是讨论了二十分钟。"这里该不该换行？""单引号还是双引号？""两个空行还是一个？"

PEP 8 只给了规范，没给答案的边界。而 Black 的口号是 "The uncompromising code formatter" ------ 不妥协的代码格式化器。它不给你选择题：任何符合语法的代码进来，出去只有一个样子。

Black 的几个特点：

• 快：基于官方 ast，格式化速度以毫秒计；
• 稳定：输出结果幂等，格式化两次结果一致；
• 省心：几乎没有可配置项，团队风格争论直接终结；
• 主流：Instagram、Python 官方文档等诸多项目在用，早已被纳入官方推荐工具链。

‍

github.com/microsoft/v...

‍

二、安装 Black

1. 给环境装 Black

Black 是一个普通的 Python 包，在项目虚拟环境里装一份（这是 VS Code 插件默认会调用的位置）：

bash 复制代码

python -m pip install black

‍

如果你还想在终端里随时手动使用 black 命令，可以额外用 pipx 装一份全局的：

bash 复制代码

pipx install black

⚠️ 注意：pipx install black 装出来的命令行工具，VS Code 的 Black Formatter 插件默认找不到 。插件优先使用当前 Python 解释器对应环境里的 black。所以项目环境里那一句 python -m pip install black 不能省。

‍

验证安装：

bash 复制代码

python -m pip show black
# Name: black
# Version: 24.x.x

‍

备注：

如果失败，超时

‍

换国内镜像安装

java 复制代码

python -m pip install black -i https://mirrors.aliyun.com/pypi/simple/

‍

三、在 VS Code 中配置 Black

1. 装好扩展（三个）

到扩展市场安装 Microsoft 官方出品的：

• Python（ms-python.python）------ 语言基础支持
• Black Formatter （ms-python.black-formatter）------ 格式化本体，必装
• Pylance（ms-python.vscode-pylance）------ 可选，顺带收获智能补全

‍

‍

2. 把 Black Formatter 设为默认格式化器

打开设置文件：Ctrl/Cmd + Shift + P → 输入 Open User Settings (JSON)，加入：

json 复制代码

{
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter",
    "editor.formatOnSave": true
  },
  "black-formatter.args": [
    "--line-length",
    "88"
  ]
}

逐行解释：

| 配置项 | 作用 | | --- | --- | | editor.defaultFormatter | 指定 Python 文件由 Black Formatter 插件 格式化 | | editor.formatOnSave | 保存即格式化 ，本方案的灵魂 | | black-formatter.args | 传给 Black 的命令行参数（等价于命令行的 black --line-length 88） |

‍

‍

‍

只想对当前项目生效的话，把上面这段写进项目根目录的 .vscode/settings.json，还能随代码仓库同步给同事。

找不到 black 时怎么办？ 如果你坚持用 pipx 全局安装（不想在每个虚拟环境里装一遍），可以用 black-formatter.path 显式指定：

json 复制代码

{
  "black-formatter.path": ["/Users/你的用户名/.local/bin/black"]
}

或者让插件跟着某个固定解释器走：

json 复制代码

{
  "black-formatter.interpreter": ["python3"]
}

‍

3. 看看效果

随手写一段"放飞自我"的代码：

python 复制代码

def  hello( name,age ):
        x={'a':1,'b':2}
        if age>18:
                return f"你好, {name}  成年了    "
        else :
            return '未成年'

‍

按下 Ctrl/Cmd + S，一瞬间变成：

python 复制代码

def hello(name, age):
    x = {"a": 1, "b": 2}
    if age > 18:
        return f"你好, {name}  成年了    "
    else:
        return "未成年"

注意 Black 只管格式、不管字符串内容------字符串里的空格它不会动。

也可以手动触发：Shift + Alt + F（macOS 为 Shift + Option + F），或右键菜单里的 "Format Document"。

‍

四、进阶配置：pyproject.toml

Black 为数不多的可配置项，写在项目根目录的 pyproject.toml 里：

toml 复制代码

[tool.black]
line-length = 100
target-version = ["py310"]
include = '\.pyi?$'
extend-exclude = '''
/(
    \.git
  | \.venv
  | build
  | dist
)/
'''

常见选项说明：

• line-length：行宽，默认 88。比 PEP 8 的 79 稍宽，实际项目中很多人设 100 或 120；
• target-version：目标 Python 版本，影响语法输出细节；
• extend-exclude：排除目录，避免格式化虚拟环境、构建产物。

配置好后，命令行和 VS Code 会自动读取同一份配置，保证"编辑器里看到的"和"CI 里检查的"完全一致。

‍

五、常见坑与排查

1. 保存时没反应？

按三步排查：

2. 报错 "Formatting with black failed" 或提示找不到 black？

• 若你用 pipx install black 安装，插件默认找不到它，解决办法见第三节"找不到 black 时怎么办"；
• 若 settings.json 里还残留 python.formatting.provider: "black" 这类旧配置，删掉它------该配置已在新版 Python 扩展中弃用；
• 用命令面板执行 Format Document With... → Configure Default Formatter，选 Black Formatter，让 VS Code 自己写对配置。

3. 和 isort 打架？

isort 负责 import 排序，Black 负责格式，两者配合需要让 isort 的 profile 设为 black：

toml 复制代码

[tool.isort]
profile = "black"

VS Code 中可配合保存时自动整理 import：

json 复制代码

"editor.codeActionsOnSave": {
    "source.organizeImports": "explicit"
}

4. 团队里有人没装 Black，提交的代码风格还是乱的？

上 pre-commit，把格式化卡在提交前：

yaml 复制代码

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/psf/black
    rev: 24.4.2
    hooks:
      - id: black

然后 pre-commit install，从此代码库风格统一由工具保证，而不是靠自觉。

‍

六、小结

| 环节 | 工具/配置 | 一句话 | | --- | --- | --- | | 格式化引擎 | Black（装在项目环境） | 不妥协，输出唯一 | | 编辑器 | VS Code + Black Formatter 插件 | defaultFormatter 指向 ms-python.black-formatter | | 自动化 | editor.formatOnSave | 保存即格式化 | | 团队统一 | pyproject.toml + pre-commit | 本地、CI、同事三处一致 |

配完这一套，你唯一需要关心的就是代码逻辑本身。至于格式------写得再放飞，保存键会替你收拾好。

‍

写在最后

感谢阅读。如果你觉得有帮助，欢迎 点赞、在看、转发 三连。

「技海拾贝」 ，一个专注开发技巧、开发效率工具与工程实践的公众号。

‍