VSCode中Black不生效需三步：确认Python解释器已选中并安装black、settings.json中配置"editor.formatOnSave": true、"[python]": {"format.enable": true}和"python.formatting.provider": "black"，且pyproject.toml须置于项目根目录并含[tool.black]段，修改后需重载窗口。
VSCode 里 Black 不是装完插件就自动工作的——必须让编辑器明确知道“用哪个 Python 环境里的 black 来格式化当前 .py 文件”，否则按 Shift+Alt+F 或保存时完全没反应。
Black 没反应？先确认 VSCode 正在用你装了 black 的解释器
常见错误现象：Format Document 点击无响应，或弹出 “no formatter installed for 'python'”；右下角显示的 Python 版本路径里根本没装 black。
- 按
Ctrl+Shift+P（Mac 为Cmd+Shift+P），运行Python: Select Interpreter，选中你项目实际使用的环境（比如./venv/bin/python或~/miniconda3/envs/myproj/bin/python） - 在 VSCode 集成终端中执行：
python -m black --version—— 有输出才说明 black 已安装在这个解释器下 - 如果用 conda，务必先
conda activate myenv再pip install black；直接pip install black在未激活环境下装，VSCode 看不见 - 别依赖全局
which black的结果：VSCode 启动时读的是解释器环境的PATH，不是你 shell 的
settings.json 里这三行缺一不可
光开 editor.formatOnSave 不够，VSCode 还得知道“派谁去干”，且只对 Python 文件生效。
- 必须写进
settings.json（不是图形界面点选），推荐放在项目根目录的.vscode/settings.json中，避免污染全局设置 - 这三行要同时存在：
{
"editor.formatOnSave": true,
"[python]": {
"format.enable": true
},
"python.formatting.provider": "black"
}
-
"[python]"是语言专属配置块，漏掉方括号或引号会导致整段失效 - 别写错成
python.formatting.blackProvider或python.formatting.defaultProvider——只有python.formatting.provider是有效键名 -
editor.formatOnType建议保持false：Black 不支持实时格式化，开它反而卡顿或报错
pyproject.toml 配置被忽略？路径和重启是关键
VSCode 的 Python 扩展只认工作区根目录下的 pyproject.toml，且必须含 [tool.black] 段。改了配置不生效，八成是缓存没刷新。
立即学习“Python免费学习笔记（深入）”；
- 文件名必须是
pyproject.toml，不能是black.toml、.black或放在src/下 - 最小可用配置示例：
[tool.black] line-length = 88 skip-string-normalization = true exclude = ''' /( \.git | __pycache__ | venv )/ '''
- 改完
pyproject.toml后，必须执行Ctrl+Shift+P→Developer: Reload Window，否则旧配置仍被缓存使用 -
python.formatting.blackArgs只能追加参数，不能覆盖pyproject.toml里的配置——比如你在 toml 里设了line-length = 100，再在 settings 里写["--line-length", "88"]也无效
格式化只作用于当前文件，别指望它扫整个项目
VSCode 的设计就是单文件触发：保存 a.py，只格式化 a.py；不会顺手把 b.py 或 src/ 下所有文件一起处理。
- 想批量格式化？老实用命令行：
black src/ --check（校验）或black src/（执行） - VSCode 内没有原生的“格式化整个工作区”功能；第三方插件如
ms-python.black-formatter提供Black: Format Workspace命令，但它仍受限于当前解释器环境，且不保证稳定 - 如果保存后部分代码没变，不是 bug——Black 对语法合法但风格已符合的代码不做任何修改
最常被跳过的一步：改完 pyproject.toml 或切换了解释器后，没重载窗口。VSCode 不会热更新这些配置，缓存行为极其顽固。
