VSCode中Python格式化不生效，主因是未正确配置python.formatting.provider及对应格式化工具路径；需手动指定black或yapf，并确保其安装在当前选中的Python解释器环境中，且配置参数为数组格式，修改后需重新打开.py文件生效。
VSCode 里 Python 格式化不生效？先确认 python.formatting.provider 设对了
格式化没反应，大概率不是插件没装，而是 VSCode 压根没调用它。VSCode 的 Python 扩展本身不带格式化引擎，它只是个“调度员”，真正干活的是你指定的外部工具（比如 black 或 yapf）。必须手动告诉它用谁。
打开设置（Ctrl+,），搜 python.formatting.provider，选 black 或 yapf；或者直接改 settings.json：
{
"python.formatting.provider": "black",
"python.formatting.blackArgs": ["--line-length", "88"]
}
- 如果设成
auto，VSCode 会按环境里有没有black、yapf、autopep8顺序找，但行为不稳定，尤其多虚拟环境时容易误判 -
blackArgs和yapfArgs必须是数组形式，字符串会报错 - 改完设置后，**不用重启 VSCode，但要重新打开一个 .py 文件**，否则旧缓冲区可能沿用之前配置
Black 和 YAPF 装在哪儿？虚拟环境路径别搞混
VSCode 默认在当前工作区的 Python 解释器环境下找 black 或 yapf。如果你用的是 venv 或 conda 环境，但插件装在系统 Python 里，格式化必然失败——报错通常是：Command 'Python: Format Document' resulted in an error (command 'python.formatDocument' not found) 或更隐蔽的 ModuleNotFoundError: No module named 'black'。
- 先确认当前解释器路径：VSCode 左下角 Python 版本号 → 点击 → 选对你的
venv/bin/python或conda/envs/xxx/bin/python - 然后在这个解释器里装工具：
pip install black或pip install yapf（别用sudo pip，也别在 base 环境乱装） - 验证是否装对：终端激活该环境后运行
which black，输出路径应和 VSCode 右下角显示的 Python 路径在同一父目录下
Black 和 YAPF 行为差异大，别指望一键切换不改代码
Black 是“强约束”风格：不接受大部分格式参数，只认 --line-length 和 --skip-string-normalization；YAPF 是“可配置”风格：靠 .style.yapf 文件控制缩进、空行、括号换行等细节。两者对同一段代码的输出可能完全不同，尤其涉及长表达式、字典/列表推导、类型注解时。
立即学习“Python免费学习笔记（深入）”；
- Black 会把
def f(a: int, b: str) -> List[Dict[str, Any]]:拆成多行，YAPF 默认不会 - Black 强制单引号，YAPF 默认双引号；想统一引号，YAPF 需显式配
single_quotes = True - 团队协作时，如果已有
.yapf配置，切 Black 前最好跑一遍black . --check看哪些文件会被动改，避免 PR 里全是格式噪音
保存时自动格式化失效？检查 editor.formatOnSave 和语言模式
很多人开了 editor.formatOnSave 却没效果，问题常出在两个地方：一是该设置被作用域覆盖（比如只在 Markdown 文件生效），二是当前文件没被识别为 Python。
- 确保全局或工作区设置了：
"editor.formatOnSave": true - 检查右下角语言模式是不是
Python（不是Plain Text或Py）；点一下切换，或按Ctrl+Shift+P→ 输入Change Language Mode→ 选Python - 如果用了 Pylance 或 Ruff，它们可能自带格式化能力，和 Black/YAPF 冲突；关掉
python.formatting.provider外的其他格式化相关配置（如ruff.format.enable）
最麻烦的情况是项目里同时有 pyproject.toml（Black 配置）和 .style.yapf，VSCode 可能读取混乱。这时优先以 settings.json 中的 python.formatting.provider 为准，其他配置文件仅作工具链补充，别指望它们自动联动。
