VSCode中Black不自动格式化Python需三者对齐：Python解释器路径与black安装环境一致、settings.json中显式配置"python.formatting.provider": "black"和"editor.formatOnSave": true、pyproject.toml置于项目根目录且含[tool.black]段，缺一不可。

python.formatting.provider 必须设为 black，否则 VSCode 根本不会调用 Black——哪怕你装了插件、终端里能跑 black --version，也完全没反应。

Python 解释器路径和 Black 安装环境必须对齐

VSCode 只在 python.defaultInterpreter 指向的环境里执行 python -m black，它不查全局 PATH，也不跨环境找包。

• 按 Ctrl+Shift+P（Mac 为 Cmd+Shift+P），运行 Python: Select Interpreter，确认路径指向你实际装了 black 的环境（如 ./venv/bin/python 或 ~/miniconda3/envs/myenv/bin/python）
• 在 VSCode 集成终端中运行 python -m black --version：有输出才算真正可用；若报 ModuleNotFoundError: No module named 'black'，立刻在这个环境下重装：pip install black
• 用 conda？别只在 base 装 black，必须先 conda activate myenv 再 pip install black

settings.json 里这三行缺一不可

editor.formatOnSave 控制是否保存时触发，[python] 块限定作用域，python.formatting.provider 指定工具——漏掉任意一个，格式化就静默失效。

• 打开 Preferences: Open Settings (JSON)，加这三行（注意引号、逗号、方括号全都要）：
• "editor.formatOnSave": true
• "[python]": { "editor.formatOnSave": true }
• "python.formatting.provider": "black"
• 删掉 python.formatting.blackArgs 这类冗余配置——除非你真要传额外参数（比如 --skip-string-normalization），否则它大概率被忽略，还容易拼错成 python.formatting.blackargs（小写 a）导致静默失效

pyproject.toml 必须放在项目根目录且含 [tool.black]

VSCode 的 Python 扩展只认工作区根目录下的 pyproject.toml，且必须包含合法的 [tool.black] 段。写成 .black、black.toml、或放在 src/ 里，它直接无视。

Claw Code Suite (Python-Only Edition)

仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...

下载

• 最小可用配置示例（存为项目根目录下的 pyproject.toml）：
• [tool.black]
• line-length = 88
• skip-string-normalization = true
• exclude = '''/( \.git | __pycache__ | venv )/'''
• 改完配置后，必须执行 Ctrl+Shift+P → Developer: Reload Window，否则旧缓存会让新规则不生效
• python.formatting.blackArgs 无法覆盖 line-length 或 exclude——这些全由 pyproject.toml 控制，这点非常容易被忽略

格式化不生效？先排除冲突扩展和错误路径

常见静默失败不是 Black 本身的问题，而是其他格式化器抢了权限，或 VSCode 启动时根本没加载到你的配置。

立即学习“Python免费学习笔记（深入）”；

• 禁用 autopep8、yapf 等冲突扩展：在扩展面板搜名字，右键 → Disable Workspace
• 别依赖 which black 的结果：VSCode 启动时读的是解释器环境的 SYS.PATH，不是你 shell 的 PATH
• 如果右下角 Python 版本显示路径正确，但按 Shift+Alt+F 弹出 no formatter installed for 'python'，说明 python.formatting.provider 没设对，或拼写错误（比如写成 python.formatting.blackProvider）
• 手动验证是否走对流程：在终端里跑 black --diff your_file.py，再对比 VSCode 里保存后的效果；不一致，基本就是环境或配置没对齐

改完所有配置后，最容易被忽略的是重载窗口——不点 Developer: Reload Window，VSCode 会继续用旧缓存，连 pyproject.toml 里的 line-length 改了都看不到效果。