你写代码 5 分钟，调格式半小时？让 Black 帮你结束这场争论。
一、为什么需要 Black
写 Python 的人多少都经历过这样的场景：Code Review 时，功能逻辑一句没挑，缩进、空行、引号风格倒是讨论了二十分钟。"这里该不该换行？""单引号还是双引号？""两个空行还是一个？"
PEP 8 只给了规范，没给答案的边界。而 Black 的口号是 "The uncompromising code formatter" —— 不妥协的代码格式化器。它不给你选择题：任何符合语法的代码进来，出去只有一个样子。
Black 的几个特点：
-
• 快：基于官方
ast，格式化速度以毫秒计； -
• 稳定：输出结果幂等，格式化两次结果一致；
-
• 省心：几乎没有可配置项，团队风格争论直接终结；
-
• 主流：Instagram、Python 官方文档等诸多项目在用，早已被纳入官方推荐工具链。
二、安装 Black
1. 给环境装 Black
Black 是一个普通的 Python 包，在项目虚拟环境里装一份（这是 VS Code 插件默认会调用的位置）：
python -m pip install black
如果你还想在终端里随时手动使用 black 命令，可以额外用 pipx 装一份全局的：
pipx install black
⚠️ 注意：
pipx install black装出来的命令行工具，VS Code 的 Black Formatter 插件默认找不到。插件优先使用当前 Python 解释器对应环境里的 black。所以项目环境里那一句python -m pip install black不能省。
验证安装：
python -m pip show black
# Name: black
# Version: 24.x.x
备注：
如果失败，超时
换国内镜像安装
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)，加入：
{
"[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 显式指定：
{
"black-formatter.path": ["/Users/你的用户名/.local/bin/black"]
}
或者让插件跟着某个固定解释器走：
{
"black-formatter.interpreter": ["python3"]
}
3. 看看效果
随手写一段"放飞自我"的代码：
def hello( name,age ):
x={'a':1,'b':2}
if age>18:
return f"你好, {name} 成年了 "
else :
return '未成年'
按下 Ctrl/Cmd + S，一瞬间变成：
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 里：
[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：
[tool.isort]
profile = "black"
VS Code 中可配合保存时自动整理 import：
"editor.codeActionsOnSave": {
"source.organizeImports": "explicit"
}
4. 团队里有人没装 Black，提交的代码风格还是乱的？
上 pre-commit，把格式化卡在提交前：
# .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、同事三处一致
|
配完这一套，你唯一需要关心的就是代码逻辑本身。至于格式——写得再放飞，保存键会替你收拾好。
写在最后
感谢阅读。如果你觉得有帮助，欢迎 点赞、在看、转发 三连。
「技海拾贝」 ，一个专注开发技巧、开发效率工具与工程实践的公众号。
